Process Token Request

This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further.

Description

This API is supposed to be called from with the implementation of the token endpoint of the service. The endpoint implementation must extract the request parameters from the token request from the client application and pass them as the value of parameters request parameter to Authlete's /auth/token API. The value of parameters is the entire entity body (which is formatted in application/x-www-form-urlencoded) of the token request. In addition, if the token endpoint of the authorization server implementation supports basic authentication as a means of client authentication, the client credentials must be extracted from Authorization header and they must be passed as clientId request parameter and clientSecret request parameter to Authlete's /auth/token API. The following code snippet is an example in JAX-RS showing how to extract request parameters from the token request and client credentials from Authorization header.

@POST
@Consumes(MediaType.APPLICATION\_FORM\_URLENCODED)
public Response post(
@HeaderParam(HttpHeaders.AUTHORIZATION) String auth,
String parameters)
{
// Convert the value of Authorization header (credentials of
// the client application), if any, into BasicCredentials.
BasicCredentials credentials = BasicCredentials.parse(auth);
// The credentials of the client application extracted from
// 'Authorization' header. These may be null.
String clientId = credentials == null ? null
: credentials.getUserId();
String clientSecret = credentials == null ? null
: credentials.getPassword();
// Process the given parameters.
return process(parameters, clientId, clientSecret);
}

The response from /auth/token API has some parameters. Among them, it is action parameter that the service implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of action, the authorization server implementation must take the steps described below. INTERNAL_SERVER_ERROR When the value of action is INTERNAL\_SERVER\_ERROR, it means that the request from the authorization server implementation was wrong or that an error occurred in Authlete. In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with HTTP status of "500 Internal Server Error". Authlete recommends application/json as the content type although OAuth 2.0 specification does not mention the format of the error response when the redirect URI is not usable. The value of responseContent is a JSON string which describes the error, so it can be used as the entity body of the response. The following illustrates the response which the service implementation should generate and return to the client application.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}

The endpoint implementation may return another different response to the client application since "500 Internal Server Error" is not required by OAuth 2.0. INVALID_CLIENT When the value of action is INVALID\_CLIENT, it means that authentication of the client failed. In this case, the HTTP status of the response to the client application is either "400 Bad Request" or "401 Unauthorized". This requirement comes from RFC 6749, 5.2. Error Response. The description about invalid\_client shown below is an excerpt from RFC 6749. Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the Authorization request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the WWW-Authenticate response header field matching the authentication scheme used by the client. In either case, the value of responseContent is a JSON string which can be used as the entity body of the response to the client application. The following illustrate responses which the service implementation must generate and return to the client application.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}

HTTP/1.1 401 Unauthorized
WWW-Authenticate: {challenge}
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}

BAD_REQUEST When the value of action is BAD\_REQUEST, it means that the request from the client application is invalid. A response with HTTP status of "400 Bad Request" must be returned to the client application and the content type must be application/json. The value of responseContent is a JSON string which describes the error, so it can be used as the entity body of the response. The following illustrates the response which the service implementation should generate and return to the client application.

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}

PASSWORD When the value of "action" is "PASSWORD", it means that the request from the client application is valid and grant\_type is "password". That is, the flow is "Resource Owner Password Credentials". In this case, {@link #getUsername()} returns the value of "username" request parameter and {@link #getPassword()} returns the value of {@code "password"} request parameter which were contained in the token request from the client application. The service implementation must validate the credentials of the resource owner (= end-user) and take either of the actions below according to the validation result.

1. When the credentials are valid, call Authlete's /auth/token/issue} API to generate an access token for the client application. The API requires "ticket" request parameter and "subject" request parameter. Use the value returned from {@link #getTicket()} method as the value for "ticket" parameter.
2. The response from /auth/token/issue API ({@link TokenIssueResponse}) contains data (an access token and others) which should be returned to the client application. Use the data to generate a response to the client application.
3. When the credentials are invalid, call Authlete's {@code /auth/token/fail} API with reason={@link TokenFailRequest.Reason#INVALID_RESOURCE_OWNER_CREDENTIALS INVALID_RESOURCE_OWNER_CREDENTIALS} to generate an error response for the client application. The API requires "ticket" request parameter. Use the value returned from {@link #getTicket()} method as the value for "ticket" parameter.
4. The response from /auth/token/fail API ({@link TokenFailResponse}) contains error information which should be returned to the client application. Use it to generate a response to the client application. OK When the value of action is OK, it means that the request from the client application is valid and an access token, and optionally an ID token, is ready to be issued. The HTTP status of the response returned to the client application must be "200 OK" and the content type must be application/json. The value of responseContent is a JSON string which contains an access token (and optionally an ID token), so it can be used as the entity body of the response. The following illustrates the response which the service implementation must generate and return to the client application.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}

