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 which you use to use the library:
The remainder of this document will primarily focus on the UserManager.
To understand how to use this library see here:
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 to anything that supports a info, warn, and error methods that accept a params array by calling Log.setLogger(). 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:
import { Log } from 'oidc-client-ts';
Log.setLogger(console);
Also, logging has levels so you can control the verbosity by calling
Log.setLevel() with one of Log.NONE, Log.ERROR,
Log.WARN, or Log.INFO. The default is 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.
If you would like to encode a custom state string in the sign-in request url, you can do so with the url_state parameter. You may want to do this in order to pass user state to the authentication server and/or a proxy and return that state as part of the response.
const mgr = new UserManager();
mgr.signinRedirect({ url_state: 'custom url state' })
The url_state will be appended to the opaque, unique value created by the library when sending the request. It should survive the round trip to your authentication server and will be part of the User object as url_state.
If your app is using hash-based routing, be aware that many OIDC providers append the query string after the hash instead of inserting it before:
Correct: https://your.org/?code=ab&state=cd#/oidc-callback
Wrong: https://your.org/#/oidc-callback?code=ab&state=cd
Check out this issue for details. (There are also workarounds, as long as your provider doesn't fix the issue)