openid-client 5.6.5 → 6.0.0-beta.0

package/README.md

@@ -1,323 +1,226 @@
-# openid-client
-
-openid-client is a server side [OpenID][openid-connect] Relying Party (RP, Client) implementation for
-Node.js runtime, supports [passport][passport-url].
-
-## Implemented specs & features
-
-The following client/RP features from OpenID Connect/OAuth2.0 specifications are implemented by
-openid-client.
-
-- [OpenID Connect Core 1.0][feature-core]
-  - Authorization Callback
-    - Authorization Code Flow
-    - Implicit Flow
-    - Hybrid Flow
-  - UserInfo Request
-  - Offline Access / Refresh Token Grant
-  - Client Credentials Grant
-  - Client Authentication
-    - none
-    - client_secret_basic
-    - client_secret_post
-    - client_secret_jwt
-    - private_key_jwt
-  - Consuming Self-Issued OpenID Provider ID Token response
-- [OpenID Connect Discovery 1.0][feature-discovery]
-  - Discovery of OpenID Provider (Issuer) Metadata
-  - Discovery of OpenID Provider (Issuer) Metadata via user provided inputs (via [webfinger][documentation-webfinger])
-- [OpenID Connect Dynamic Client Registration 1.0][feature-registration]
-  - Dynamic Client Registration request
-  - Client initialization via registration client uri
-- [RFC7009 - OAuth 2.0 Token revocation][feature-revocation]
-  - Client Authenticated request to token revocation
-- [RFC7662 - OAuth 2.0 Token introspection][feature-introspection]
-  - Client Authenticated request to token introspection
-- [RFC8628 - OAuth 2.0 Device Authorization Grant (Device Flow)][feature-device-flow]
-- [RFC8705 - OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens][feature-mtls]
-  - Mutual TLS Client Certificate-Bound Access Tokens
-  - Metadata for Mutual TLS Endpoint Aliases
-  - Client Authentication
-    - tls_client_auth
-    - self_signed_tls_client_auth
-- [RFC9101 - OAuth 2.0 JWT-Secured Authorization Request (JAR)][feature-jar]
-- [RFC9126 - OAuth 2.0 Pushed Authorization Requests (PAR)][feature-par]
-- [RFC9449 - OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)][feature-dpop]
-- [OpenID Connect RP-Initiated Logout 1.0][feature-rp-logout]
-- [Financial-grade API Security Profile 1.0 - Part 2: Advanced (FAPI)][feature-fapi]
-- [JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)][feature-jarm]
-- [OAuth 2.0 Authorization Server Issuer Identification][feature-iss]
-
-Updates to draft specifications are released as MINOR library versions,
-if you utilize these specification implementations consider using the tilde `~` operator in your
-package.json since breaking changes may be introduced as part of these version updates. 
-
-## Certification
-[<img width="184" height="96" align="right" src="https://cdn.jsdelivr.net/gh/panva/node-openid-client@38cf016b0837e6d4116de3780b28d222d5780bc9/OpenID_Certified.png" alt="OpenID Certification">][openid-certified-link]  
-Filip Skokan has [certified][openid-certified-link] that [openid-client][npm-url]
-conforms to the following profiles of the OpenID Connect™ protocol
-
-- Basic, Implicit, Hybrid, Config, Dynamic, and Form Post RP
-- FAPI 1.0 Advanced RP
+# High-Level OAuth 2 / OpenID Connect Client API for JavaScript Runtimes
 
-## Sponsor
+TODO
 
-[<img height="65" align="left" src="https://cdn.auth0.com/blog/github-sponsorships/brand-evolution-logo-Auth0-horizontal-Indigo.png" alt="auth0-logo">][sponsor-auth0] If you want to quickly add OpenID Connect authentication to Node.js apps, feel free to check out Auth0's Node.js SDK and free plan. [Create an Auth0 account; it's free!][sponsor-auth0]<br><br>
+## Features
 
-## Support
+The following features are currently in scope and implemented in this software:
 
-If you or your business use openid-client, please consider becoming a [sponsor][support-sponsor] so I can continue maintaining it and adding new features carefree.
+- 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
+- Demonstrating Proof-of-Possession at the Application Layer (DPoP)
+- Token Introspection and Revocation
+- Pushed Authorization Requests (PAR)
+- UserInfo and Protected Resource Requests
+- Authorization Server Issuer Identification
+- JWT Secured Introspection, Response Mode (JARM), Authorization Request (JAR), and UserInfo
 
