docs: add DPoP example

Author: panva

README.md

@@ -54,6 +54,7 @@ import * as client from 'openid-client'
 - Authorization Code Flow (OAuth 2.0) - [source](examples/oauth.ts)
 - Authorization Code Flow (OpenID Connect) - [source](examples/oidc.ts) | [diff](examples/oidc.diff)
 - Extensions
+  - DPoP - [source](examples/dpop.ts) | [diff](examples/dpop.diff)
   - JWT Secured Authorization Request (JAR) - [source](examples/jar.ts) | [diff](examples/jar.diff)
   - JWT Secured Authorization Response Mode (JARM) - [source](examples/jarm.ts) | [diff](examples/jarm.diff)
   - Pushed Authorization Request (PAR) - [source](examples/par.ts) | [diff](examples/par.diff)

examples/.update-diffs.sh

@@ -1,4 +1,5 @@
 git diff HEAD:examples/oauth.ts examples/oidc.ts > examples/oidc.diff
 git diff HEAD:examples/oauth.ts examples/par.ts > examples/par.diff
+git diff HEAD:examples/oauth.ts examples/dpop.ts > examples/dpop.diff
 git diff HEAD:examples/oauth.ts examples/jar.ts > examples/jar.diff
 git diff HEAD:examples/oauth.ts examples/jarm.ts > examples/jarm.diff

examples/README.md

@@ -19,6 +19,7 @@ A collection of examples for the most common use cases.
 - Authorization Code Flow (OAuth 2.0) - [source](oauth.ts)
 - Authorization Code Flow (OpenID Connect) - [source](oidc.ts) | [diff](oidc.diff)
 - Extensions
+  - DPoP - [source](dpop.ts) | [diff](dpop.diff)
   - JWT Secured Authorization Request (JAR) - [source](jar.ts) | [diff](jar.diff)
   - JWT Secured Authorization Response Mode (JARM) - [source](jarm.ts) | [diff](jarm.diff)
   - Pushed Authorization Request (PAR) - [source](par.ts) | [diff](par.diff)

examples/dpop.diff

@@ -0,0 +1,55 @@
+diff --git a/examples/oauth.ts b/examples/dpop.ts
+index dde3bbc..dcd9ff2 100644
+--- a/examples/oauth.ts
++++ b/examples/dpop.ts
+@@ -12,10 +12,19 @@ let clientSecret!: string
+  */
+ let redirect_uri!: string
+ 
++/**
++ * In order to take full advantage of DPoP you shall generate a random key pair
++ * for every session. In the browser environment you shall use IndexedDB to
++ * persist the generated CryptoKeyPair.
++ */
++let DPoPKeys!: client.CryptoKeyPair
++
+ // End of prerequisites
+ 
+ let config = await client.discovery(server, clientId, clientSecret)
+ 
++let DPoP = client.getDPoPHandle(config, DPoPKeys)
++
+ let code_challenge_method = 'S256'
+ /**
+  * The following (code_verifier and potentially state) MUST be generated for
+@@ -58,10 +67,16 @@ let state!: string
+ let access_token: string
+ {
+   let currentUrl: URL = getCurrentUrl()
+-  let tokens = await client.authorizationCodeGrant(config, currentUrl, {
+-    pkceCodeVerifier: code_verifier,
+-    expectedState: state,
+-  })
++  let tokens = await client.authorizationCodeGrant(
++    config,
++    currentUrl,
++    {
++      pkceCodeVerifier: code_verifier,
++      expectedState: state,
++    },
++    undefined,
++    { DPoP },
++  )
+ 
+   console.log('Token Endpoint Response', tokens)
+   ;({ access_token } = tokens)
+@@ -74,6 +89,9 @@ let access_token: string
+     access_token,
+     new URL('https://rs.example.com/api'),
+     'GET',
++    undefined,
++    undefined,
++    { DPoP },
+   )
+ 
+   console.log('Protected Resource Response', await protectedResource.json())

examples/dpop.ts

@@ -0,0 +1,98 @@
+import * as client from 'openid-client'
+
+// Prerequisites
+
+let getCurrentUrl!: (...args: any) => URL
+let server!: URL // Authorization server's Issuer Identifier URL
+let clientId!: string
+let clientSecret!: string
+/**
+ * Value used in the authorization request as redirect_uri pre-registered at the
+ * Authorization Server.
+ */
+let redirect_uri!: string
+
+/**
+ * In order to take full advantage of DPoP you shall generate a random key pair
+ * for every session. In the browser environment you shall use IndexedDB to
+ * persist the generated CryptoKeyPair.
+ */
+let DPoPKeys!: client.CryptoKeyPair
+
+// End of prerequisites
+
+let config = await client.discovery(server, clientId, clientSecret)
+
+let DPoP = client.getDPoPHandle(config, DPoPKeys)
+
+let code_challenge_method = 'S256'
+/**
+ * The following (code_verifier and potentially state) MUST be generated for
+ * every redirect to the authorization_endpoint. You must store the
+ * code_verifier and state in the end-user session such that it can be recovered
+ * as the user gets redirected from the authorization server back to your
+ * application.
+ */
+let code_verifier = client.randomPKCECodeVerifier()
+let code_challenge = await client.calculatePKCECodeChallenge(code_verifier)
+let state!: string
+
+{
+  // redirect user to as.authorization_endpoint
+  let parameters: Record<string, string> = {
+    redirect_uri,
+    scope: 'api:read',
+    code_challenge,
+    code_challenge_method,
+  }
+
+  /**
+   * We cannot be sure the AS supports PKCE so we're going to use state too. Use
+   * of PKCE is backwards compatible even if the AS doesn't support it which is
+   * why we're using it regardless.
+   */
+  if (!config.serverMetadata().supportsPKCE()) {
+    state = client.randomState()
+    parameters.state = state
+  }
+
+  let redirectTo = client.buildAuthorizationUrl(config, parameters)
+
+  console.log('redirecting to', redirectTo.href)
+  // now redirect the user to redirectTo.href
+}
+
+// one eternity later, the user lands back on the redirect_uri
+// Authorization Code Grant
+let access_token: string
+{
+  let currentUrl: URL = getCurrentUrl()
+  let tokens = await client.authorizationCodeGrant(
+    config,
+    currentUrl,
+    {
+      pkceCodeVerifier: code_verifier,
+      expectedState: state,
+    },
+    undefined,
+    { DPoP },
+  )
+
+  console.log('Token Endpoint Response', tokens)
+  ;({ access_token } = tokens)
+}
+
+// Protected Resource Request
+{
+  let protectedResource = await client.fetchProtectedResource(
+    config,
+    access_token,
+    new URL('https://rs.example.com/api'),
+    'GET',
+    undefined,
+    undefined,
+    { DPoP },
+  )
+
+  console.log('Protected Resource Response', await protectedResource.json())
+}