Authentication

Apiato utilizes the Laravel Passport package to provide a complete OAuth2 server. While this guide focuses on the Password Grant, you can use any other grant type supported by Passport.

OAuth2 offers various methods of authentication, known as grants. To learn how to choose the best grant type for your needs, read this article.

Important

This documentation assumes prior familiarity with OAuth2. If you're new to OAuth2, we recommend acquainting yourself with its general terminology and features before proceeding.

tip

To access a comprehensive list of available Passport endpoints, please refer to the app/Containers/Authentication/UI/API/Routes/passport.v1.private.php file.

Installation

To get started, you should execute the passport:install Artisan command. This command will create the encryption keys needed to generate secure access tokens. In addition, the command will create "personal access" and "password grant" clients which will be used to generate access tokens:

php artisan passport:install

You should see something like this:

Personal access client created successfully.
Client ID: 1
Client secret: Mo45lC2zhZWcMfDGmCbsw1OfasdCrc3wqQAeeYAO
Password grant client created successfully.
Client ID: 2
Client secret: nu8B2npfoR4hP6sWHaf90EvWUFe2EDYyJXGnCrso

Next you need to add the Password grant CLIENT_ID and CLIENT_SECRET to your .env file:

CLIENT_WEB_ID=2
CLIENT_WEB_SECRET=nu8B2npfoR4hP6sWHaf90EvWUFe2EDYyJXGnCrso

Password Grant Tokens

The OAuth2 password grant allows your other first-party clients, such as a mobile application, to obtain an access token using an email address / username and password. This allows you to issue access tokens securely to your first-party clients without requiring your users to go through the entire OAuth2 authorization code redirect flow.

Creating A Password Grant Client

Before your application can issue tokens via the password grant, you will need to create a password grant client. You may do this using the passport:client Artisan command with the --password option. If you have already run the passport:install command, you do not need to run this command:

php artisan passport:client --password

Access Token

POST http://api.apiato.test/v1/oauth/token

Once you have created a password grant client, you may request an access token by issuing a POST request to the /oauth/token route with the user's email address and password. If the request is successful, you will receive an access_token and refresh_token in the JSON response from the server:

// Request
{
  "grant_type": "password", // should always be "password"
  "client_id": "client-id", // required
  "client_secret": "client-secret", // required
  "username": "[email protected]",
  "password": "secret",
  "scope": "" // can be empty
}

Proxy Endpoint

POST http://api.apiato.test/v1/clients/web/login

By default, Apiato provides a single ready-to-use URL for your web client: clients/web/login. However, you can add additional URLs as needed for each of your trusted first-party client apps. For example, you could have URLs like clients/mobile/login.

You may request an access token by issuing a POST request to the /clients/web/login route with the user's email address and password. If the request is successful, you will receive an access_token and refresh_token in the JSON response from the server:

// Request
{
  "username": "[email protected]",
  "password": "secret"
}

Behind the scenes, when a request is made to these endpoints, the corresponding client ID and secret are automatically appended to the request. This allows Apiato to make an additional call to your authentication server with all the necessary data. This approach eliminates the need for clients to send their ID and secret with each request, and it allows them to use their own URL, providing even more control over which client is accessing your server. The authentication server then returns the authentication response to the client, including the tokens.

note

You must manually extract the client credentials from the database and update your .env file with the appropriate credentials for each client.

Refresh Token

If your application utilizes short-lived access tokens, users will need to refresh their access tokens using the refresh token that was provided to them when the access token was initially issued.

There are two recommended methods to refresh the token:

1. Proxy Endpoint (recommended for first-party clients): POST http://api.apiato.test/v1/clients/web/refresh

2. Proxy Endpoint (recommended for first-party clients): POST http://api.apiato.test/v1/oauth/token

Proxy Endpoint

Apiato provides a default endpoint, http://api.apiato.test/v1/clients/web/refresh, specifically for the Web Client to refresh its token. You can create additional endpoints for each client as needed. This endpoint can be used in two ways: by manually passing the refresh_token to the endpoint or by including it in the request's HttpCookie. In either case, the server will respond with a new access token and refresh token.

Laravel Passport Endpoint

You can find more information about the Laravel Passport refresh token endpoint here.

Revoking Tokens

POST http://api.apiato.test/v1/api/logout

You may revoke a token by using this endpoint and passing the token to be revoked in the header Authorization: Bearer {token}.

Protecting Routes

API

To protect an API endpoint from being accessible by unauthenticated users, you can use the auth:api middleware.

Route::get('secret/info', Controller::class)
    ->middleware('auth:api');

All endpoints protected with the auth:api middleware can only be accessed by sending a valid access token along with the request. This ensures that only authenticated users with valid tokens are granted access to these endpoints.

Web

To secure a web endpoint and restrict access to authenticated users only, you can utilize the auth:web middleware. By applying the auth:web middleware to a specific endpoint or route, you ensure that only authenticated users can access it. This middleware verifies the user's authentication status based on their web session or cookie, making it suitable for web-based authentication and authorization.

Route::get('private/page', Controller::class)
    ->middleware('auth:web');

Passing The Access Token

When calling routes that Passport protects, your application's API consumers should specify their access token as a Bearer token in the Authorization header of their request. For example, when using the Guzzle HTTP library:

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Accept' => 'application/json',
    'Authorization' => 'Bearer '.$accessToken,
])->get('http://api.apiato.test/v1/users');

return $response->json();

Configuration

Most of the configuration is done in the app/Containers/AppSection/Configs/appSection-authentication.php file.