Using DPoP

Preface

This article describes how to support “RFC 9449: OAuth 2.0 Demonstrating Proof-of-Possession (DPoP) " with Authlete APIs.

This feature is available in Authlete version 2.2 or later.

Instructions

Authorization servers and resource servers support DPoP by following these steps.

1. Receiving a request that includes a “DPoP Proof JWT”

   • A endpoint (EP) of an authorization server (e.g., Token EP, PAR EP, UserInfo EP) or a resource server receives a request, with “DPoP Proof JWT” as one of HTTP headers, from a client.

2. Extracting DPoP-related information

   • The server extracts DPoP-related information (DPoP Proof JWT, HTTP method and HTTP target URI) from the request.

3. Making a request to Authlete’s APIs

   • The server make a request, that includes the content of the client’s request and the above DPoP-related information as request parameters,  to Authlete APIs (/auth/token, /auth/introspection, etc.)

   ---

Example

The following is an example of how to support DPoP in an authorization server’s token EP.

1. Receiving a request that includes a “DPoP Proof JWT”

Let us assume that the authorization server’s token EP receives the following HTTP request. (wrapped for readability)

POST /token HTTP/1.1
Host: as.example.com
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IlJTMjU2IiwiandrIjp7Imt0eSI6IlJ
       JTQSIsImUiOiJBUUFCIiwidXNlIjoic2lnIiwia2lkIjoib3A4cTNIaUNPVHQtej
       BmUE1kanZsV21WN2QwS2FxVG9xcDNlZF9wdHA1QSIsImFsZyI6IlJTMjU2Iiwibi
       I6ImdadHZ5VmRCb1ZEVTZHVTFLOGE2eHphb2EwR0F6dE9wcG1zRVZFN1NDZFpjT2
       9WanpURlNRSnBXa0RQQmktNzBmeHdtc041c016Q3RPeXZ1Sk5XcFk5RHFUb0lWYX
       bXM2VJOFRIU3dNNnZ0bXpNSWt5WDY0RXdZb2VuN2twbkhtZ3VDWUZ6dWxLM2FKZz
       JKWFpOWXl1YTFuTTRmSGs3TnA0UlhTYmFBb2p5THR0SVFCSXZpOFVPcVI1dEYwaXZ
       CQzRKSGxnUDVZTjNjTjIxOEFqeTVmcHFJdi1naE0zcmhtZjJuZFNpWnU2R3JPNmdP
       OXFyaE05NXJRcEprSDlMcmdQaEE2ZkhQWVB3WnR5dEpBVGNVd1FWTThKTmwybTFWR
       zlXS1o0SjdTTGJxdVNNNUZ4b29Oekc2dmZBWlhWLTBVTVBqSU5TZ3dJMDdBYi1Ocn
       ZBUHNKUSJ9fQ.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIjoiUE9TVCIsIm
       h0dSI6Imh0dHBzOi8vYXMuZXhhbXBsZS5jb20vdG9rZW4iLCJpYXQiOjE2NzkzMDg3
       NDN9.VOoyMJVR5RwyOWDGF42Oc_AElsGf6x2ZLW-X
       Y8g8xXbH7WMdGKeSY0Mm8YIXblviyBCgD0y6oQH07Ds5uEtH0GSO15z5brawJmivr
       UyiIiaH6UK2GKE42HNHrQ29Ln66cEqbDYxizN4hfu9yqoQgGEw6oRhiQaOLDLyzGE
       QQRMkDPEz2LwhfsUhSzWPjtyhj2WBobH5WaNCybo6SBI2eGj1Pj97PdREK0luR7rn
       3AU_N-PtIDFNeXbtYjRcE6NNrfSCWcrkLcuOHuKgPv61-OuqQ0jRbLpkyhTWjxtmj
       zOuzWspfvg8ln8bOaw_y4VOspvUL5FBGI6P-RXBlBUrKow
...

grant_type=authorization_code&scope=read&
redirect_uri={redirect_uri}&code={code}&client_id={client_id}

2. Extracting DPoP-related information

The authorization server detects a DPoP header in the request, and extracts HTTP method, HTTP target URI and DPoP Proof JWT. These values are then included in a request to Authlete’s /auth/token API , as htm, htu and dpop respectively.

The following table shows the values in this example.

eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IlJTMjU2IiwidHlwIjoiYXQrand0In0.eyJraWQ
iOiJvOGpsc1IydXBkcnRjZ280NU5CejFrdDJ6aWg4cHNKV09KUU1lQ3E5OVdGIiwic2lnbm
F0dXJlIjoiZ3Z0MmFNRXJsV0RqVk5ST3U1WlA4R2h3dnBJa0tLVTRjN3hwU1ZyT3ciLCJlb
mMiOiJBMjU2R0NNIiwia2lkIjoib3A4cTNIaUNPVHQtejBmUE1kanZsV21WN2QwS2FxVG9x
cDNlZF9wdHA1USJ9.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIjoiUE9TVCIsIm
h0dSI6Imh0dHBzOi8vYXMuZXhhbXBsZS5jb20vdG9rZW4iLCJpYXQiOjE2NzkzMDg3NDN9.
VOoyMJVR5RwyOWDGF42Oc_AElsGf6x2ZLW-X Y8g8xXbH7WMdGKeSY0Mm8YIXblviyBCgD0
y6oQH07Ds5uEtH0GSO15z5brawJmivrU yiIiaH6UK2GKE42HNHrQ29Ln66cEqbDYxizN4h
fu9yqoQgGEw6oRhiQaOLDLyzGEQQRMKB PEz2LwhfsUhSzWPjtyhj2WBobH5WaNCybo6SBI
2eGj1Pj97PdREK0luR7rn3AU_N-PtI DFNeXbtYjRcE6NNrfSCWcrkLcuOHuKgPv61-OuqQ
0jRbLpkyhTWjxtmjzOuzWspfvg8l n8bOaw_y4VOspvUL5FBGI6P-RXBlBUrKow

3. Making a request to Authlete’s APIs

The following is a request body from the authorization server to the /auth/token API.

{
  "parameters": "grant_type=authorization_code&scope=read&
                 redirect_uri={redirect_uri}&code={code}&client_id={client_id}",
  "htm":"POST",
  "htu":"https://as.example.com/token",
  "dpop":"eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IlJTMjU2IiwiandrIjp7Imt0eSI6IlJTQSIs
          ImUiOiJBUUFCIiwidXNlIjoic2lnIiwia2lkIjoib3A4cTNIaUNPVHQtejBmUE1kanZs
          V21WN2QwS2FxVG9xcDNlZF9wdHA1QSIsImFsZyI6IlJTMjU2IiwibiI6ImdadHZ5VmRC
          b1ZEVTZHVTFLOGE2eHphb2EwR0F6dE9wcG1zRVZFN1NDZFpjT29WanpURlNRSnBXa0RQ
          QmktNzBmeHdtc041c016Q3RPeXZ1Sk5XcFk5RHFUb0lWYXBXM2VJOFRIU3dNNnZ0bXpN
          SWt5WDY0RXdZb2VuN2twbkhtZ3VDWUZ6dWxLM2FKZzJKWFpOWXl1YTFuTTRmSGs3TnA0
          UlhTYmFBb2p5THR0SVFCSXZpOFVPcVI1dEYwaXZCQzRKSGxnUDVZTjNjTjIxOEFqeTVm
          cHFJdi1naE0zcmhtZjJuZFNpWnU2R3JPNmdPOXFyaE05NXJRcEprSDlMcmdQaEE2ZkhQ
          WVB3WnR5dEpBVGNVd1FWTThKTmwybTFWRzlXS1o0SjdTTGJxdVNNNUZ4b29Oekc2dmZB
          WlhWLTBVTVBqSU5TZ3dJMDdBYi1OcnZBUHNKUSJ9fQ.eyJqdGkiOiItQndDM0VTYzZhY
          2MybFRjIiwiaHRtIjoiUE9TVCIsImh0dSI6Imh0dHBzOi8vYXMuZXhhbXBsZS5jb20vd
          G9rZW4iLCJpYXQiOjE2NzkzMDg3NDN9.VOoyMJVR5RwyOWDGF42Oc_AElsGf6x2ZLW-X
          Y8g8xXbH7WMdGKeSY0Mm8YIXblviyBCgD0y6oQH07Ds5uEtH0GSO15z5brawJmivrUyi
          IiaH6UK2GKE42HNHrQ29Ln66cEqbDYxizN4hfu9yqoQgGEw6oRhiQaOLDLyzGEQQRMkB
          PEz2LwhfsUhSzWPjtyhj2WBobH5WaNCybo6SBI2eGj1Pj97PdREK0luR7rn3AU_N-PtI
          DFNeXbtYjRcE6NNrfSCWcrkLcuOHuKgPv61-OuqQ0jRbLpkyhTWjxtmjzOuzWspfvg8l
          n8bOaw_y4VOspvUL5FBGI6P-RXBlBUrKow"
}

Authlete returns the following response if the above request is successful.

{
    "type": "tokenResponse",
    "resultCode": "A050001",
    "resultMessage": "[A050001] The token request (grant_type=authorization_code) was processed successfully.",
    "accessToken": "{access_token}",
    "action": "OK",
    "responseContent": {
        "access_token": "{access_token}",
        "scope": "read",
        "token_type": "DPoP",
        "expires_in": 60
    },
    ...
}

The authorization server will then return a token response to the client with responseContent as its body.