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
.
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.
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
.
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.
Token generation in DotKernel API is done using the password
grand_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
tableclient_secret
= column secret
from the oauth_clients
tablescope
= column scope
from the oauth_scopes
tableusername
= 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...
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..."
}
The server responds with a JSON as follows:
{
"token_type": "Bearer",
"expires_in": 86400,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
"refresh_token": "def5020087199939a49d0f2f818..."
}