client_secret_jwt

Overview

Authlete allows users to authenticate its clients with a client_secret_jwt method, which is defined in OpenID Connect Core 1.0, 9.Client Authentication



About client_secret_jwt


When an authorization server authenticates its clients with the client_secret_jwt method, the client must send an assertion-containing request to the token endpoint of the server. 
And the authorization server must introspect the signature and payload of the JWT-formatted assertion, which is described as follows.

Client side


The client must send the request that contains the following parameters to the token endpoint when using the client_secret_jwt method.
parameter
description
client_assertion_type
a type of client_assertion
client_assertion
a JWT that contains information for client authentication

The value of the client_asesrtion_type must be  "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" .

The value of the client_assertion must be a JWT that contains information for client authentication. Also the JWT must satisfy the following specifications.

<Signature>
The JWT must be signed using an HMAC SHA algorithm, such as HMAC SHA-256. The HMAC (Hash-based Message Authentication Code) is calculated using the octets of the UTF-8 representation of the client_secret as the shared key.


<Payload>
The JWT must contains the REQUIRED claims listed below.
claim
detail
iss
REQUIRED. Issuer. This must contain the client_id of the OAuth Client.
sub
REQUIRED. Subject. This must contain the client_id of the OAuth Client.
aud
REQUIRED. Audience. The aud (audience) Claim. Value that identifies the Authorization Server as an intended audience. The Authorization Server must verify that it is an intended audience for the token. The Audience should be the URL of the Authorization Server's Token Endpoint.
jti
REQUIRED. JWT ID. A unique identifier for the token, which can be used to prevent reuse of the token. These tokens must only be used once, unless conditions for reuse were negotiated between the parties; any such negotiation is beyond the scope of this specification.
exp
REQUIRED. Expiration time on or after which the ID Token must not be accepted for processing.
iat
OPTIONAL. Time at which the JWT was issued.

You can find the sample request in the  "Generating an assertion" section.

Server side


Authlete will process the requests following the specifications listed below.



Setting up Authlete for using client_secret_jwt



In the Service Owner Console
section
key
value
Authorization
Supported Client Authentication Methods
contains CLIENT_SECRET_JWT

In the Developer Console
section
key
value
Basic
Client Type
Confidential
Authorization
Assertion Signature Algorithm
HS256, HS384  or HS512

Example


generating an assertion


First, let's create a JWT, which will be used as a value of  the client_assertion in a token request.

Base on the format of the payload,

{
                          "jti":"JWT ID",
                          "sub":"client ID",
                          "iss":"client ID",
                          "aud":"URL of the token endpoint",
                          "exp":"expiration time of this JWT",
                          "iat":"time when this JWT issued"
                      }

create a payload json file and save it as "payload.json",

{
                          "jti":"myJWTId001",
                          "sub":"38174623762",
                          "iss":"38174623762",
                          "aud":"http://localhost:4000/api/auth/token/direct/24523138205",
                          "exp":1536165540,
                          "iat":1536132708
                      }

and create a JWT using authlete-jose as is described below.

$ bin/jose-generator \
                          --payload-file payload.json \
                          --sign \
                          --signing-alg HS256 \
                          --signing-alg-key TzPTZDtcw9ek41H1VmofRoXQddP5cWCXPWidZHSA2spU6gZN9eIFUiXaHD7OfxtBhTxJsg_I1tdFI_CkKl8t8Q

The created JWT will look like this.

eyJhbGciOiJIUzI1NiJ9.
                      ewogICJqdGkiOiJteUpXVElkMDAxIiwKICAic3ViIjoiMzgxNzQ2MjM3NjIiLAogICJpc3MiOiIzODE3NDYyMzc2MiIsCiAgImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAwMC9hcGkvYXV0aC90b2tlbi9kaXJlY3QvMjQ1MjMxMzgyMDUiLAogICJleHAiOjE1MzYxNjU1NDAsCiAgImlhdCI6MTUzNjEzMjcwOAp9Cg.
                      Vin3IxRPMLQ0SKNJ8Ba_59dYHBGLb4Ft-JLbJVKFd3E

Requesting a token


When a client sends a request to the authorization server,

POST /token.oauth2 HTTP/1.1
                      Host: as.example.com
                      Content-Type: application/x-www-form-urlencoded
                                        
                      grant_type=authorization_code&
                      code=Gw30fMKJBHkcOBSde5awLrMm4ahvgCNM2cFSTUOUflY&
                      redirect_uri=https://example.com/redirection
                      client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
                      client_assertion=eyJhbGciOiJIUzI1NiJ9.
                                                    ewogICJqdGkiOiJteUpXVElkMDAxIiwKICAic3ViIjoiMzgxNzQ2MjM3NjIiLAogICJpc3MiOiIzODE3NDYyMzc2MiIsCiAgImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAwMC9hcGkvYXV0aC90b2tlbi9kaXJlY3QvMjQ1MjMxMzgyMDUiLAogICJleHAiOjE1MzYxNjU1NDAsCiAgImlhdCI6MTUzNjEzMjcwOAp9Cg.
                                                    Vin3IxRPMLQ0SKNJ8Ba_59dYHBGLb4Ft-JLbJVKFd3E

the authorization server will send a request, which is generated according to the request above, to Authlete's /auth/token API, 

$ curl -v -X POST https://api.authlete.com/api/auth/token \
                      -H 'Content-Type: application/json' \
                      -u '10629969330:tszcLrddM8146JPApzflvRYc7QVU3HhkwCQnoAWF3UI' \
                      -d '{ 
                                "parameters":"grant_type=authorization_code&
                                                          code=Gw30fMKJBHkcOBSde5awLrMm4ahvgCNM2cFSTUOUflY&
                                                          redirect_uri=https://example.com/redirection&
                                                          client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
                                                          client_assertion=eyJhbGciOiJIUzI1NiJ9.
                                                                                        ewogICJqdGkiOiJteUpXVElkMDAxIiwKICAic3ViIjoiMzgxNzQ2MjM3NjIiLAogICJpc3MiOiIzODE3NDYyMzc2MiIsCiAgImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAwMC9hcGkvYXV0aC90b2tlbi9kaXJlY3QvMjQ1MjMxMzgyMDUiLAogICJleHAiOjE1MzYxNjU1NDAsCiAgImlhdCI6MTUzNjEzMjcwOAp9Cg.
                                                                                        Vin3IxRPMLQ0SKNJ8Ba_59dYHBGLb4Ft-JLbJVKFd3E"
                         }'

and the client will receive a response described as below.

{
                          "type":"tokenResponse",
                          "resultCode":"A050001",
                          "resultMessage":"[A050001] The token request (grant_type=authorization_code) was processed successfully.",
                          "accessToken":"kwXY57oN4nBOqxk57vW2fo-WzgezrwSl2h1N_xW8aKI",
                          ...
                      }

How did we do with this article?