Authentication

Authentication is the process by which an identity is presented to the application. It ensures that the entity making the request has the proper credentials to access the API.

Dotkernel API identities are delivered to the application from the client through the Authorization request. If it is present, the application tries to find and assign the identity to the application. If it is not presented, Dotkernel API assigns a default guest identity, represented by an instance of the class Mezzio\Authentication\UserInterface.

Configuration

Authentication in Dotkernel API is built around the mezzio/mezzio-authentication-oauth2 component and is already configured out of the box. But if you want to dig more, the configuration is stored in config/autoload/local.php under the authentication key.

You can check the mezzio/mezzio-authentication-oauth2 configuration part for more info.

How it works

Dotkernels API authentication system can be used for SPAs (single-page applications), mobile applications, and simple, token-based APIs. It allows each user of your application to generate API tokens for their accounts.

The authentication happens through the middleware in the Api\App\Middleware\AuthenticationMiddleware.

Database

When you install Dotkernel API for the first time, you need to run the migrations and seeders. All the tables required for authentication are automatically created and populated.

In Dotkernel API, authenticated users come from either the admin or the user table. We choose to keep the admin table separated from the users to prevent users of the application from accessing sensitive data, which only the administrators of the application should access.

The oauth_clients table is pre-populated with the default admin and frontend clients with the same password as their names (we recommend you change the default passwords).

As you guessed each client serves to authenticate admin or user.

Another table that is pre-populated is the oauth_scopes table, with the api scope.

Issuing API Tokens

Token generation in Dotkernel API is done using the password grant_type scenario, which in this case allows authentication to an API using the user's credentials (generally a username and password).

The client sends a POST request to the /security/generate-token with the following parameters:

grant_type = password.
client_id = column name from the oauth_clients table
client_secret = column secret from the oauth_clients table
scope = column scope from the oauth_scopes table
username = column identity from table admin/user
password = column password from table admin/user

POST /security/generate-token HTTP/1.1
Accept: application/json
Content-Type: application/json
{
  "grant_type": "password",
  "client_id": "frontend",
  "client_secret": "frontend",
  "scope": "api",
  "username": "test@dotkernel.com",
  "password": "dotkernel"
}

The server responds with a JSON as follows:

{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
    "refresh_token": "def5020087199939a49d0f2f818..."
}

Next time when you make a request to the server to an authenticated endpoint, the client should use the Authorization header request.

GET /users/1 HTTP/1.1
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

Refreshing tokens

Dotkernel API can refresh the access token, based on the expired access token's refresh_token.

The clients need to send a POST request to the /security/refresh-token with the following request

POST /security/refresh-token HTTP/1.1
Accept: application/json
Content-Type: application/json
{
  "grant_type": "refresh_token",
  "client_id": "frontend",
  "client_secret": "frontend",
  "scope": "api",
  "refresh_token" : "def5020087199939a49d0f2f818..."
}