oidc-provider
oidc-provider is an OAuth 2.0 Authorization Server with OpenID Connect and many
additional features and standards implemented.
Table of Contents
- Implemented specs & features
- Certification
- Get started
- Documentation & Configuration
- Recipes
- Debugging
- Events
Implemented specs & features
The following specifications are implemented by oidc-provider. Note that not all features are
enabled by default, check the configuration section on how to enable them.
- RFC6749 - OAuth 2.0 & OpenID Connect Core 1.0
- Authorization (Authorization Code Flow, Implicit Flow, Hybrid Flow)
- UserInfo Endpoint and ID Tokens including Signing and Encryption
- Passing a Request Object by Value or Reference including Signing and Encryption
- Public and Pairwise Subject Identifier Types
- Offline Access / Refresh Token Grant
- Client Credentials Grant
- Client Authentication incl. client_secret_jwt and private_key_jwt methods
- OpenID Connect Discovery 1.0
- OpenID Connect Dynamic Client Registration 1.0 and RFC7591 - OAuth 2.0 Dynamic Client Registration Protocol
- OAuth 2.0 Form Post Response Mode
- RFC7636 - Proof Key for Code Exchange (PKCE)
- RFC7009 - OAuth 2.0 Token Revocation
- RFC7592 - OAuth 2.0 Dynamic Client Registration Management Protocol
- RFC7662 - OAuth 2.0 Token Introspection
- RFC8252 - OAuth 2.0 for Native Apps BCP (AppAuth)
- RFC8628 - OAuth 2.0 Device Authorization Grant (Device Flow)
- RFC8705 - OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens (MTLS)
The following draft specifications are implemented by oidc-provider.
- JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens - draft 05
- JWT Response for OAuth Token Introspection - draft 09
- JWT Secured Authorization Response Mode for OAuth 2.0 (JARM) - draft 02
- OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP) - draft 01
- OAuth 2.0 JWT Secured Authorization Request (JAR)
- OAuth 2.0 Pushed Authorization Requests - draft 03
- OAuth 2.0 Resource Indicators - draft 08
- OAuth 2.0 Web Message Response Mode - individual draft 00
- OpenID Connect RP-Initiated Logout 1.0 - draft 01
- OpenID Connect Back-Channel Logout 1.0 - draft 06
- OpenID Connect Front-Channel Logout 1.0 - draft 04
- OpenID Connect Session Management 1.0 - draft 30
Updates to draft specification versions 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. Alternatively
acknowledge the version and be notified of breaking changes as part of
your CI.
Certification
Filip Skokan has certified that oidc-provider
conforms to the following profiles of the OpenID Connect™ protocol
- OP Basic, Implicit, Hybrid, Config, Dynamic, Form Post, and 3rd Party-Init
- OP Front-Channel Logout, Back-Channel Logout, RP-Initiated Logout, and Session Management
- OP FAPI R/W MTLS and Private Key
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/developers.
Support
If you or your business use oidc-provider, please consider becoming a sponsor so I can continue maintaining it and adding new features carefree.
Get started
You may check the example folder or follow a step by step example to see
which of those fits your desired application setup.
A feature-rich example configuration of oidc-provider is available for you to experiment with
here. Dynamic Client Registration is open, you can literally register any client
you want there. An example client using this provider is available here
(uses openid-client).
Also be sure to check the available configuration docs section.
Documentation & Configuration
oidc-provider can be mounted to existing connect, express, fastify, hapi, or koa applications, see
how. The provider allows to be extended and configured in
various ways to fit a variety of uses. See the documentation.
const { Provider } = require('oidc-provider');
const configuration = {
// ... see available options /docs
clients: [{
client_id: 'foo',
client_secret: 'bar',
redirect_uris: ['http://lvh.me:8080/cb'],
// + other client properties
}],
};
const oidc = new Provider('http://localhost:3000', configuration);
// express/nodejs style application callback (req, res, next) for use with express apps, see /examples/express.js
oidc.callback
// koa application for use with koa apps, see /examples/koa.js
oidc.app
// or just expose a server standalone, see /examples/standalone.js
const server = oidc.listen(3000, () => {
console.log('oidc-provider listening on port 3000, check http://localhost:3000/.well-known/openid-configuration');
});
Recipes
Collection of useful configurations use cases are available over at recipes.
Debugging
oidc-provider uses the debug module internally to log information about various states
of authentication requests, errors and grants. To see all these set the DEBUG environment variable
to oidc-provider:* when launching your app.
There is no filter on what is included in the debug output, since it may end-user Personally
identifiable information or client credentials its use is only advised for debugging, not regular
logging. Use emitted events to cherry pick the one's of interest to your flows and form your own
logs aware of what should and should not be a part of a logged message.
Events
Your oidc-provider instance is an event emitter, using event handlers you can hook into the various
actions and i.e. emit metrics or that react to specific triggers. In some scenarios you can even
change the defined behavior.
See the list of available emitted event names and their description.