Download the PHP package jot/hf-shield without Composer

hf-shield

A module for authentication and authorization management using OAuth 2.0, with robust support for scope hierarchy and authentication flow.

TL/DR

Build for:

• OAuth2 authentication
• Cookie-based authentication over OAuth2 JWT Token
• Passkey registration and authentication
• WhatsApp authentication with OTP
• Automatic Swagger documentation
• Easy-to-use code generators

Copy the docker-compose.yml file to your project directory and replace the values in the .env file and start the environment.

Authenticating

JWT Bearer token

Start a new session

See .env HF_SESSION settings

Registering a passkey

Client challenging

Registering authenticator

Authenticate a passkey

Start challenge

Authenticate

This will redirect user for HF_SESSION redirect_uri configuration

Authenticate a WhatsApp number

You will receive the otp id in response and a code on your whatsapp that you must enter in the next step.

Validating the OTP

For a JWT token

To start a new session

Table of Contents

1. Introduction
2. Installation
3. Configuration
4. Translations
5. Defining Permissions
6. Creating migrations
7. Code Generators

Introduction

hf-shield is a module designed to facilitate the implementation of authentication and scope-based access control. It follows the guidelines of the OAuth 2.0 protocol and is especially useful for distributed systems, multi-tenant applications, and APIs that require complex permission hierarchies.

With customizable flows and well-defined validations, hf-shield offers a secure and scalable way to ensure access to resources, with validations focused on tokens, users, and clients.

Installation

Make sure your project uses PHP 8.2 or higher to ensure full compatibility.

To start using hf-shield, we suggest first installing hyperf/hyperf-skeleton.

During installation, accept the following packages:

• Redis client: hyperf/redis
• Config Center: option 3 ETCD
• AMQP Component hyperf/amqp
• Elasticsearch component hyperf/elasticsearch

After installation, navigate to the project directory and install this module:

Configuration

After installing the module, it needs to be configured. Make sure all dependencies are installed in your environment before starting the service.

You can set up your development environment using the docker-composer in this repository.

Dependencies

ETCD

After installing the service in your environment, run the command below:

REDIS

All cache management and rate-limiting are stored in Redis. After installing the service, run the command below:

With the configuration created, publish the credentials to ETCD with the following command:

ELASTICSEARCH

This application was built to use Elasticsearch as the main database.

After editing the .env file with the necessary credentials, register them in etcd:

SWAGGER

The code generation commands provided by the jot/hf-repository module already create controllers, entities, and data repositories with the necessary Swagger basics, which means the application is born with documented APIs.

RATE-LIMIT

Like Swagger, the jot/hf-repository module also implements the application's throttling configuration, which can be configured globally and reimplemented on a case-by-case basis in controller methods through their annotations.

OAUTH2

Finally, add the configurations for this module to work:

Example of config/autoload/hf_shield.php:

MIGRATIONS

After everything is configured, it's time to run the migrations so that the necessary indices for the authentication process are created:

Translations

hf-shield supports internationalization (i18n) using the hyperf/translation package. Translation files are located in storage/languages/{locale}/hf-shield.php.

Currently, the module supports the following languages:

• English (en)
• Brazilian Portuguese (pt_BR)

To add support for a new language, create a new translation file following the existing pattern.

Publishing Translations

Translations are automatically published when you run the package publish command:

Additional packages translations will be automatically published when you publish the hf-* package.

eg:

Customizing Translations

You can customize translations by editing the files in storage/languages/{locale}/messages.php. Translation keys are organized into the following categories:

• Command messages (for CLI)
• Form labels and prompts
• Exception messages

Defining Permissions

Scopes

Scopes are automatically implemented in controllers when created by the repo:controller or repo:crud command, but if you are implementing a controller manually, add the following docblock before the desired action:

Scope Naming Rules

Scopes should be named following this pattern: [service]:[resource]:[permission]

Examples:

To register the scopes in the application, run the command below:

Token Validation

If you want your action to be protected by token, you must add the middleware with the desired validation strategy:

Currently, there are 3 types of strategies for request validation:

1. BearerStrategy, validates the token through the Authorization header: Bearer {token}, generated by the /oauth/token endpoint.
2. SessionStrategy, validates the token from the access_token cookie, generated by the '/oauth/session' endpoint, which encrypts the token and sends it to the browser cookies.
3. SignedJwtStrategy, validates the token by its signature. In this case, the payload is sent in the JWT and validated by the user's signature.

API Validation Scope Hierarchy

The following diagram describes how the scope hierarchy works in hf-shield:

Authentication Flow

The authentication flow expected by hf-shield is described in the diagram below:

Creating migrations

Inspired by Laravel migrations, the hf-elastic module, part of the hf-shield ecosystem, allows you to create your indices quickly and dynamically, either manually or from JSON examples or JSON Schemas, and is prepared for all known types of Elasticsearch in version 8.x.

Creating a migration manually

As a result, it will create a file in the format YYYYmmdd-create-my_awesome_index.php in the migrations/elasticsearch directory.

The generated file will be in this format:

Creating a migration from an existing JSON

Let's use the JSON below as a model:

The JSON can be accessed from either a URL or a local directory.

As a final result, we will have the file with the following content:

The command tries to understand the data type in the JSON and represents it in the migration file, understanding internal objects and collections.

The settings property can be edited according to your needs in the config/autoload/hf_elastic.php file.

Running the migration

This command will search for all migrations and execute those that don't yet exist in elasticsearch.

You can also execute a single index if you wish:

Other migration commands

To see the list of elastic commands:

The commands execute all (and only) the files that are in the project's migrations/elasticsearch directory.

And for all commands, if you want to execute for just one index, simply add the option --index=index_name

Code Generators

Through the hf-repository module, hf-shield allows you to easily and practically create API endpoints with all the necessary resources to manage the content of existing Elasticsearch indices.

This component is prepared to generate the following types of files:

Controllers

Creates a controller for the project based on basic configurations from the .env file, allowing easy and efficient management of API versions:

When creating a controller, hf-repository creates all necessary actions to perform CRUD operations, applying the HTTP verbs GET, POST, PUT, DELETE, HEAD, and OPTIONS.

When executed, the command asks a series of questions to customize the controller creation:

As a result, the file app/Controller/V2/MyUserController.php is generated with the following content:

Entities, Services, and Repositories

The commands for entities, services, and repositories don't require additional questions, only creating their files in their respective directories.

For entities, additional classes will be created according to the index structure if it has sub-objects or collections.

Creates the file app/Repository/MyUserRepository.php

Creates the file app/Service/MyUserService.php

Results in the following file structure:

The entity files also receive Swagger attributes to compose the example data for documentation.