DPoP support for Client Credentials flow

Identify OAuth 2.0 supports Demonstration of Proof-of-Possession (DPoP) for the Client Credentials flow. DPoP enhances security by binding access tokens to a specific client, preventing token misuse if intercepted. This is particularly useful in scenarios where clients need to prove possession of a private key when making requests to protected resources. For more information, refer to OAuth 2.0 Demonstrating Proof of Possession (DPoP).

What is DPoP?

DPoP is a security mechanism that allows clients to demonstrate possession of a private key when making requests to protected resources. It involves the use of DPoP proofs, which are JSON Web Tokens (JWTs) that include claims about the HTTP method and URI of the request, as well as a unique identifier and timestamp. These proofs are signed using the client's private key.

+--------+                                          +---------------+
|        |------- Token Request ------------------->|  Identify     |
| Client |   (Client Credentials with DPoP Proof)   |  OAuth 2.0    |
|        |                                          |  Server       |
|        |<------ DPoP-Bound Access Token ----------|               |
|        |        (token_type=DPoP)                 +---------------+
|        |
|        |
|        |                                          +---------------+
|        |------- DPoP-Bound Access Token --------->|               |
|        |        (DPoP Proof)                      |    Resource   |
|        |                                          |     Server    |
|        |<------ Protected Resource ---------------|               |
|        |                                          +---------------+
+--------+

Note: Only the Client Credentials flow is supported.

When a client requests an access token using the Client Credentials flow, it includes a DPoP proof in the request. The authorization server validates the proof and issues an access token that is bound to the DPoP proof. This means that the access token can only be used by the client that possesses the corresponding private key, enhancing security by preventing token misuse.

Signing algorithms supported

Identify supports the following signing algorithms for DPoP proofs: RS256, RS384, RS512, PS256, PS384 and PS512.

How DPoP with Client Credentials Flow works

To use DPoP with the Client Credentials flow, follow these steps:

  1. Register the OAuth 2.0 Application: Ensure that your OAuth 2.0 application is registered in Identify with the appropriate settings for Client Credentials flow.

  2. Generate DPoP Key Pair: The client must generate a public/private key pair to be used for DPoP. The private key will be used to sign DPoP proofs, while the public key will be provided as the jwk header of DPoP JWT.

  3. Create DPoP Proofs: For each request to the token endpoint, the client must create a DPoP proof JWT. This JWT should include claims such as htm (HTTP method), htu (HTTP URI), jti (JWT ID), and iat (issued at time). The JWT must be signed using the client's private key.

Header example of a DPoP proof JWT:

{
  "alg": "PS256",
  "typ": "dpop+jwt",
  "jwk": {
    "kty": "RSA",
    "e": "AQAB",
    "n": "1sysHo9lUj0ag2fsFiin2vPWa22cgzhT4ZDE6IEJodtPrDfieDRqN5i24qZvvTH86XmiIiu2IHRPIxKK4B8XQnxNql8R8pamnydCl99b9uHX7TCYxbD79hryMqVGrnjUFLW8fCzHtZHxiOCq_-yFGuszV5SOvsz-TWZA3LtMhVKGPL8WyO4bxAQa1nTiPN_Bqy86mF2qrJM8Fj4XlxjnOe2q0I7t_Oqg1xcrwtLPGV-xP9sTSmOZmCWHWWXO3DvPjJiQdrkkTlHSR8xU_E3BtOEYr0K6A0_NCq7AehC4_WJRIsVcDf_eTaOqdRVzZV-GV2kem_JXjfIa0SsYPnM6kQ"
  }
}

Payload example of a DPoP proof JWT:

{
  "jti": "iAGnp_2kfmdGMDE-uEY5HaiiHRx_L1eESLDTe2diQ88",
  "htm": "POST",
  "htu": "https://identify01.identify.safewhere.com/runtime/oauth2/mtls/token.idp",
  "iat": 1766574479
}

  1. Request Access Token: When requesting an access token using the Client Credentials flow, the client must include the DPoP proof in the DPoP HTTP header of the token request.

  2. Validate DPoP Proofs: Identify will validate the DPoP proof included in the token request. If valid, it will issue an access token bound to the DPoP proof.

By following these steps, clients can securely obtain an access token through the Client Credentials flow using DPoP against the Identity OAuth 2 server, ensuring strong protection against token misuse.

Using the DPoP-Bound Access Token

When making requests to protected resources, the client must include the DPoP-Bound access token in the Authorization header and a new DPoP proof in the DPoP header for each request. Note that the token type of the Authorization header should be DPoP (not Bearer), indicating that the access token is bound to a DPoP proof.

Example token request with DPoP

Here is an example of how to request an access token using the Client Credentials flow with DPoP:

POST https://identify01.identify.safewhere.com/runtime/oauth2/mtls/token.idp HTTP/1.1
Host: identify01.identify.safewhere.com
DPoP: eyJhbGciOiJQUzI1NiIsInR5cCI6ImRwb3Arand0IiwiandrIjp7Imt0eSI6IlJTQSIsImUiOiJBUUFCIiwibiI6IjlkTDNBb3FpRGt2cktRVGZPWXM1OHhYcGNDWXJlSUIzeEItT3pKRVZmT1V2dkxHRVVNUEtnRlJ2NTRCTEJDUjhqOUhFbVlrSHF5eEdCVDVKRVRSTlNXSno3bU1obXRwSWZJR2ZCaTRGUVc0cjYtOEs0QlNKc1ZLQllDclpnZUtIUW5DMGZCX3NVUHVlZ2lfNFFFTEtsT0FhTm1QMW1QWDdFb2FUZTR6cFhGME81Rl9FN3RaWWlfVjMtV3RQSXBVb2NNczd4SENiSE5HR0tfZThKcVZBV1RHZFI3RHFuSy14WlJSU2EtMWRXcVJXTDJ6YmRqUkZQenV5SzI4Wml3eF8wMzZiUjFtanVJby1IMDdNbmxQVWJZbjNVMzV1cEtteVBmS3FGbkdlSFBTRHRmZXdpeHZfZFR6X0t4TThPYmpiekNZYlpZeWFPdkxmdmpxdTB1cUJhUSJ9fQ.eyJqdGkiOiJjNHFHeUlVNV8tU291WkFkWU92VVNMM21rZkVVOEhOeFI4NHVqNVp5VUo4IiwiaHRtIjoiUE9TVCIsImh0dSI6Imh0dHBzOi8vaWRlbnRpZnkwMS5pZGVudGlmeS5zYWZld2hlcmUuY29tL3J1bnRpbWUvb2F1dGgyL210bHMvdG9rZW4uaWRwIiwiaWF0IjoxNzY2NTc0OTkxfQ.BLtZrWCiE795tNIKHQtHTNe44_R2DpvlgN34xm9FSd0cCFviW-um1DBpCpJT50mubgvEoxdLTyJYbhVI4M2wyyMWuI_dr4bKeKnzYp20EQRD6yqbRdymIMlBunDexgrkjJTkP5vcTyIasY8pQM66VaJyrGODq34RQ4Fw8mWkH664Yq0f1Q4tdTzETOBzWmejeKvjD24qYGyT4Zso5cvZQgyzA5ycuOOVpWXAstkKaQpHZnCZ51SNPS9Xy8JDC1THFdhIaIW3PvbYK9Dcu16WxFGk1RmTppZZKvBJ_0U3sYnXq5JKPox2hy_oSFRgvsBvPrKAe9Iz9vnrM6nZh56-Vw
Content-Type: application/x-www-form-urlencoded

client_id=clientid_mTLS-console-app&grant_type=client_credentials

Successful response

A token_type of DPoP is included in the access token response to signal to the client that the access token was bound to its DPoP key:

{
    "scope": "identify*empty",
    "token_type": "DPoP",
    "access_token": "eyJhbGciOiJSUzI1NiIsImt...y53OVTiKlZkvKfeD4zfiOjr-_Ztw28g",
    "expires_in": 360000
}

The payload of the access token contains a cnf claim with the jkt JWK Thumbprint confirmation method member:

{
  "token_usage": "access_token",
  "sub": "clientid_mTLS-console-app",
  ...
  "aud": "https://localhost:7102/",
  "azp": "clientid_mTLS-console-app",
  "iat": 1766574993,
  "cnf": {
    "x5t#S256": "FumM1Xqmy-CEBVNY8ukrerAz6JGl_qdzv2ei14RqZNY",
    "jkt": "1zRKTMIO0iBhYO0CQmRRRHAJlZu6YNk3Z3Vm0V6Qbac"
  },
  "nbf": 1766574993,
  "exp": 1766934993,
  "iss": "https://identify01.identify.safewhere.com/runtime/oauth2"
}

The client can use the access token in requests to protected resources by including it in the Authorization header along with a new DPoP proof in the DPoP header.

Error response

When a DPoP proof is not valid, for example, its typ JOSE Header Parameter does not have the value dpop+jwt, Identify returns an error response with the error parameter value set to invalid_request:

{
    "error": "invalid_request",
    "error_description": "The DPoP proof must have 'typ' header set to 'dpop+jwt'."
}

Samples

The client and API demo from this GitHub link: https://github.com/Safewhere/OIDC/tree/master/src/CSharp/mtls-client

Conclusion

Implementing DPoP with the Client Credentials flow in Identify enhances the security of access tokens by ensuring that they are bound to a specific client. This prevents unauthorized use of tokens and provides an additional layer of protection for sensitive resources. By following the outlined steps, developers can effectively integrate DPoP into their OAuth 2.0 implementations.