feat: add Client-Initiated Backchannel Authentication

panva · Feb 17, 2025 · fe6d996 · fe6d996
1 parent d3629c9
commit fe6d996
Show file tree

Hide file tree

Showing 13 changed files with 613 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@ The following features are currently in scope and implemented in this software:
 
 - Authorization Server Metadata discovery
 - Authorization Code Flow (profiled under OpenID Connect 1.0, OAuth 2.0, OAuth 2.1, FAPI 1.0 Advanced, and FAPI 2.0)
-- Refresh Token, Device Authorization, and Client Credentials Grants
+- Refresh Token, Device Authorization, Client-Initiated Backchannel Authentication, and Client Credentials Grants
 - Demonstrating Proof-of-Possession at the Application Layer (DPoP)
 - Token Introspection and Revocation
 - Pushed Authorization Requests (PAR)
@@ -182,6 +182,27 @@ console.log('Token Endpoint Response', tokens)
 
 This will poll in a regular interval and only resolve with tokens once the end-user authenticates.
 
+### Client-Initiated Backchannel Authentication (CIBA)
+
+```ts
+let scope!: string // Scope of the access request
+let login_hint!: string // one of login_hint, id_token_hint, or login_hint_token parameters must be provided in CIBA
+
+let response = await client.initiateBackchannelAuthentication(config, {
+  scope,
+  login_hint,
+})
+
+// OPTIONAL: If your client is configured with Ping Mode you'd invoke the following after getting the CIBA Ping Callback (its implementation is framework specific and therefore out of scope for openid-client)
+
+let tokens: client.TokenEndpointResponse =
+  await client.pollBackchannelAuthenticationGrant(config, response)
+
+console.log('Token Endpoint Response', tokens)
+```
+
+This will poll in a regular interval and only resolve with tokens once the end-user authenticates.
+
 ### Client Credentials Grant
 
 Client Credentials flow is for obtaining Access Tokens to use with third party APIs on behalf of your application, rather than an end-user which was the case in previous examples.

diff --git a/docs/README.md b/docs/README.md
@@ -22,7 +22,9 @@ Support from the community to continue maintaining and improving this module is
 - [authorizationCodeGrant](functions/authorizationCodeGrant.md)
 - [clientCredentialsGrant](functions/clientCredentialsGrant.md)
 - [genericGrantRequest](functions/genericGrantRequest.md)
+- [initiateBackchannelAuthentication](functions/initiateBackchannelAuthentication.md)
 - [initiateDeviceAuthorization](functions/initiateDeviceAuthorization.md)
+- [pollBackchannelAuthenticationGrant](functions/pollBackchannelAuthenticationGrant.md)
 - [pollDeviceAuthorizationGrant](functions/pollDeviceAuthorizationGrant.md)
 - [refreshTokenGrant](functions/refreshTokenGrant.md)
 
@@ -95,6 +97,8 @@ Support from the community to continue maintaining and improving this module is
 - [AuthorizationCodeGrantChecks](interfaces/AuthorizationCodeGrantChecks.md)
 - [AuthorizationCodeGrantOptions](interfaces/AuthorizationCodeGrantOptions.md)
 - [AuthorizationDetails](interfaces/AuthorizationDetails.md)
+- [BackchannelAuthenticationGrantPollOptions](interfaces/BackchannelAuthenticationGrantPollOptions.md)
+- [BackchannelAuthenticationResponse](interfaces/BackchannelAuthenticationResponse.md)
 - [ConfigurationMethods](interfaces/ConfigurationMethods.md)
 - [ConfigurationProperties](interfaces/ConfigurationProperties.md)
 - [ConfirmationClaims](interfaces/ConfirmationClaims.md)

