Package com.authlete.jaxrs.spi

Interface TokenRequestHandlerSpi

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      String authenticateUser​(String username, String password)
      Authenticate an end-user.
      com.authlete.common.dto.Property[] getProperties()
      Get extra properties to associate with an access token.
      javax.ws.rs.core.Response jwtBearer​(com.authlete.common.dto.TokenResponse tokenResponse)
      Handle a token request that uses the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer" (RFC 7523).
      javax.ws.rs.core.Response tokenExchange​(com.authlete.common.dto.TokenResponse tokenResponse)
      Handle a token exchange request.

    • Method Detail

      • authenticateUser

        String authenticateUser​(String username,
                        String password)
        Authenticate an end-user.

        This method is called only when Resource Owner Password Credentials Grant was used. Therefore, if you have no mind to support Resource Owner Password Credentials, always return null. In typical cases, you don't have to support Resource Owner Password Credentials Grant. FYI: RFC 6749 says "The authorization server should take special care when enabling this grant type and only allow it when other flows are not viable."

        Below is an example implementation using Apache Shiro. 

         @Override
 public String authenticateUser(String username, String password)
 {
     // Pack the username and password into AuthenticationToken
     // which Apache Shiro's SecurityManager can accept.
     AuthenticationToken credentials =
         new UsernamePasswordToken(username, password);

     try
     {
         // Authenticate the resource owner.
         AuthenticationInfo info =
             SecurityUtils.getSecurityManager().authenticate(credentials);

         // Get the subject of the authenticated user.
         return info.getPrincipals().getPrimaryPrincipal().toString();
     }
     catch (AuthenticationException e)
     {
         // Not authenticated.
         return null;
     }
 }
        Parameters:
        username - The value of username parameter in the token request.
        password - The value of password parameter in the token request.
        Returns:
        The subject (= unique identifier) of the authenticated end-user. If the pair of username and password is invalid, null should be returned.

      • getProperties

        com.authlete.common.dto.Property[] getProperties()
        Get extra properties to associate with an access token.

        This method is expected to return an array of extra properties. The following is an example that returns an array containing one extra property. 

         @Override
 public Property[] getProperties()
 {
     return new Property[] {
         new Property("example_parameter", "example_value")
     };
 }

        Extra properties returned from this method will appear as top-level entries in a JSON response from an authorization server as shown in 5.1. Successful Response in RFC 6749.

        Keys listed below should not be used and they would be ignored on the server side even if they were used. It's because they are reserved in RFC 6749 and OpenID Connect Core 1.0.

        • access_token
        • token_type
        • expires_in
        • refresh_token
        • scope
        • error
        • error_description
        • error_uri
        • id_token

        Note that there is an upper limit on the total size of extra properties. On the server side, the properties will be (1) converted to a multidimensional string array, (2) converted to JSON, (3) encrypted by AES/CBC/PKCS5Padding, (4) encoded by base64url, and then stored into the database. The length of the resultant string must not exceed 65,535 in bytes. This is the upper limit, but we think it is big enough.

        When the value of grant_type parameter contained in the token request from the client application is authorization_code or refresh_token, extra properties are merged. Rules are as described in the table below.

        grant_type Description
        authorization_code

        If the authorization code presented by the client application already has extra properties (this happens if AuthorizationDecisionHandlerSpi.getProperties() returned extra properties when the authorization code was issued), extra properties returned by this method will be merged into the existing extra properties. Note that the existing extra properties will be overwritten if extra properties returned by this method have the same keys.

        For example, if an authorization code has two extra properties, a=1 and b=2, and if this method returns two extra properties, a=A and c=3, the resultant access token will have three extra properties, a=A, b=2 and c=3.

        refresh_token

        If the access token associated with the refresh token presented by the client application already has extra properties, extra properties returned by this method will be merged into the existing extra properties. Note that the existing extra properties will be overwritten if extra properties returned by this method have the same keys.

        Returns:
        Extra properties. If null is returned, any extra property will not be associated.
        Since:
        1.3

      • tokenExchange

        javax.ws.rs.core.Response tokenExchange​(com.authlete.common.dto.TokenResponse tokenResponse)
        Handle a token exchange request.

        This method is called when the grant type of the token request is "urn:ietf:params:oauth:grant-type:token-exchange". The grant type is defined in RFC 8693: OAuth 2.0 Token Exchange.

        RFC 8693 is very flexible. In other words, the specification does not define details that are necessary for secure token exchange. Therefore, implementations have to complement the specification with their own rules.

        The argument passed to this method is an instance of TokenResponse that represents a response from Authlete's /auth/token API. The instance contains information about the token exchange request such as the value of the subject_token request parameter. Implementations of this tokenExchange method are supposed to (1) validate the information based on their own rules, (2) generate a token (e.g. an access token) using the information, and (3) prepare a token response in the JSON format that conforms to Section 2.2 of RFC 8693.

        Authlete's /auth/token API performs validation of token exchange requests to some extent. Therefore, authorization server implementations don't have to repeat the same validation steps. See the JavaDoc of the TokenResponse class for details about the validation steps.

        NOTE: Token Exchange is supported by Authlete 2.3 and newer versions. If the Authlete server of your system is older than version 2.3, the grant type ("urn:ietf:params:oauth:grant-type:token-exchange") is not supported and so this method is never called.

        Parameters:
        tokenResponse - A response from Authlete's /auth/token API.
        Returns:
        A response from the token endpoint. It must conform to Section 2.2 of RFC 8693. If this method returns null, TokenRequestHandler will generate 400 Bad Request with {"error":"unsupported_grant_type"}.
        Since:
        2.47, Authlete 2.3
        See Also:
        RFC 8693 OAuth 2.0 Token Exchange

      • jwtBearer

        javax.ws.rs.core.Response jwtBearer​(com.authlete.common.dto.TokenResponse tokenResponse)
        Handle a token request that uses the grant type "urn:ietf:params:oauth:grant-type:jwt-bearer" (RFC 7523).

        This method is called when the grant type of the token request is "urn:ietf:params:oauth:grant-type:jwt-bearer". The grant type is defined in RFC 7523: JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants.

        The grant type utilizes a JWT as an authorization grant, but the specification does not define details about how the JWT is generated by whom. As a result, it is not defined in the specification how to obtain the key whereby to verify the signature of the JWT. Therefore, each deployment has to define their own rules which are necessary to determine the key for signature verification.

        The argument passed to this method is an instance of TokenResponse that represents a response from Authlete's /auth/token API. The instance contains information about the token request such as the value of the assertion request parameter. Implementations of this jwtBearer method are supposed to (1) validate the authorization grant (= the JWT specified by the assertion request parameter), (2) generate an access token, and (3) prepare a token response in the JSON format that conforms to RFC 6749.

        Authlete's /auth/token API performs validation of token requests to some extent. Therefore, authorization server implementations don't have to repeat the same validation steps. Basically, what implementations have to do is to verify the signature of the JWT. See the JavaDoc of the TokenResponse class for details about the validation steps.

        NOTE: JWT Authorization Grant is supported by Authlete 2.3 and newer versions. If the Authlete server of your system is older than version 2.3, the grant type ("urn:ietf:params:oauth:grant-type:jwt-bearer") is not supported and so this method is never called.

        Parameters:
        tokenResponse - A response from Authlete's /auth/token API.
        Returns:
        A response from the token endpoint. It must conform to RFC 6749. If this method returns null, TokenRequestHandler will generate 400 Bad Request with {"error":"unsupported_grant_type"}.
        Since:
        2.48, Authlete 2.3
        See Also:
        RFC 7521 Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants, RFC 7523 JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants