openid-client-kingfisher
Disclamer: this work is a fork of the excellent package openid-client, with some changes made to ensure compatibility with NHS Identity.
openid-client-kingfisher is a server side OpenID Relying Party (RP, Client) implementation for Node.js, supports passport.
Notice: openid-client ^2.0.x drops support for Node.js versions less than lts/boron(6.9.0) due to Node.js lts/argon end of life on 2018-04-30. See the CHANGELOG for a complete list of deprecations and changes.
Table of Contents
Implemented specs & features
The following client/RP features from OpenID Connect/OAuth2.0 specifications are implemented by openid-client.
- OpenID Connect Core 1.0
- Authorization Callback
- Authorization Code Flow
- Implicit Flow
- Hybrid Flow
- UserInfo Request
- Fetching Distributed Claims
- Unpacking Aggregated Claims
- Offline Access / Refresh Token Grant
- Client Credentials Grant
- Password Grant
- Client Authentication
- none
- client_secret_basic
- client_secret_post
- client_secret_jwt
- private_key_jwt
- Authorization Callback
- RFC8414 - OAuth 2.0 Authorization Server Metadata and OpenID Connect Discovery 1.0
- Discovery of OpenID Provider (Issuer) Metadata
- Discovery of OpenID Provider (Issuer) Metadata via user provided inputs (see WebFinger)
- OpenID Connect Dynamic Client Registration 1.0
- Dynamic Client Registration request
- Client initialization via registration client uri
- RFC7009 - OAuth 2.0 Token revocation
- Client Authenticated request to token revocation
- RFC7662 - OAuth 2.0 Token introspection
- Client Authenticated request to token introspection
Updates to features defined in draft or experimental specifications are released as MINOR library versions, if you utilize these consider using the tilde ~ operator in your package.json since breaking changes may be introduced as part of these specification updates.
Certification
Filip Skokan has certified that openid-client
conforms to the RP Basic, RP Implicit, RP Hybrid, RP Config, RP Dynamic and RP Form Post profiles
of the OpenID Connect™ protocol.
Sponsor
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/overview.
Get started
On the off-chance you want to manage multiple clients for multiple issuers you need to first get an Issuer instance.
via Discovery (recommended)
const Issuer = ;Issuer // => Promise ;
manually
const Issuer = ;const googleIssuer = issuer: 'https://accounts.google.com' authorization_endpoint: 'https://accounts.google.com/o/oauth2/v2/auth' token_endpoint: 'https://www.googleapis.com/oauth2/v4/token' userinfo_endpoint: 'https://www.googleapis.com/oauth2/v3/userinfo' jwks_uri: 'https://www.googleapis.com/oauth2/v3/certs'; // => Issuerconsole;
Now you can create your Client.
manually (recommended)
You should provide at least the following metadata: client_id
, client_secret
, id_token_signed_response_alg
(defaults to RS256
) and token_endpoint_auth_method
(defaults to client_secret_basic
) for a basic client definition, but you may provide any IANA registered client metadata.
const client = client_id: 'zELcpfANLqY7Oqas' client_secret: 'TQV5U29k1gHibH5bx1layBo0OSAvAbRT3UYW3EWrSYBB5swxjVfWUa1BS8lqzxG/0v9wruMcrGadany3' keystore; // => Client
keystore
is an optional argument for instantiating a client with configured asymmetrical
ID Token or UserInfo response encryption.
via registration client uri
Should your oidc provider have provided you with a registration client uri and registration access token you can also have the Client discovered.
googleIssuerClient // => Promise ;
keystore
is an optional argument for instantiating a client through registration client uri
with configured asymmetrical ID Token or UserInfo response encryption.
Usage
Getting authorization url
client; // => String (URL)
You can also get HTML body of a self-submitting form to utilize POST to the authorization url with
#authorizationPost
method, same signature as #authorizationUrl
.
client; // => String (Valid HTML body)
Processing callback
const state response_type = sessionauthorizationRequestState;client // => Promise ;
Aside from state
and response_type
, checks for nonce
(implicit and hybrid responses) and
max_age
are implemented. id_token
signature and claims validation does not need to be requested,
it is done automatically.
OP Errors - OpenIdConnectError
When the OpenID Provider returns an OIDC formatted error from either authorization callbacks or
any of the JSON responses the library will reject a given Promise with OpenIdConnectError
instance.
The message of this error is "${error} (${error_description})"
. However the OpenIdConnectError object
also has the following properties:
- error
- error_description
- error_uri
- state
- scope
Values are undefined
if these were not provided in the response. Additionally, for API call
responses a response
property is available with the response object from the used http client.
Handling multiple response modes
When handling multiple response modes with one single pass you can use #callbackParams
to get the params object from the koa/express/node request object or a url string.
(http.IncomingMessage). If form_post is your response_type you need to include a body parser prior.
client; // => { code: 'code' };client; // => { code: 'code' }; // example koa v2.x w/ koa-bodyapp;app; // example express w/ bodyParserapp;app;
Refreshing a token
client // => Promise ;
Tip: accepts TokenSet as well as direct refresh token values;
Revoke a token
client // => Promise ;
Introspect a token
client // => Promise ;
Fetching userinfo
client // => Promise ;
Tip: accepts TokenSet as well as direct access token values;
via POST
client; // => Promise
with extra query/body payload
client; // => Promise
auth via query
client; // => Promise
auth via body
client; // => Promise
userinfo also handles (as long as you have the proper metadata configured) responses that are:
- signed
- signed and encrypted (nested JWT)
- just encrypted
Getting RP-Initiated Logout url
Note: Only usable with issuer's supporting OpenID Connect Session Management 1.0
client; // => String (URL)
Fetching Distributed Claims
let claims = sub: 'userID' _claim_names: credit_history: 'src1' email: 'src2' _claim_sources: src1: endpoint: 'https://src1.example.com/claims' access_token: 'foobar' src2: endpoint: 'https://src2.example.com/claims' ; client // => Promise ; // when rejected the error will have a property 'src' with the source name it relates to
Unpacking Aggregated Claims
let claims = sub: 'userID' _claim_names: credit_history: 'src1' email: 'src2' _claim_sources: src1: JWT: 'probably.a.jwt' src2: JWT: 'probably.another.jwt' ; client // => Promise, autodiscovers JWT issuers, verifies signatures ; // when rejected the error will have a property 'src' with the source name it relates to
Custom token endpoint grants
Use when the token endpoint also supports additional grant types.
client; // => Promise client; // => Promise
Registering new client (via Dynamic Registration)
const opts = keystore initialAccessToken ; // both optionalissuerClient // => opts optional, Promise ;
Generating a signed/encrypted Request Object
client ;
This will use the client metadata request_object_signing_alg
, request_object_encryption_alg
and
request_object_encryption_enc
, but you can provide the signing and/or encryption algs explicitly
client;
WebFinger discovery
Issuer // => Promise ;
Accepts, normalizes, discovers and validates the discovery of User Input using E-Mail, URL, acct, Hostname and Port syntaxes as described in Discovery 1.0.
Uses already discovered (cached) issuers where applicable.
TokenSet
authorizationCallback
and refresh
methods on a Client return TokenSet, when assigned an
expires_in
value a TokenSet calculates and assigns an expires_at
with the corresponding unix
time. It also comes with few helpers.
client;
Usage with passport
Once you have a Client instance, just pass it to the Strategy constructor. Issuer is best discovered, Client passed properties manually or via an uri (see get-started).
Verify function is invoked with a TokenSet, userinfo only when requested, last argument is always the done function which you invoke once you found your user.
const Strategy = ;const params = // ... any authorization request parameters go here // client_id defaults to client.client_id // redirect_uri defaults to client.redirect_uris[0] // response type defaults to client.response_types[0], then 'code' // scope defaults to 'openid'const passReqToCallback = false; // optional, defaults to false, when true req is passed as a first // argument to verify fn const usePKCE = true; // optional, defaults to false, when true the code_challenge_method will be // resolved from the issuer configuration, instead of true you may provide // any of the supported values directly, i.e. "S256" (recommended) or "plain" passport; // start authentication request// options [optional], extra authentication parametersapp; // authentication callbackapp;
Configuration
Client Authentication explained
Configure token_endpoint_auth_method
with one of the following. Defined in Core 1.0:
none
- only client_id is sent in the request bodyclient_secret_basic
(default) - client_id and client_secret is sent using theAuthorization
header as described in RFC6749client_secret_post
- client_id and client_secret is sent in the request body as described in RFC6749client_secret_jwt
- usingclient_secret
as a shared symmetrical secret aclient_assertion
is sent in the request bodyprivate_key_jwt
- using the asymmetric keys provided viakeystore
aclient_assertion
is sent in the request body
The configuration may differ between token, introspection and revocation endpoints. The metadata would be:
token_endpoint_auth_method
introspection_endpoint_auth_method
revocation_endpoint_auth_method
The other metadata names follow the same prefix convention.
Note: *_jwt
methods resolve their algorithm either via the client's configured alg
(token_endpoint_auth_signing_alg
) or any of the issuer's supported algs
(token_endpoint_auth_signing_alg_values_supported
)
Allow for system clock skew
It is possible the RP or OP environment has a system clock skew, to set a clock tolerance (in seconds)
clientCLOCK_TOLERANCE = 5; // to allow a 5 second skew
Changing HTTP request defaults
Setting defaultHttpOptions
on Issuer
always merges your passed options with the default.
openid-client uses got for http requests with the following default request options
const DEFAULT_HTTP_OPTIONS = followRedirect: false headers: 'User-Agent': `/ ()` retries: 0 timeout: 1500;
You can add your own headers, change the user-agent used or change the timeout setting
IssuerdefaultHttpOptions = timeout: 2500 headers: 'X-Your-Header': '<whatever>' ;
Confirm your httpOptions by
console;
Proxy settings
Because of the lightweight nature of got library the client will not use
environment-defined http(s) proxies. In order to have them used you'll need to either provide your own http request
implementation using the provided httpClient
setter or use the bundled request
one.
Custom implementation:
/* * url {String} * options {Object} * options.headers {Object} * options.body {String|Object} * options.form {Boolean} * options.query {Object} * options.timeout {Number} * options.retries {Number} * options.followRedirect {Boolean} */ IssuerhttpClient = {} // return Promise {} // return Promise HTTPError // used error constructor;
Bundled (and maintained + tested) request implementation after you've added request to your package.json bundle:
npm install request@^2.0.0 --save
Issuer;