diff --git a/docs/functions/initiateBackchannelAuthentication.md b/docs/functions/initiateBackchannelAuthentication.md
@@ -0,0 +1,43 @@
+# Function: initiateBackchannelAuthentication()
+
+[💗 Help the project](https://github.com/sponsors/panva)
+
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
+***
+
+▸ **initiateBackchannelAuthentication**(`config`, `parameters`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`BackchannelAuthenticationResponse`](../interfaces/BackchannelAuthenticationResponse.md)\>
+
+Initiates a [Client-Initiated Backchannel Authentication Grant](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) using
+parameters from the `parameters` argument.
+
+Note:
+[URL of the authorization server's backchannel authentication endpoint](../interfaces/ServerMetadata.md#backchannel_authentication_endpoint)
+must be configured.
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `config` | [`Configuration`](../classes/Configuration.md) | - |
+| `parameters` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)\<`string`, `string`\> \| [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) | Authorization request parameters that will be sent to the backchannel authentication endpoint |
+
+## Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`BackchannelAuthenticationResponse`](../interfaces/BackchannelAuthenticationResponse.md)\>
+
+## Example
+
+```ts
+let config!: client.Configuration
+let scope!: string
+let login_hint!: string
+
+let backchannelAuthenticationResponse =
+  await client.initiateBackchannelAuthentication(config, {
+    scope,
+    login_hint,
+  })
+
+let { auth_req_id } = backchannelAuthenticationResponse
+```
diff --git a/docs/functions/pollBackchannelAuthenticationGrant.md b/docs/functions/pollBackchannelAuthenticationGrant.md
@@ -0,0 +1,52 @@
+# Function: pollBackchannelAuthenticationGrant()
+
+[💗 Help the project](https://github.com/sponsors/panva)
+
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
+***
+
+▸ **pollBackchannelAuthenticationGrant**(`config`, `backchannelAuthenticationResponse`, `parameters`?, `options`?): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`TokenEndpointResponse`](../interfaces/TokenEndpointResponse.md) & [`TokenEndpointResponseHelpers`](../interfaces/TokenEndpointResponseHelpers.md)\>
+
+Continuously polls the [token endpoint](../interfaces/ServerMetadata.md#token_endpoint)
+until the end-user finishes the
+[Client-Initiated Backchannel Authentication Grant](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) process
+
+Note:
+[URL of the authorization server's token endpoint](../interfaces/ServerMetadata.md#token_endpoint)
+must be configured.
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `config` | [`Configuration`](../classes/Configuration.md) | - |
+| `backchannelAuthenticationResponse` | [`BackchannelAuthenticationResponse`](../interfaces/BackchannelAuthenticationResponse.md) | Backchannel Authentication Response obtained from [initiateBackchannelAuthentication](initiateBackchannelAuthentication.md) |
+| `parameters`? | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)\<`string`, `string`\> \| [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) | Additional parameters that will be sent to the token endpoint, typically used for parameters such as `scope` and a `resource` ([Resource Indicator](https://www.rfc-editor.org/rfc/rfc8707)) |
+| `options`? | [`BackchannelAuthenticationGrantPollOptions`](../interfaces/BackchannelAuthenticationGrantPollOptions.md) | - |
+
+## Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`TokenEndpointResponse`](../interfaces/TokenEndpointResponse.md) & [`TokenEndpointResponseHelpers`](../interfaces/TokenEndpointResponseHelpers.md)\>
+
+## Example
+
+```ts
+let config!: client.Configuration
+let scope!: string
+let login_hint!: string
+
+let backchannelAuthenticationResponse =
+  await client.initiateBackchannelAuthentication(config, {
+    scope,
+    login_hint,
+  })
+
+let { auth_req_id } = backchannelAuthenticationResponse
+
+let tokenEndpointResponse =
+  await client.pollBackchannelAuthenticationGrant(
+    config,
+    backchannelAuthenticationResponse,
+  )
+```
diff --git a/docs/interfaces/BackchannelAuthenticationGrantPollOptions.md b/docs/interfaces/BackchannelAuthenticationGrantPollOptions.md
@@ -0,0 +1,30 @@
+# Interface: BackchannelAuthenticationGrantPollOptions
+
+[💗 Help the project](https://github.com/sponsors/panva)
+
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
+***
+
+## Properties
+
+### DPoP?
+
+• `optional` **DPoP**: [`DPoPHandle`](DPoPHandle.md)
+
+DPoP handle to use for requesting a sender-constrained access token.
+Obtained from [getDPoPHandle](../functions/getDPoPHandle.md)
+
+#### See
+
+[RFC 9449 - OAuth 2.0 Demonstrating Proof of Possession (DPoP)](https://www.rfc-editor.org/rfc/rfc9449.html)
+
+***
+
+### signal?
+
+• `optional` **signal**: [`AbortSignal`](https://developer.mozilla.org/docs/Web/API/AbortSignal)
+
+AbortSignal to abort polling. Default is that the operation will time out
+after the indicated expires_in property returned by the server in
+[initiateBackchannelAuthentication](../functions/initiateBackchannelAuthentication.md)
diff --git a/docs/interfaces/BackchannelAuthenticationResponse.md b/docs/interfaces/BackchannelAuthenticationResponse.md
@@ -0,0 +1,36 @@
+# Interface: BackchannelAuthenticationResponse
+
+[💗 Help the project](https://github.com/sponsors/panva)
+
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
+***
+
+## Indexable
+
+\[`parameter`: `string`\]: `undefined` \| [`JsonValue`](../type-aliases/JsonValue.md)
+
+## Properties
+
+### auth\_req\_id
+
+• `readonly` **auth\_req\_id**: `string`
+
+Unique identifier to identify the authentication request.
+
+***
+
+### expires\_in
+
+• `readonly` **expires\_in**: `number`
+
+The lifetime in seconds of the "auth_req_id".
+
+***
+
+### interval?
+
+• `readonly` `optional` **interval**: `number`
+
+The minimum amount of time in seconds that the client should wait between polling requests to
+the token endpoint.
diff --git a/patches/typedoc-plugin-mdn-links+4.0.8.patch b/patches/typedoc-plugin-mdn-links+4.0.8.patch
@@ -1,8 +1,8 @@
 diff --git a/node_modules/typedoc-plugin-mdn-links/data/web-api.json b/node_modules/typedoc-plugin-mdn-links/data/web-api.json
-index d84389e..56bf890 100644
+index e92381a..96a13c4 100644
 --- a/node_modules/typedoc-plugin-mdn-links/data/web-api.json
 +++ b/node_modules/typedoc-plugin-mdn-links/data/web-api.json
-@@ -1,4 +1,34 @@
+@@ -1,4 +1,37 @@
  {
 +	"OIDC": {
 +		"url": "https://openid.net/specs/openid-connect-core-1_0.html"
@@ -22,6 +22,9 @@ index d84389e..56bf890 100644
 +	"Device Authorization Grant": {
 +		"url": "https://www.rfc-editor.org/rfc/rfc8628.html"
 +	},
++	"Client-Initiated Backchannel Authentication Grant": {
++		"url": "https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html"
++	},
 +	"Resource Indicators": {
 +		"url": "https://www.rfc-editor.org/rfc/rfc8707"
 +	},