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:
The remainder of this document will primarily focus on the UserManager.
The UserManager constructor requires a settings object as a parameter:
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:
The UserManager will raise various events about the user's session:
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...");
});
The User type is returned from the UserManager's getUser API.
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);
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.
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,
});
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 });
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.
Generated using TypeDoc