openid-client 4.9.1 → 5.1.0

package/README.md

@@ -14,8 +14,6 @@ openid-client.
     - Implicit Flow
     - Hybrid Flow
   - UserInfo Request
-  - Fetching Distributed Claims
-  - Unpacking Aggregated Claims
   - Offline Access / Refresh Token Grant
   - Client Credentials Grant
   - Client Authentication
@@ -25,7 +23,7 @@ openid-client.
     - client_secret_jwt
     - private_key_jwt
   - Consuming Self-Issued OpenID Provider ID Token response
-- [RFC8414 - OAuth 2.0 Authorization Server Metadata][feature-oauth-discovery] and [OpenID Connect Discovery 1.0][feature-discovery]
+- [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]
@@ -44,13 +42,13 @@ openid-client.
     - 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]
-- [OpenID Connect Session Management 1.0 - draft 28][feature-rp-logout]
-  - RP-Initiated Logout
-- [Financial-grade API - Part 2: Read and Write API Security Profile (FAPI) - ID2][feature-fapi]
+- [OpenID Connect RP-Initiated Logout 1.0 - draft 01][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) - ID1][feature-jarm]
-- [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP) - draft 03][feature-dpop]
+- [OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP) - draft 04][feature-dpop]
+- [OAuth 2.0 Authorization Server Issuer Identification - draft-04][feature-iss]
 
-Updates to draft specifications (DPoP, JARM, and FAPI) are released as MINOR library versions,
+Updates to draft specifications (DPoP, JARM, etc) 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. 
 
@@ -59,13 +57,12 @@ package.json since breaking changes may be introduced as part of these version u
 Filip Skokan has [certified][openid-certified-link] that [openid-client][npm-url]
 conforms to the following profiles of the OpenID Connect™ protocol
 
-- RP Basic, Implicit, Hybrid, Config, Dynamic, and Form Post
-- RP FAPI R/W MTLS and Private Key
-
+- Basic, Implicit, Hybrid, Config, Dynamic, and Form Post RP
+- FAPI 1.0 Advanced RP
 
 ## Sponsor
 