+## Sponsor
 
-## Documentation
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./sponsor/Auth0byOkta_dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="./sponsor/Auth0byOkta_light.png">
+  <img height="65" align="left" alt="Auth0 by Okta" src="./sponsor/Auth0byOkta_light.png">
+</picture>
 
-The library exposes what are essentially steps necessary to be done by a relying party consuming
-OpenID Connect Authorization Server responses or wrappers around requests to its endpoints. Aside
-from a generic OpenID Connect [passport][passport-url] strategy it does not expose any framework
-specific middlewares. Those can however be built using the exposed API, one such example is [express-openid-connect][]
+If you want to quickly add authentication to JavaScript apps, feel free to check out Auth0's JavaScript SDK and free plan. [Create an Auth0 account; it's free!][sponsor-auth0]<br><br>
 
-- [openid-client API Documentation][documentation]
-  - [Issuer][documentation-issuer]
-  - [Client][documentation-client]
-  - [Customizing][documentation-customizing]
-  - [TokenSet][documentation-tokenset]
-  - [Strategy][documentation-strategy]
-  - [generators][documentation-generators]
-  - [errors][documentation-errors]
+## [Certification](https://openid.net/certification/faq/)
 
-## Install
+[<img width="96" height="50" align="right" src="https://user-images.githubusercontent.com/241506/166977513-7cd710a9-7f60-4944-aebe-a658e9f36375.png" alt="OpenID Certification">](#certification)
 
-Node.js LTS releases Codename Erbium and newer LTS releases are supported.
+[Filip Skokan](https://github.com/panva) has [certified](https://openid.net/certification) that [this software](https://github.com/panva/openid-client) conforms to the Basic, FAPI 1.0, and FAPI 2.0 Relying Party Conformance Profiles of the OpenID Connect™ protocol.
 
-```console
-npm install openid-client
-```
+## [💗 Help the project](https://github.com/sponsors/panva)
 
-Note: Other javascript runtimes are not supported.
-I recommend [panva/oauth4webapi][oauth4webapi], or a derivate thereof, if you're 
-looking for a similarly compliant and certified client software that's not dependent 
-on the Node.js runtime builtins.
+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).
 
 ## Quick start
 
-Discover an Issuer configuration using its published .well-known endpoints
-```js
-import { Issuer } from 'openid-client';
-
-const googleIssuer = await Issuer.discover('https://accounts.google.com');
-console.log('Discovered issuer %s %O', googleIssuer.issuer, googleIssuer.metadata);
+```ts
+import * as client from 'openid-client'
+
+let server!: URL
+let clientId!: string
+let clientSecret!: string
+let config: client.Configuration = await client.discovery(
+  server,
+  clientId,
+  clientSecret,
+)
 ```
 
 ### Authorization Code Flow
 
 Authorization Code flow is for obtaining Access Tokens (and optionally Refresh Tokens) to use with
-third party APIs securely as well as Refresh Tokens. In this quick start your application also uses
-PKCE instead of `state` parameter for CSRF protection.
-
-Create a Client instance for that issuer's authorization server intended for Authorization Code
-flow.
-
-**See the [documentation][] for full API details.**
-
-```js
-const client = new googleIssuer.Client({
-  client_id: 'zELcpfANLqY7Oqas',
-  client_secret: 'TQV5U29k1gHibH5bx1layBo0OSAvAbRT3UYW3EWrSYBB5swxjVfWUa1BS8lqzxG/0v9wruMcrGadany3',
-  redirect_uris: ['http://localhost:3000/cb'],
-  response_types: ['code'],
-  // id_token_signed_response_alg (default "RS256")
-  // token_endpoint_auth_method (default "client_secret_basic")
-}); // => Client
-```
+third party APIs.
 
-When you want to have your end-users authorize you need to send them to the issuer's
-`authorization_endpoint`. Consult the web framework of your choice on how to redirect but here's how
+When you want to have your end-users authorize or authenticate you need to send them to the authorization server's `authorization_endpoint`. Consult the web framework of your choice on how to redirect but here's how
 to get the authorization endpoint's URL with parameters already encoded in the query to redirect
 to.
 
-```js
-import { generators } from 'openid-client';
-const code_verifier = generators.codeVerifier();
-// store the code_verifier in your framework's session mechanism, if it is a cookie based solution
-// it should be httpOnly (not readable by javascript) and encrypted.
-
-const code_challenge = generators.codeChallenge(code_verifier);
-
-client.authorizationUrl({
-  scope: 'openid email profile',
-  resource: 'https://my.api.example.com/resource/32178',
+```ts
+/**
+ * Value used in the authorization request as redirect_uri pre-registered at the
+ * Authorization Server.
+ */
+let redirect_uri!: string
+let scope!: string
+/**
+ * The following 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: string = client.randomPKCECodeVerifier()
+let code_challenge: string =
+  await client.calculatePKCECodeChallenge(code_verifier)
+let state!: string
+
+let parameters: Record<string, string> = {
+  redirect_uri,
+  scope,
   code_challenge,
   code_challenge_method: 'S256',
-});
+}
+
+if (
+  config.serverMetadata().code_challenge_methods_supported?.includes('S256') !==
+  true
+) {
+  /**
+   * We cannot be sure the server 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.
+   */
+  state = client.randomState()
+  parameters.state = state
+}
+
+let redirectTo: URL = client.buildAuthorizationUrl(config, parameters)
+
+// now redirect the user to redirectTo.href
+console.log('redirecting to', redirectTo.href)
 ```
 
 When end-users are redirected back to your `redirect_uri` your application consumes the callback and
 passes in the `code_verifier` to include it in the authorization code grant token exchange.
-```js
-const params = client.callbackParams(req);
-const tokenSet = await client.callback('https://client.example.com/callback', params, { code_verifier });
-console.log('received and validated tokens %j', tokenSet);
-console.log('validated ID Token claims %j', tokenSet.claims());
-```
 
-You can then call the `userinfo_endpoint`.
-```js
-const userinfo = await client.userinfo(access_token);
-console.log('userinfo %j', userinfo);
-```
+```ts
+let getCurrentUrl!: (...args: any) => URL
 
-And later refresh the tokenSet if it had a `refresh_token`.
-```js
-const tokenSet = await client.refresh(refresh_token);
-console.log('refreshed and validated tokens %j', tokenSet);
-console.log('refreshed ID Token claims %j', tokenSet.claims());
-```
+let tokens: client.TokenEndpointResponse = await client.authorizationCodeGrant(
+  config,
+  getCurrentUrl(),
+  {
+    pkceCodeVerifier: code_verifier,
+    expectedState: state,
+  },
+)
 
-### Implicit ID Token Flow
+console.log('Token Endpoint Response', tokens)
+```
 
-Implicit `response_type=id_token` flow is perfect for simply authenticating your end-users, assuming
-the only job you want done is authenticating the user and then relying on your own session mechanism
-with no need for accessing any third party APIs with an Access Token from the Authorization Server.
+You can then fetch a protected resource response
 
-Create a Client instance for that issuer's authorization server intended for ID Token implicit flow.
+```ts
+let protectedResourceResponse: Response = await client.fetchProtectedResource(
+  config,
+  tokens.access_token,
+  new URL('https://rs.example.com/api'),
+  'GET',
+)
 
-**See the [documentation][] for full API details.**
-```js
-const client = new googleIssuer.Client({
-  client_id: 'zELcpfANLqY7Oqas',
-  redirect_uris: ['http://localhost:3000/cb'],
-  response_types: ['id_token'],
-  // id_token_signed_response_alg (default "RS256")
-}); // => Client
+console.log(
+  'Protected Resource Response',
+  await protectedResourceResponse.json(),
+)
 ```
 
-When you want to have your end-users authorize you need to send them to the issuer's
-`authorization_endpoint`. Consult the web framework of your choice on how to redirect but here's how
-to get the authorization endpoint's URL with parameters already encoded in the query to redirect
-to.
+### Device Authorization Grant (Device Flow)
 
-```js
-import { generators } from 'openid-client';
-const nonce = generators.nonce();
-// store the nonce in your framework's session mechanism, if it is a cookie based solution
-// it should be httpOnly (not readable by javascript) and encrypted.
-
-client.authorizationUrl({
-  scope: 'openid email profile',
-  response_mode: 'form_post',
-  nonce,
-});
+```ts
+let scope!: string
+let response = await client.initiateDeviceAuthorization(config, { scope })
+
+console.log('User Code:', response.user_code)
+console.log('Verification URI:', response.verification_uri)
+console.log('Verification URI (complete):', response.verification_uri_complete)
 ```
 
-When end-users hit back your `redirect_uri` with a POST (authorization request included `form_post`
-response mode) your application consumes the callback and passes the `nonce` in to include it in the
-ID Token verification steps.
-```js
-// assumes req.body is populated from your web framework's body parser
-const params = client.callbackParams(req);
-const tokenSet = await client.callback('https://client.example.com/callback', params, { nonce });
-console.log('received and validated tokens %j', tokenSet);
-console.log('validated ID Token claims %j', tokenSet.claims());
+You will display the instructions to the end-user and have them directed at `verification_uri` or
+`verification_uri_complete`, afterwards you can start polling for the Device Access Token Response.
+
+```ts
+let tokens: client.TokenEndpointResponse =
+  await client.pollDeviceAuthorizationGrant(config, response)
+
+console.log('Token Endpoint Response', tokens)
 ```
 
-### Device Authorization Grant (Device Flow)
+This will poll in a regular interval and only resolve with tokens once the end-user authenticates.
+
+### Client Credentials Grant
 
-[RFC8628 - OAuth 2.0 Device Authorization Grant (Device Flow)](https://tools.ietf.org/html/rfc8628)
-is started by starting a Device Authorization Request.
+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.
+
+```ts
+let scope!: string
+let resource!: string
 
-```js
-const handle = await client.deviceAuthorization();
-console.log('User Code: ', handle.user_code);
-console.log('Verification URI: ', handle.verification_uri);
-console.log('Verification URI (complete): ', handle.verification_uri_complete);
+let tokens: client.TokenEndpointResponse = await lib.clientCredentialsGrant(
+  config,
+  { scope, resource },
+)
+
+console.log('Token Endpoint Response', tokens)
 ```
 
-The handle represents a Device Authorization Response with the `verification_uri`, `user_code` and
-other defined response properties.
+## [API Reference](docs/README.md)
 
-You will display the instructions to the end-user and have him directed at `verification_uri` or
-`verification_uri_complete`, afterwards you can start polling for the Device Access Token Response.
-```js
-const tokenSet = await handle.poll();
-console.log('received tokens %j', tokenSet);
+`openid-client` is distributed via [npmjs.com](https://www.npmjs.com/package/openid-client) and [github.com](https://github.com/panva/openid-client).
+
+## [Examples](examples/README.md)
+
+**`example`** ESM import
+
+```ts
+import * as client from 'openid-client'
 ```
 
-This will poll in the defined interval and only resolve with a TokenSet once one is received. This
-will handle the defined `authorization_pending` and `slow_down` "soft" errors and continue polling
-but upon any other error it will reject. With tokenSet received you can throw away the handle.
+- Authorization Code Flow (OAuth 2.0) - [source](examples/oauth.ts)
+- Authorization Code Flow (OpenID Connect) - [source](examples/oidc.ts) | [diff](examples/oidc.diff)
+- Extensions
+  - 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)
 
-### Client Credentials Grant Flow
+## Supported Runtimes
 
-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.
+The supported JavaScript runtimes include those that support the utilized Web API globals and standard built-in objects. These are _(but are not limited to)_:
 
-**See the [documentation](./docs/README.md#clientgrantbody-extras) for full API details.**
+- Browsers
+- Bun
+- Cloudflare Workers
+- Deno
+- Electron
+- Node.js[^nodejs]
+- Vercel's Edge Runtime
 
-```js
-const client = new issuer.Client({
-  client_id: 'zELcpfANLqY7Oqas',
-  client_secret: 'TQV5U29k1gHibH5bx1layBo0OSAvAbRT3UYW3EWrSYBB5swxjVfWUa1BS8lqzxG/0v9wruMcrGadany3',
-});
+## Supported Versions
 
-const tokenSet = await client.grant({
-  resource: 'urn:example:third-party-api',
-  grant_type: 'client_credentials'
-});
-```
+| Version                                                  | Security Fixes 🔑 | Other Bug Fixes 🐞 | New Features ⭐ | Runtime and Module type         |
+| -------------------------------------------------------- | ----------------- | ------------------ | --------------- | ------------------------------- |
+| [v6.x](https://github.com/panva/openid-client/tree/v6.x) | ✅                | ✅                 | ✅              | Universal[^universal] ESM[^cjs] |
+| [v5.x](https://github.com/panva/openid-client/tree/v5.x) | ✅                | ❌                 | ❌              | Node.js CJS + ESM               |
+
+[sponsor-auth0]: https://auth0.com/signup?utm_source=external_sites&utm_medium=panva&utm_campaign=devn_signup
+[WebCryptoAPI]: https://w3c.github.io/webcrypto/
+[Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+
+[^nodejs]: Node.js v20.x as baseline is required
+
+[^universal]: Assumes runtime support of [WebCryptoAPI][] and [Fetch API][]
 
-## FAQ
-
-#### Semver?
-
-**Yes.** Everything that's either exported in the TypeScript definitions file or
-[documented][documentation] is subject to
-[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). The rest is to be considered
-private API and is subject to change between any versions.
-
-#### How do I use it outside of Node.js
-
-It is **only built for Node.js**. Other javascript runtimes are not supported.
-I recommend [panva/oauth4webapi][oauth4webapi], or a derivate thereof, if you're 
-looking for a similarly compliant and certified client software that's not dependent 
-on the Node.js runtime builtins.
-
-#### How to make the client send client_id and client_secret in the body?
-
-See [Client Authentication Methods (docs)][documentation-methods].
-
-#### Can I adjust the HTTP timeout?
-
-See [Customizing (docs)][documentation-customizing].
-
-
-[openid-connect]: https://openid.net/connect/
-[feature-core]: https://openid.net/specs/openid-connect-core-1_0.html
-[feature-discovery]: https://openid.net/specs/openid-connect-discovery-1_0.html
-[feature-registration]: https://openid.net/specs/openid-connect-registration-1_0.html
-[feature-revocation]: https://tools.ietf.org/html/rfc7009
-[feature-introspection]: https://tools.ietf.org/html/rfc7662
-[feature-mtls]: https://tools.ietf.org/html/rfc8705
-[feature-device-flow]: https://tools.ietf.org/html/rfc8628
-[feature-rp-logout]: https://openid.net/specs/openid-connect-rpinitiated-1_0.html
-[feature-jarm]: https://openid.net/specs/oauth-v2-jarm.html
-[feature-fapi]: https://openid.net/specs/openid-financial-api-part-2-1_0.html
-[feature-dpop]: https://www.rfc-editor.org/rfc/rfc9449.html
-[feature-par]: https://www.rfc-editor.org/rfc/rfc9126.html
-[feature-jar]: https://www.rfc-editor.org/rfc/rfc9101.html
-[feature-iss]: https://www.rfc-editor.org/rfc/rfc9207.html
-[openid-certified-link]: https://openid.net/certification/
-[passport-url]: http://passportjs.org
-[npm-url]: https://www.npmjs.com/package/openid-client
-[sponsor-auth0]: https://a0.to/try-auth0
-[support-sponsor]: https://github.com/sponsors/panva
-[documentation]: https://github.com/panva/node-openid-client/blob/main/docs/README.md
-[documentation-issuer]: https://github.com/panva/node-openid-client/blob/main/docs/README.md#issuer
-[documentation-client]: https://github.com/panva/node-openid-client/blob/main/docs/README.md#client
-[documentation-customizing]: https://github.com/panva/node-openid-client/blob/main/docs/README.md#customizing
-[documentation-tokenset]: https://github.com/panva/node-openid-client/blob/main/docs/README.md#tokenset
-[documentation-strategy]: https://github.com/panva/node-openid-client/blob/main/docs/README.md#strategy
-[documentation-errors]: https://github.com/panva/node-openid-client/blob/main/docs/README.md#errors
-[documentation-generators]: https://github.com/panva/node-openid-client/blob/main/docs/README.md#generators
-[documentation-methods]: https://github.com/panva/node-openid-client/blob/main/docs/README.md#client-authentication-methods
-[documentation-webfinger]: https://github.com/panva/node-openid-client/blob/main/docs/README.md#issuerwebfingerinput
-[express-openid-connect]: https://www.npmjs.com/package/express-openid-connect
-[oauth4webapi]: https://github.com/panva/oauth4webapi#readme
+[^cjs]: CJS style `require('openid-client')` is possible in Node.js versions where `process.features.require_module` is `true` or with the `--experimental-require-module` Node.js CLI flag.