> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Client authentication using private_key_jwt method
> Technical information on client authentication using the private_key_jwt method in OAuth 2.0 with an overview of the method setup instructions with Authlete and requirements for both the client and the authorization server side.
For **Authlete 2.x** documentation, see [2.x version](/v2/protocols-and-flows/client-authentication/client-auth-private-key-jwt).
## Preface
**private\_key\_jwt** is one of client authentication methods defined in [OpenID Connect Core 1.0, 9. Client Authentication](http://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
.
On a token request, a client crafts a digitally signed JWT assertion and includes it to the request. Then an authorization server authenticates the client by verifying the signature and payload of the assertion.
Authlete supports `private_key_jwt` as a client authentication method so that authorization servers can enable it. This article describes overview of the method and setup instructions with Authlete.\\
## Requirements for private\_key\_jwt
The following section describes details on both client and authorization server side.
## Client
A client must include the following parameters in a token request when using the private\_key\_jwt method.
| Parameter | Description |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| client\_assertion\_type | A type of client\_assertion. Its value must be "**urn:ietf:params:oauth:client-assertion-type:jwt-bearer**". |
| client\_assertion | A JWT that contains information for client authentication. It must be **digitally signed using a private key**. See below for details. |
The value of **client\_assertion** must satisfy the following requirements on its JWT payload and JWT signature. You can find an example JWT in the "[Generating a JWT assertion](#example)
" section.
### Payload
A JWT assertion must contain the REQUIRED claims listed below.
| Claim | Description |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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. A 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 JWT must not be accepted for processing. |
| iat | \[OPTIONAL] Time at which the JWT was issued. |
### Signature
* A JWT assertion must be digitally signed using **a private key in asymmetric cryptography** (e.g. RS256).
* A client using the authentication method has to register **its public key** to an authorization server in advance so that the server can verify the assertion.
## Authorization server
An authorization server must process a token request as per the specifications listed below. The details are omitted here because **you can offload these operations from your authorization server to Authlete**.
* [JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC7523)](https://tools.ietf.org/html/rfc7523)
* [Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants (RFC7521)](https://tools.ietf.org/html/rfc7521)
***
## Configuration settings
This section explains settings for enabling the private\_key\_jwt method. You have to configure both Authlete service and its client to be authenticated with the method.
## Service settings
Log in to the Authlete Management Console and navigate to **Service Settings > Endpoints > Token**. Under the **Supported Client Authentication Methods** section, enable the `PRIVATE_KEY_JWT` checkbox.
## Client settings
| Tab | Key | Value |
| ------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------- |
| Basic Settings | Client Type | **CONFIDENTIAL** |
| Endpoints > Token | Client Authentication Method | **PRIVATE\_KEY\_JWT** |
| Endpoints > Token | Assertion Signature Algorithm | **RS256**, **RS384**, **RS512**,**ES256**, **ES384**, **ES512**,**PS256**, **PS384**, or **PS512** |
| Key Management > JWK Set | JWK Set Content | A JWK set including **a public key used for verifying the client's JWT assertion** |
Navigate to **Client Settings > Endpoints > Token**. Under the **Client Authentication Method** section, open the dropdown menu and select `PRIVATE_KEY_JWT` and select `ES256` as the **Assertion Signature Algorithm**.
Click Save Changes to apply the updates.
Navigate to **Key Management > JWK Set**. Under the **JWK Set Content** section, enter your JWK Set.
Click Save Changes to apply the updates.
## Example
This example shows client authentication using `private_key_jwt` at the token endpoint of the authorization server.
## Generating a JWT assertion
Let's generate a JWT that will be used as a value of the **client\_assertion** in a token request.
### Preparing a JWT payload
First, create a JSON formatted payload and save it as "payload.json".
```json theme={null}
{
"jti": "myJWTId001",
"sub": "38174623762",
"iss": "38174623762",
"aud": "http://localhost:4000/api/auth/token/direct/24523138205",
"exp": 1536165540,
"iat": 1536132708
}
```
### Preparing a JWK set
Then, prepare a JWK set for signing and verification. Here we use [mkjwk.org](https://mkjwk.org/)
to generate a JWK set.\\
The examples below are ones generated using `ES256` algorithm, and saved the public and private key pair as a file "key\_pair.jwk".
> Make sure to register the public key (the latter one) to Authlete and configure Client Authentication Method (PRIVATE\_KEY\_JWT) and Client Assertion Algorithm (ES256). These settings can be done via Client Developer Console, as described in the previous section.
* Public and private key pair
```json theme={null}
{
"kty": "EC",
"d": "ukQKQexNI8PtEv7SKpqUDnbZ-WkN6HaQqcVrVV8ZWRQ",
"use": "sig",
"crv": "P-256",
"x": "9Yxd2TvwBbgmupZh3bpg3umKihM_FNAk2_uI_-Edv_Q",
"y": "BOUFuyvWoBZ9-RVSeHJLF-L4I3ORv0xbaM1CKCFJr54",
"alg": "ES256"
}
```
* Public key (to be registered to Authlete via Client Developer Console)
```json theme={null}
{
"kty": "EC",
"use": "sig",
"crv": "P-256",
"x": "9Yxd2TvwBbgmupZh3bpg3umKihM_FNAk2_uI_-Edv_Q",
"y": "BOUFuyvWoBZ9-RVSeHJLF-L4I3ORv0xbaM1CKCFJr54",
"alg": "ES256"
}
```
### Generating a JWT
Generate a JWT assertion including the payload and signed with the private key. The example below is an instruction using an [authlete-jose library](https://github.com/authlete/authlete-jose)
. Or you can use [mkjose.org](https://mkjose.org/)
website to do that.
```bash theme={null}
bin/jose-generator \
--payload-file payload.json \
--sign \
--signing-alg ES256 \
--jwk-signing-alg-file key_pair.jwk
```
The generated JWT will look like this (with line breaks for display purposes only):
```plaintext theme={null}
eyJhbGciOiJFUzI1NiJ9.
ewogICJqdGkiOiJteUpXVElkMDAxIiwKICAic3ViIjoiMzgxNzQ2MjM3NjIiL
AogICJpc3MiOiIzODE3NDYyMzc2MiIsCiAgImF1ZCI6Imh0dHA6Ly9sb2NhbG
hvc3Q6NDAwMC9hcGkvYXV0aC90b2tlbi9kaXJlY3QvMjQ1MjMxMzgyMDUiLAo
gICJleHAiOjE1MzYxNjU1NDAsCiAgImlhdCI6MTUzNjEzMjcwOAp9Cg.
YB4gdhWUGRjWEsEbKDs7-G2WFH2oYz7bAEP5AtegHXInkY9ncA2V3IoA6O_HV
QuFxyCRIklrxsMk32MfNF_ABA
```
This JWT is a value of `client_assertion`, to be used by the client on making a token request.
## Token request and response
### Token request from the client to the authorization server
Assume the client that has the assertion makes a token request to the authorization server. (folded for readability)
```plaintext theme={null}
POST /token 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=eyJhbGciOiJFUzI1NiJ9.ewogICJqdGkiOiJteUpXVElkMDAxIiwKICAic3ViIjoiMzgxNzQ2MjM3NjIiLAogICJpc3MiOiIzODE3NDYyMzc2MiIsCiAgImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAwMC9hcGkvYXV0aC90b2tlbi9kaXJlY3QvMjQ1MjMxMzgyMDUiLAogICJleHAiOjE1MzYxNjU1NDAsCiAgImlhdCI6MTUzNjEzMjcwOAp9Cg.YB4gdhWUGRjWEsEbKDs7-G2WFH2oYz7bAEP5AtegHXInkY9ncA2V3IoA6O_HVQuFxyCRIklrxsMk32MfNF_ABA
```
### API request from the authorization server to Authlete
The authorization server forwards the request content to Authlete's [/auth/token](/api-reference/token-endpoint/process-token-request). (folded for readability)
```bash theme={null}
$ curl -s -X POST https://us.authlete.com/api/auth/token \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-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=eyJhbGciOiJFUzI1NiJ9.ewogICJqdGkiOiJteUpXVElkMDAxIiwKICAic3ViIjoiMzgxNzQ2MjM3NjIiLAogICJpc3MiOiIzODE3NDYyMzc2MiIsCiAgImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6NDAwMC9hcGkvYXV0aC90b2tlbi9kaXJlY3QvMjQ1MjMxMzgyMDUiLAogICJleHAiOjE1MzYxNjU1NDAsCiAgImlhdCI6MTUzNjEzMjcwOAp9Cg.YB4gdhWUGRjWEsEbKDs7-G2WFH2oYz7bAEP5AtegHXInkY9ncA2V3IoA6O_HVQuFxyCRIklrxsMk32MfNF_ABA"
}'
```
### API response from Authlete to the authorization server
Authlete processes the request and sends back an API response to the authorization server as follows. (folded for readability)
```json theme={null}
{
"type": "tokenResponse",
"resultCode": "A050001",
"resultMessage": "[A050001] The token request (grant_type=authorization_code) was processed successfully.",
"accessToken": "ni6uDszfkeR5GH96k3cUjt3R7MHG9-xRbMDObaKGY2A",
"responseContent": {
"access_token": "ni6uDszfkeR5GH96k3cUjt3R7MHG9-xRbMDObaKGY2A",
"refresh_token": "dyzc8D96hSdrCmaPaB75uFiqjWTIWHXq-_OjVN17gAk",
"scope": null,
"token_type": "Bearer",
"expires_in": 3600
},
...
}
```
### Token response from the authorization server to the client
The authorization server extracts the value of "responseContent" and sends it back to the client as a token response (details omitted).
## See Also
* [Configuring Client Authentication](/configuration-reference/endpoints/configuring-client-authentication)
> This article describes basics of client authentication configuration in Authlete.
* [Client Authentication Using client\_secret\_jwt Method](/configuration-reference/endpoints/client-authentication-using-client-secret-jwt-method)
> Authlete supports **client\_secret\_jwt** as a client authentication method so authorization servers can enable it. This article describes overview of the method and setup instructions with Authlete.
* [OAuth 2.0 Client Authentication - Takahiko Kawasaki - Medium](https://medium.com/@darutk/oauth-2-0-client-authentication-4b5f929305d4)
> This article explains “**OAuth 2.0 client authentication**”. In addition to the client authentication methods described in [RFC 6749](https://tools.ietf.org/html/rfc6749)
> , this article explains methods that utilize a client assertion and a client certificate.