oidc-client-ts is a TypeScript library intended to be used by web applications and run in browsers. It provides protocol support for OIDC and OAuth2, as well as management functions for user sessions and access tokens management.

If you are unfamiliar with OpenID Connect, then you should learn the protocol first. This library is designed as a spec-compliant protocol library.

There are two main classes that you might want to use depend on the level at with you use to use the library:

• UserManager provides a higher level API for signing a user in, signing out, managing the user's claims
• OidcClient provides the raw OIDC/OAuth2 protocol support

The remainder of this document will primarily focus on the UserManager.

UserManager

Configuration

The UserManager constructor requires a settings object as a parameter:

• UserManagerSettings which extends
• OidcClientSettings

Required settings

• authority: The URL of the OIDC/OAuth2 provider.
• client_id: Your client application's identifier as registered with the OIDC/OAuth2 provider.
• redirect_uri: The redirect URI of your client application to receive a response from the OIDC/OAuth2 provider.

Provider settings if CORS not supported on OIDC/OAuth2 provider metadata endpoint

The authority URL setting is used to make HTTP requests to discover more information about the OIDC/OAuth2 provider and populate a metadata property on the settings. If the server does not allow CORS on the metadata endpoint, then these additional settings can be manually configured. These values can be found on the metadata endpoint of the provider:

• metadata property which contains:
  • issuer
  • authorization_endpoint
  • userinfo_endpoint
  • end_session_endpoint
• metadataSeed can be used to seed or add additional values to the results of the discovery request.

Events

The UserManager will raise various events about the user's session:

• UserManagerEvents which extends
• AccessTokenEvents

To register for the events, there is an events property on the UserManager with addXxx and removeXxx APIs to add/remove callbacks for the events. An example:

const mgr = new UserManager();
mgr.events.addAccessTokenExpiring(function() {
    console.log("token expiring...");
});
Copy

User

The User type is returned from the UserManager's getUser API.

Logging

The oidc-client-ts library supports logging. You can set a logger by assigning Oidc.Log.logger to anything that supports a info, warn, and error methods that accept a params array. By default, no logger is configured.

The console object in the browser supports these, so a common way to easily enable logging in the browser is to simply add this code:

Oidc.Log.setLogger(console);
Copy

Also, logging has levels so you can control the verbosity by calling Oidc.Log.setLevel() with one of Oidc.Log.NONE, Oidc.Log.ERROR, Oidc.Log.WARN, or Oidc.Log.INFO. The default is Oidc.Log.INFO.

Provider specific settings

Additional provider specific settings may be needed for a flawless operation:

Amazon Cognito

const mgr = new UserManager({
    // ...
    // no revoke of "access token" (https://github.com/authts/oidc-client-ts/issues/262)
    revokeTokenTypes: ["refresh_token"],
    // no silent renew via "prompt=none" (https://github.com/authts/oidc-client-ts/issues/366)
    automaticSilentRenew: false,
});
Copy

Custom state in user object

In case you would like to add additional data into the User object, you can do so during the initial sign-in request.

const mgr = new UserManager();
const customState = { foo: "bar" };
mgr.signinRedirect({ state: customState });
Copy

After successful sign-in the custom state is part of the User object as state. In case of failure it is inside ErrorResponse.

This custom state should not be confused with the URL state parameter. The latter is internally used to match against the authentication state object to finish the authentication process.

Projects using oidc-client

• React context provider
• Angular sample
• Chrome service worker

Training

• Securing Angular Apps with OpenID and OAuth2