Working with the JWT Service in WordPress

This is how easily you can generate a proper JWT token. It can be invalidated at any any point in time simply with revoke method.

$token = AAM::api()->jwts('user:john@example.xyz')->issue();

This article will guide you through the JWT Service available in the Advanced Access Manager (AAM) framework. This feature, starting from AAM version 7 Beta 1, is already available for download from the official WordPress.org repositoryopen in new window.

I'm assuming that you're familiar with the concept of JSON Web Tokens (JWT) and you already know how they work. However, it’s crucial to highlight that JWT tokens are not designed to store sensitive information. While they appear encrypted, they are merely base64-encoded arrays of data. For security, avoid placing sensitive information in the token claims.

# Key Considerations

There are only two considerations you have to keep in mind as follow:

• User-specific only: The JWT service operates exclusively at the user access level. Tokens cannot be assigned to roles, default access level, or visitor.
• Dependencies: Ensure you have a valid user account for issuing tokens.

# Get Service Instance

To create an instance of the JWT Service via the AAM API, simply invoke the jwts() method and provide desired user access level as the first argument.

$jwt_service = AAM::api()->jwts('user:12');

Another way to pre-configure the JWT service with user level is to obtain the service instance through access level. In this case you have the ability to provide user identifier in several different ways:

// Pass user identifier as WP_User instance
$jwt_service = AAM::api()->user(get_user(12))->jwts();

// Pass user identifier as user ID
$jwt_service = AAM::api()->user(12)->jwts();

// Pass user identifier as user's email address
$jwt_service = AAM::api()->user('john@example.xyz')->jwts();

// Pass user identifier as username
$jwt_service = AAM::api()->user('john')->jwts();

With the instance of JWT service, you can now manage JWT tokens for given user and you have several public methods as following:

• get_tokens: Retrieve an array of all tokens issued for a specific user.
• get_token_by: Search for a specific token by claim.
• issue: Generate a new token for a user.
• validate: Verify if a token is valid.
• revoke: Remove a token from the user's registry, invalidating it.
• refresh: Renew an existing token before it expires.
• reset: Delete all tokens associated with a user.

# Issue Token

The issue method accepts two optional parameters: $claims and $settings.

The $claims allows you to add custom claims to the token. For instance, in the following code snippet, we are adding user roles as part of JWT token claims:

$user        = get_user(1); // Get admin user account
$jwt_service = AAM::api()->user($user)->jwts();
$token       = $jwt_service->issue([
    'roles' => $user->roles
]);

The $settings arguments is optional and is used to configure token's behavior. It support 3 distinct properties:

• ttl: Token Time-to-Live. By default, tokens are valid for 24 hours. You can adjust it using a timestamp or a relative duration (e.g. 3 days, 1 months, etc.).
• revocable: When set to true (default), the token can be invalidated even before its expiration.
• refreshable: Allows the token to be renewed. When enabled, a valid token can issue a new one with the same duration.

# Managing Tokens

Once issued, tokens are automatically added to the user token registry. You can view them within the AAM interface under the user’s profile or you can obtain the complete list of tokens with get_tokens method. As an option, you can also use get_token_by method to search a very specific token by claim. For example, the following code will search for a token by jti claim.

$result = AAM::api()->jwts()->get_token_by('d1fc364a-52aa-4ab1-9fea-2e3149d51a6b', 'jti');

The validate method allows to validate if token is not expired and is still part of user token registry. If it is not found in the user token registry, the token is considered as invalid because it was likely revoked with revoke method.

The refresh method allows to obtain a new JWT token for the same duration. For example, if a token was issued for 3 days, you have the ability to refresh it within 3 days and obtain a new token for another 3 days. This deviates from the Auth 2.0 standard where refresh token is a separate token from actual JWT token. This is done to simplify token management.

# Using Tokens in API Requests

Tokens are typically used for authenticating API requests. Add the issued token as a Bearer token in your API request header and AAM will automatically validate and authenticate user prior to request processing.

curl --location 'https://example.xyz/wp-json/aam/v2/service/posts?access_level=role&role_id=subscriber&post_type=post' \
--header 'Authorization: Bearer ****'

# Conclusion

The JWT Service in AAM provides a streamlined way to manage tokens for user-specific authentication. With features like token issuance, validation, revocation, and refreshing, you can manage your JWT tokens effectively.