-[<img width="65" height="65" align="left" src="https://avatars.githubusercontent.com/u/2824157?s=75&v=4" 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 at [auth0.com/developers][sponsor-auth0].<br><br>
+[<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>
 
 ## Support
 
@@ -76,8 +73,8 @@ If you or your business use openid-client, please consider becoming a [sponsor][
 
 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 neither express
-or koa middlewares. Those can however be built using the exposed API.
+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][]
 
 - [openid-client API Documentation][documentation]
   - [Issuer][documentation-issuer]
@@ -90,7 +87,9 @@ or koa middlewares. Those can however be built using the exposed API.
 
 ## Install
 
-Node.js version **>=12.0.0** is recommended, but **^10.19.0** lts/dubnium is also supported.
+Node.js LTS releases Codename Erbium (starting with ^12.19.0) and newer LTS releases are supported. 
+This means  ^12.19.0 (Erbium), ^14.15.0 (Fermium), and ^16.13.0 (Gallium). Future LTS releases will
+be added to this list as they're released.
 
 ```console
 npm install openid-client
@@ -100,11 +99,10 @@ npm install openid-client
 
 Discover an Issuer configuration using its published .well-known endpoints
 ```js
-const { Issuer } = require('openid-client');
-Issuer.discover('https://accounts.google.com') // => Promise
-  .then(function (googleIssuer) {
-    console.log('Discovered issuer %s %O', googleIssuer.issuer, googleIssuer.metadata);
-  });
+import { Issuer } from 'openid-client';
+
+const googleIssuer = await Issuer.discover('https://accounts.google.com');
+console.log('Discovered issuer %s %O', googleIssuer.issuer, googleIssuer.metadata);
 ```
 
 ### Authorization Code Flow
@@ -116,7 +114,7 @@ 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][documentation] for full API details.**
+**See the [documentation][] for full API details.**
 
 ```js
 const client = new googleIssuer.Client({
@@ -135,7 +133,7 @@ to get the authorization endpoint's URL with parameters already encoded in the q
 to.
 
 ```js
-const { generators } = require('openid-client');
+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.
@@ -154,28 +152,22 @@ When end-users are redirected back to your `redirect_uri` your application consu
 passes in the `code_verifier` to include it in the authorization code grant token exchange.
 ```js
 const params = client.callbackParams(req);
-client.callback('https://client.example.com/callback', params, { code_verifier }) // => Promise
-  .then(function (tokenSet) {
-    console.log('received and validated tokens %j', tokenSet);
-    console.log('validated ID Token claims %j', tokenSet.claims());
-  });
+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
-client.userinfo(access_token) // => Promise
-  .then(function (userinfo) {
-    console.log('userinfo %j', userinfo);
-  });
+const userinfo = await client.userinfo(access_token);
+console.log('userinfo %j', userinfo);
 ```
 
 And later refresh the tokenSet if it had a `refresh_token`.
 ```js
-client.refresh(refresh_token) // => Promise
-  .then(function (tokenSet) {
-    console.log('refreshed and validated tokens %j', tokenSet);
-    console.log('refreshed ID Token claims %j', tokenSet.claims());
-  });
+const tokenSet = await client.refresh(refresh_token);
+console.log('refreshed and validated tokens %j', tokenSet);
+console.log('refreshed ID Token claims %j', tokenSet.claims());
 ```
 
 ### Implicit ID Token Flow
@@ -186,7 +178,7 @@ with no need for accessing any third party APIs with an Access Token from the Au
 
 Create a Client instance for that issuer's authorization server intended for ID Token implicit flow.
 
-**See the [documentation][documentation] for full API details.**
+**See the [documentation][] for full API details.**
 ```js
 const client = new googleIssuer.Client({
   client_id: 'zELcpfANLqY7Oqas',
@@ -202,7 +194,7 @@ to get the authorization endpoint's URL with parameters already encoded in the q
 to.
 
 ```js
-const { generators } = require('openid-client');
+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.
@@ -220,11 +212,9 @@ ID Token verification steps.
 ```js
 // assumes req.body is populated from your web framework's body parser
 const params = client.callbackParams(req);
-client.callback('https://client.example.com/callback', params, { nonce }) // => Promise
-  .then(function (tokenSet) {
-    console.log('received and validated tokens %j', tokenSet);
-    console.log('validated ID Token claims %j', tokenSet.claims());
-  });
+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());
 ```
 
 ### Device Authorization Grant (Device Flow)
@@ -253,11 +243,6 @@ This will poll in the defined interval and only resolve with a TokenSet once one
 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.
 
-## Electron Support
-
-Electron >=v6.0.0 runtime is supported to the extent of the crypto engine BoringSSL feature parity
-with standard Node.js OpenSSL.
-
 ## FAQ
 
 #### Semver?
@@ -269,8 +254,8 @@ private API and is subject to change between any versions.
 
 #### How do I use it outside of Node.js
 
-It is **only built for ^10.19.0 || >=12.0.0 Node.js** environment - including openid-client in
-browser-environment targeted projects is not supported and may result in unexpected results.
+It is **only built for Node.js** environments - including openid-client in
+browser-environment targeted projects is not supported.
 
 #### How to make the client send client_id and client_secret in the body?
 
@@ -278,32 +263,28 @@ See [Client Authentication Methods (docs)][documentation-methods].
 
 #### Can I adjust the HTTP timeout?
 
-See [Customizing (docs)](https://github.com/panva/node-openid-client/blob/master/docs/README.md#customizing).
-
-#### How can I debug the requests and responses?
-
-See [Customizing (docs)](https://github.com/panva/node-openid-client/blob/master/docs/README.md#customizing).
+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-oauth-discovery]: https://tools.ietf.org/html/rfc8414
 [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-session-1_0.html#RPLogout
+[feature-rp-logout]: https://openid.net/specs/openid-connect-rpinitiated-1_0-01.html
 [feature-jarm]: https://openid.net/specs/openid-financial-api-jarm-ID1.html
-[feature-fapi]: https://openid.net/specs/openid-financial-api-part-2-ID2.html
-[feature-dpop]: https://tools.ietf.org/html/draft-ietf-oauth-dpop-03
+[feature-fapi]: https://openid.net/specs/openid-financial-api-part-2-1_0.html
+[feature-dpop]: https://tools.ietf.org/html/draft-ietf-oauth-dpop-04
 [feature-par]: https://www.rfc-editor.org/rfc/rfc9126.html
 [feature-jar]: https://www.rfc-editor.org/rfc/rfc9101.html
+[feature-iss]: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-iss-auth-resp-04
 [openid-certified-link]: https://openid.net/certification/
 [passport-url]: http://passportjs.org
 [npm-url]: https://www.npmjs.com/package/openid-client
-[sponsor-auth0]: https://auth0.com/developers?utm_source=GHsponsor&utm_medium=GHsponsor&utm_campaign=openid-client&utm_content=auth
+[sponsor-auth0]: https://a0.to/try-auth0
 [support-sponsor]: https://github.com/sponsors/panva
 [documentation]: https://github.com/panva/node-openid-client/blob/master/docs/README.md
 [documentation-issuer]: https://github.com/panva/node-openid-client/blob/master/docs/README.md#issuer
@@ -315,3 +296,4 @@ See [Customizing (docs)](https://github.com/panva/node-openid-client/blob/master
 [documentation-generators]: https://github.com/panva/node-openid-client/blob/master/docs/README.md#generators
 [documentation-methods]: https://github.com/panva/node-openid-client/blob/master/docs/README.md#client-authentication-methods
 [documentation-webfinger]: https://github.com/panva/node-openid-client/blob/master/docs/README.md#issuerwebfingerinput
+[express-openid-connect]: https://www.npmjs.com/package/express-openid-connect