Preface

This tutorial describes the basic usage of Authlete APIs to implement an OAuth 2.0 authorization server that supports the authorization code grant flow. It also shows how Resource Servers can use Authlete APIs to quickly validate the access tokens, providing secure and authorized access to APIs.

Prerequisites:

• Basic knowledge of OAuth 2.0.
• Access to an Authlete account. Sign up here if needed.

Components

A typical OAuth 2.0 architecture involves multiple components, shown in the flowchart below. In this tutorial, we use the live, public cloud versions of the Authlete Management Console and Authlete API Cluster running in the US region (https://us.authlete.com). The Authorization and Resource servers are simulated using curl commands, showing how an Authorization Server and Resource Server make API requests to Authlete for authorization, token issuance, and introspection.

The FQDNs for each component are listed below. While the Authorization Server and Client are simulated, their FQDNs are used to illustrate the OAuth flow.

Environment Setup

Follow the Quick Setup Guide to create a new Authlete Service and Client. Also, generate a Service Access Token, which is needed to call Authlete APIs. This tutorial assumes you have already created a service in the US cluster and a client as described in the Quick Setup Guide.

Walk-through

The sequence diagram below shows the entire OAuth 2.0 flow as used in this tutorial. Refer back to it as you proceed through each step.

Authorization request from the client to the authorization server

The client makes an authorization request to the authorization server via the user agent (Steps 3 and 4). In this tutorial, we’ll assume the following values are specified as parameters in the request.

The authorization server is expected to receive the following content (folded for readability) as an HTTP GET query string from the user agent.

redirect_uri=https://client.example.org/cb/example.com
 &response_type=code
 &client_id=12818600553323

A typical authorization server should evaluate the following rules before proceeding with the authorization code grant flow.

• Verify that a client associated with the client ID 12818600553323 is registered with the authorization server.
• Check that the redirect URI https://client.example.org/cb/example.com matches one of the URIs registered for the client.
• Confirm that other parameter values, such as response_type and scope, are permitted for the client to specify in its request.

Authlete’s /auth/authorization API performs the above request validation on behalf of the authorization server.

Use the following curl command to make an authorization request to the Authlete API (Step 5):

# Linux/Mac
curl -X POST "https://us.authlete.com/api/933860280/auth/authorization" \
     -H "Authorization: Bearer $sat" \
     -d "parameters=response_type=code&client_id=2800496004&redirect_uri=https://client.example.org/cb/example.com"

# Windows
curl.exe -X POST "https://us.authlete.com/api/933860280/auth/authorization" `
     -H "Authorization: Bearer $env:sat" `
     -d "parameters=response_type=code&client_id=2800496004&redirect_uri=https://client.example.org/cb/example.com"

Note:

• Replace $sat with your actual bearer token.
• For Windows, ensure PowerShell is used to handle environment variables ($env:sat).

If the request is valid, Authlete returns a response like this (Step 6).

{
    "action": "INTERACTION",
    "resultCode": "A004001",
    "resultMessage": "[A004001] Authlete has successfully issued a ticket to the service (API Key = 933860280) for the authorization request from the client (ID = 2800496004). [response_type=code, openid=false]",
    "ticket": "cElOaH9j4mS6AiIGR9oLqHlDn9jpvcNjqSgyRqfcmAE",
    "client": {...},
    "service": {...},
}

• resultMessage provides human-readable result of the request processing. (See also Interpreting Authlete’s result codes)
• action indicates what the authorization server should do next.
• ticket is required for the authorization server to make a request to another API in the following step.

Authlete also provides service and client information in the response. The authorization server utilizes them to ask the resource owner if he or she authorizes access for the client to the service.

User authentication and confirmation of granting access

The actual interaction between the resource owner and the authorization server is out of scope for this tutorial. Typically, the authorization server would authenticate the user with credentials (e.g., ID and password), determine the user’s roles and privileges, and ask if they authorize access (Steps 7, 8 and 9).

Issuing an authorization code

Assume the authorization server reaches the following state after completing the previous process:

• The authorization server has authenticated the resource owner and determined that the identifier to be shared with Authlete as the value of the subject parameter is john.s@example.com.
• The authorization server has obtained consent from the resource owner.

The authorization server then makes a request to Authlete’s /auth/authorization/issue to issue an authorization code. It includes the values of subject and ticket from the /auth/authorization API response as request parameters (Step 10).

Use the following curl command to issue an authorization request to the Authlete API:

# Linux/Mac
curl -X POST "https://us.authlete.com/api/933860280/auth/authorization/issue" \
     -H "Authorization: Bearer $sat" \
     -d "ticket=5tqii9i_pUp1iteacZGUtdjikRnqGSrPwW7lqoH1Pcc" \
     -d "subject=john.s@example.com"

# Windows
curl.exe -X POST "https://us.authlete.com/api/933860280/auth/authorization/issue" `
     -H "Authorization: Bearer $env:sat" `
     -d "ticket=5tqii9i_pUp1iteacZGUtdjikRnqGSrPwW7lqoH1Pcc" `
     -d "subject=john.s@example.com"

If the request is valid, Authlete generates the following response (Step 11).

{
    "action": "LOCATION",
    "authorizationCode": "tJlGEKt8y0DLpjIA_jweywRtJs2fh83ZGNiwFRmIwYI",
    "idToken": null,
    "jwtAccessToken": null,
    "responseContent": "https://client.example.org/cb/example.com?code=tJlGEKt8y0DLpjIA_jweywRtJs2fh83ZGNiwFRmIwYI&iss=https%3A%2F%2Fauthlete.com",
    "resultCode": "A040001",
    "resultMessage": "[A040001] The authorization request was processed successfully.",
    "ticketInfo": {
        "context": null
    }
}

• resultMessage provides a human-readable result of the request processing. (See also Interpreting Authlete’s result codes)
• action indicates what the authorization server should do next. The value in this response is LOCATION, meaning the authorization server should make a redirection response back to the user agent.
• responseContent represents the content of the response from the authorization server.

The authorization server is expected to send the following response (folded for readability) to the user agent (Step 12).

HTTP/1.1 302 Found
Location: https://client.example.org/cb/example.com
 ?code=tJlGEKt8y0DLpjIA_jweywRtJs2fh83ZGNiwFRmIwYI

There are cases where the authorization server may decide not to issue tokens to the client due to the result of the previous authentication, user consent confirmation, or other missing context that prohibits token issuance. In these situations, the authorization server must inform the client that the authorization flow has been terminated with an appropriate protocol response.

Authlete’s /auth/authorization/fail API supports the termination process in terms of messages to be sent to the client, and transfer method for the response.

To summarize, an authentication server usually makes a request to either /auth/authorization/issue or /auth/authorization/fail API depending on result of user authentication and consent.

Token request

Here, we assume that the user agent receives the redirection response from the authorization server. It then sends the following request (folded for readability) to the client (Step 13).

GET /cb/example.com?code=tJlGEKt8y0DLpjIA_jweywRtJs2fh83ZGNiwFRmIwYI HTTP/1.1
Host: client.example.org

The client extracts the value of the code parameter, crafts a token request using this value, and sends it to the authorization server as follows (folded for readability). In this tutorial, https://as.example.com/token is the token endpoint URI (Step 14).

POST /token HTTP/1.1
Host: as.example.com
Authorization: Basic base64(12818600553323:-olDIKD9BihRfB8O1JxobUEKBZ7PIV5Z6oaqxAshmoUtUZgB-wjmmxTYDiDV6vM_Mgl267PeNrRftq8cWplvmg)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
 &code=tJlGEKt8y0DLpjIA_jweywRtJs2fh83ZGNiwFRmIwYI
 &redirect_uri=https://client.example.org/cb/example.com

The authorization server evaluates the parameters in the request and then sends a token response back to the client. In this tutorial, we’ll use Authlete’s /auth/token API to evaluate the request and generate the response.

Use the following curl command to exchange an authorization code for an access token using the Authlete API:

# Linux/Mac
curl -X POST "https://us.authlete.com/api/933860280/auth/token" \
     -H "Authorization: Bearer $sat" \
     -d "parameters=grant_type=authorization_code&code=tJlGEKt8y0DLpjIA_jweywRtJs2fh83ZGNiwFRmIwYI&redirect_uri=https://client.example.org/cb/example.com" \
     -d "clientId=2800496004" \
     -d "clientSecret=AqZKLbUFfRurwZ0-zN1BwAXfo-odPwrZa6XoSOrm-AKtbaaOAq6uzWM3oVG4w"

# Windows
curl.exe -X POST "https://us.authlete.com/api/933860280/auth/token" `
     -H "Authorization: Bearer $env:sat" `
     -d "parameters=grant_type=authorization_code&code=tJlGEKt8y0DLpjIA_jweywRtJs2fh83ZGNiwFRmIwYI&redirect_uri=https://client.example.org/cb/example.com" `
     -d "clientId=2800496004" `
     -d "clientSecret=AqZKLbUFfRurwZ0-zN1BwAXfo-odPwrZa6XoSOrm-AKtbaaOAq6uzWM3oVG4w"

If the request is valid, Authlete responds as follows (Step 16).

{
    "accessToken": "gV5ByjqCVjyinFugV9Wlc0oAxkEP0osifSajXSfJV9g",
    "accessTokenDuration": 86400,
    "accessTokenExpiresAt": 1730203012061,
    "action": "OK",
    "clientAuthMethod": "CLIENT_SECRET_BASIC",
    "clientId": 2800496004,
    "grantType": "AUTHORIZATION_CODE",
    "refreshToken": "1mQRm2XRwaBNYRIjxjO0ls9hb4eDKo9I3ChU0yy8lHo",
    "refreshTokenDuration": 864000,
    "refreshTokenExpiresAt": 1730980612061,
    "responseContent": "{\"access_token\":\"gV5ByjqCVjyinFugV9Wlc0oAxkEP0osifSajXSfJV9g\",\"token_type\":\"Bearer\",\"expires_in\":86400,\"scope\":null,\"refresh_token\":\"1mQRm2XRwaBNYRIjxjO0ls9hb4eDKo9I3ChU0yy8lHo\"}",
    "resultCode": "A050001",
    "resultMessage": "[A050001] The token request (grant_type=authorization_code) was processed successfully.",
    "subject": "john.s@example.com",
}

• resultMessage provides a human-readable result of the request processing. (See also Interpreting Authlete’s result codes)
• action indicates what the authorization server should do next. The value in this response is OK, meaning the authorization server should send a token response back to the client.
• responseContent contains the content of the response from the authorization server.

The authorization server is expected to send the following response to the client (Step 17).

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token":"gV5ByjqCVjyinFugV9Wlc0oAxkEP0osifSajXSfJV9g",
  "refresh_token":"1mQRm2XRwaBNYRIjxjO0ls9hb4eDKo9I3ChU0yy8lHo",
  "scope":null,
  "token_type":"Bearer",
  "expires_in":86400
}

The authorization server has now successfully created the tokens and provided them to the client. By leveraging Authlete APIs, the authorization server avoids the need to implement complex logic to evaluate parameters in authorization and token requests and can respond correctly using the appropriate methods.

API request (access token introspection)

In most cases, the client sends a request with the access token to the resource server providing the APIs (Step 18). The resource server is responsible for evaluating the token’s validity, retrieving information about the user and client associated with the token, and determining how to respond to the API request.

Authlete provides the /auth/introspection API for this purpose. It verifies the token’s validity and provides the necessary information.

Use the following curl command to introspect a token using the Authlete API:

# Linux/Mac
curl -X POST "https://us.authlete.com/api/933860280/auth/introspection" \
     -H "Authorization: Bearer $sat" \
     -d "token=gV5ByjqCVjyinFugV9Wlc0oAxkEP0osifSajXSfJV9g"

# Windows
curl.exe -X POST "https://us.authlete.com/api/933860280/auth/introspection" `
     -H "Authorization: Bearer $env:sat" `
     -d "token=gV5ByjqCVjyinFugV9Wlc0oAxkEP0osifSajXSfJV9g"

If the request is valid, Authlete returns the following response (Step 20).

{
    "action": "OK",
    "authTime": 0,
    "clientId": 2800496004,
    "expiresAt": 1730203012000,
    "grantType": "AUTHORIZATION_CODE",
    "issuableCredentials": null,
    "properties": null,
    "refreshable": true,
    "resources": null,
    "responseContent": "Bearer error=\"invalid_request\"",
    "resultCode": "A056001",
    "resultMessage": "[A056001] The access token is valid.",
    "scopeDetails": null,
    "scopes": null,
    "serviceAttributes": null,
    "subject": "john.s@example.com",
    "sufficient": false,
    "usable": true
}

The resource server can retrieve various information, such as the token’s expiration time (expiresAt), the identifier of the user who approved access (subject), the grant type used to obtain the token, and the client identifier (clientId). It then determines how to respond to the API request (Step 21).

Recap

In this tutorial, we covered how to use Authlete APIs to implement the authorization code grant flow in an authorization server.

Next Steps

Let’s dig deeper into Authlete by exploring the following features.

• Authlete API Tutorial - OIDC Basics
• PKCE (RFC 7636) — OAuth and OpenID Connect — Authlete Knowledge Base
• Authorization Server Reference Implementations