TOKEN_EXCHANGE (Authlete 2.3 onwards) When the value of "action" is "TOKEN\_EXCHANGE", it means that the request from the client application is a valid token exchange request (cf. RFC 8693 OAuth 2.0 Token Exchange) and that the request has already passed the following validation steps.

1. Confirm that the value of the requested\_token\_type request parameter is one of the registered token type identifiers if the request parameter is given and its value is not empty.
2. Confirm that the subject\_token request parameter is given and its value is not empty.
3. Confirm that the subject\_token\_type request parameter is given and its value is one of the registered token type identifiers.
4. Confirm that the actor\_token\_type request parameter is given and its value is one of the registered token type identifiers if the actor\_token request parameter is given and its value is not empty.
5. Confirm that the actor\_token\_type request parameter is not given or its value is empty when the actor\_token request parameter is not given or its value is empty. Furthermore, Authlete performs additional validation on the tokens specified by the subject\_token request parameter and the actor\_token request parameter according to their respective token types as shown below. Token Validation Steps *Token Type: urn:ietf:params:oauth:token-type:jwt*
6. Confirm that the format conforms to the JWT specification [RFC 7519][https://www.rfc-editor.org/rfc/rfc7519.html].
7. Check if the JWT is encrypted and if it is encrypted, then (a) reject the token exchange request when the {@link Service#isTokenExchangeEncryptedJwtRejected() tokenExchangeEncryptedJwtRejected} flag of the service is true or (b) skip remaining validation steps when the flag is false. Note that Authlete does not verify an encrypted JWT because there is no standard way to obtain the key to decrypt the JWT with. This means that you must verify an encrypted JWT by yourself when one is used as an input token with the token type { @code "urn:ietf:params:oauth:token-type:jwt" }.
8. Confirm that the current time has not reached the time indicated by the exp claim if the JWT contains the claim.
9. Confirm that the current time is equal to or after the time indicated by the iat claim if the JWT contains the claim. 5.Confirm that the current time is equal to or after the time indicated by the nbf claim if the JWT contains the claim.
10. Check if the JWT is signed and if it is not signed, then (a) reject the token exchange request when the {@link Service#isTokenExchangeUnsignedJwtRejected() tokenExchangeUnsignedJwtRejected} flag of the service is true or (b) finish validation on the input token. Note that Authlete does not verify the signature of the JWT because there is no standard way to obtain the key to verify the signature of a JWT with. This means that you must verify the signature by yourself when a signed JWT is used as an input token with the token type "urn:ietf:params:oauth:token-type:jwt". *Token Type: urn:ietf:params:oauth:token-type:access\_token*
11. Confirm that the token is an access token that has been issued by the Authlete server of your service. This implies that access tokens issued by other systems cannot be used as a subject token or an actor token with the token type urn:ietf:params:oauth:token-type:access_token.
12. Confirm that the access token has not expired.
13. Confirm that the access token belongs to the service. *Token Type: urn:ietf:params:oauth:token-type:refresh\_token*
14. Confirm that the token is a refresh token that has been issued by the Authlete server of your service. This implies that refresh tokens issued by other systems cannot be used as a subject token or an actor token with the token type urn:ietf:params:oauth:token-type:refresh_token.
15. Confirm that the refresh token has not expired.
16. Confirm that the refresh token belongs to the service. *Token Type: urn:ietf:params:oauth:token-type:id\_token*
17. Confirm that the format conforms to the JWT specification (RFC 7519).
18. Check if the ID Token is encrypted and if it is encrypted, then (a) reject the token exchange request when the {@link Service#isTokenExchangeEncryptedJwtRejected() tokenExchangeEncryptedJwtRejected} flag of the service is true or (b) skip remaining validation steps when the flag is false. Note that Authlete does not verify an encrypted ID Token because there is no standard way to obtain the key to decrypt the ID Token with in the context of token exchange where the client ID for the encrypted ID Token cannot be determined. This means that you must verify an encrypted ID Token by yourself when one is used as an input token with the token type "urn:ietf:params:oauth:token-type:id\_token".
19. Confirm that the ID Token contains the exp claim and the current time has not reached the time indicated by the claim.
20. Confirm that the ID Token contains the iat claim and the current time is equal to or after the time indicated by the claim.
21. Confirm that the current time is equal to or after the time indicated by the nbf claim if the ID Token contains the claim.
22. Confirm that the ID Token contains the iss claim and the value is a valid URI. In addition, confirm that the URI has the https scheme, no query component and no fragment component.
23. Confirm that the ID Token contains the aud claim and its value is a JSON string or an array of JSON strings.
24. Confirm that the value of the nonce claim is a JSON string if the ID Token contains the claim.
25. Check if the ID Token is signed and if it is not signed, then (a) reject the token exchange request when the {@link Service#isTokenExchangeUnsignedJwtRejected() tokenExchangeUnsignedJwtRejected} flag of the service is true or (b) finish validation on the input token.
26. Confirm that the signature algorithm is asymmetric. This implies that ID Tokens whose signature algorithm is symmetric (HS256, HS384 or HS512) cannot be used as a subject token or an actor token with the token type urn:ietf:params:oauth:token-type:id\_token.
27. Verify the signature of the ID Token. Signature verification is performed even in the case where the issuer of the ID Token is not your service. But in that case, the issuer must support the discovery endpoint defined in OpenID Connect Discovery 1.0. Otherwise, signature verification fails. *Token Type: urn:ietf:params:oauth:token-type:saml1* (Authlete does not perform any validation for this token type.) *Token Type: urn:ietf:params:oauth:token-type:saml2* (Authlete does not perform any validation for this token type.) The specification of Token Exchange (RFC 8693) is very flexible. In other words, the specification has abandoned the task of determining details. Therefore, for secure token exchange, you have to complement the specification with your own rules. For that purpose, Authlete provides some configuration options as listed below. Authorization server implementers may utilize them and/or implement their own rules. In the case of {@link Action#TOKEN_EXCHANGE TOKEN_EXCHANGE}, the {@link #getResponseContent()} method returns null. You have to construct the token response by yourself. For example, you may generate an access token by calling Authlete's /api/auth/token/create API and construct a token response like below.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: {challenge}
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{responseContent}

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store
{
"access\_token": "{@link TokenCreateResponse#getAccessToken()}",
"issued\_token\_type": "urn:ietf:params:oauth:token-type:access\_token",
"token\_type": "Bearer",
"expires\_in": { @link TokenCreateResponse#getExpiresIn() },
"scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})"
}

JWT_BEARER JWT_BEARER (Authlete 2.3 onwards) When the value of "action" is "JWT\_BEARER", it means that the request from the client application is a valid token request with the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer" (RFC 7523 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants) and that the request has already passed the following validation steps.

1. Confirm that the assertion request parameter is given and its value is not empty.
2. Confirm that the format of the assertion conforms to the JWT specification (RFC 7519).
3. Check if the JWT is encrypted and if it is encrypted, then (a) reject the token request when the {@link Service#isJwtGrantEncryptedJwtRejected() jwtGrantEncryptedJwtRejected} flag of the service is true or (b) skip remaining validation steps when the flag is false. Note that Authlete does not verify an encrypted JWT because there is no standard way to obtain the key to decrypt the JWT with. This means that you must verify an encrypted JWT by yourself.
4. Confirm that the JWT contains the iss claim and its value is a JSON string.
5. Confirm that the JWT contains the sub claim and its value is a JSON string.
6. Confirm that the JWT contains the aud claim and its value is either a JSON string or an array of JSON strings.
7. Confirm that the issuer identifier of the service (cf. {@link Service#getIssuer()}) or the URL of the token endpoint (cf. {@link Service#getTokenEndpoint()}) is listed as audience in the aud claim.
8. Confirm that the JWT contains the exp claim and the current time has not reached the time indicated by the claim.
9. Confirm that the current time is equal to or after the time indicated by by the iat claim if the JWT contains the claim.
10. Confirm that the current time is equal to or after the time indicated by by the nbf claim if the JWT contains the claim.
11. Check if the JWT is signed and if it is not signed, then (a) reject the token request when the {@link Service#isJwtGrantUnsignedJwtRejected() jwtGrantUnsignedJwtRejected} flag of the service is true or (b) finish validation on the JWT. Note that Authlete does not verify the signature of the JWT because there is no standard way to obtain the key to verify the signature of a JWT with. This means that you must verify the signature by yourself. Authlete provides some configuration options for the grant type as listed below. Authorization server implementers may utilize them and/or implement their own rules.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store
{
"access\_token": "{@link TokenCreateResponse#getAccessToken()}",
"token\_type": "Bearer",
"expires\_in": {@link TokenCreateResponse#getExpiresIn()},
"scope": "String.join(" ", {@link TokenCreateResponse#getScopes()})"
}

Finally, note again that Authlete does not verify the signature of the JWT specified by the assertion request parameter. You must verify the signature by yourself.