Skip to main content

Public API

The most public accessible observables, properties and methods are placed in the OidcSecurityService. Below you can find the description of every single one of them.

userData$​

The userData$ observable provides the information about the user after they have logged in. It returns an UserDataResult in the following form:

export interface UserDataResult {
  userData: any;
  allUserData: ConfigUserDataResult[];
}

export interface ConfigUserDataResult {
  configId: string;
  userData: any;
}

In case you are running with one configuration, the ConfigUserDataResult contains the user data in the userData property and the ConfigUserData[] returns the same user data with the configId filled in case you need it.

In case you are running with multiple configs, the userData property of ConfigUserDataResult is set to null and you find your user data per config in the ConfigUserData[].

Example​

this.userData$ = this.oidcSecurityService.userData$;

Single Config​

{
  "userData": {
    "sub": "...",
    "preferred_username": "[email protected]",
    "name": "[email protected]",
    "email": "[email protected]",
    "email_verified": false,
    "given_name": "[email protected]",
    "role": "user",
    "amr": "pwd"
  },
  "allUserData": [
    {
      "configId": "configId",
      "userData": {
        "sub": "...",
        "preferred_username": "[email protected]",
        "name": "[email protected]",
        "email": "[email protected]",
        "email_verified": false,
        "given_name": "[email protected]",
        "role": "user",
        "amr": "pwd"
      }
    }
  ]
}

Multiple Configs​

{
  "userData": null,
  "allUserData": [
    {
      "configId": "configId1",
      "userData": {
        "sub": "...",
        "preferred_username": "[email protected]",
        "name": "[email protected]",
        "email": "[email protected]",
        "email_verified": false,
        "given_name": "[email protected]",
        "role": "user",
        "amr": "pwd"
      }
    },
    {
      "configId": "configId2",
      "userData": {
        "sub": "...",
        "preferred_username": "[email protected]",
        "name": "[email protected]",
        "email": "[email protected]",
        "email_verified": false,
        "given_name": "[email protected]",
        "role": "user",
        "amr": "pwd"
      }
    }
  ]
}

userData​

A signal implementation of userData$. The userData signal returns a Signal<UserDataResult>.

Example​

userData = this.oidcSecurityService.userData;

console.log(this.userData().userData);
console.log(this.userData().userData?.name);
console.log(this.userData().allUserData);

isAuthenticated$​

The isAuthenticated$ property returns an Observable<AuthenticatedResult>. This object is filled depending on with how many configurations you run. The AuthenticatedResult is structured as follows:

export interface AuthenticatedResult {
  isAuthenticated: boolean;
  allConfigsAuthenticated: ConfigAuthenticatedResult[];
}

export interface ConfigAuthenticatedResult {
  configId: string;
  isAuthenticated: boolean;
}

In case you have a single config, the isAuthenticated on the AuthenticatedResult tells you if the user is authenticated or not. The ConfigAuthenticatedResult[] contains the single config result with its configId and again if this config is authenticated or not.

In case you have multiple configs, the isAuthenticated on the AuthenticatedResult tells you if all configs are authenticated (true) or not (false). The ConfigAuthenticatedResult[] contains the single config results with their configId and again if this config is authenticated or not.

Example​

this.isAuthenticated$ = this.oidcSecurityService.isAuthenticated$;

Single Config​

{
  "isAuthenticated": true,
  "allConfigsAuthenticated": [{ "configId": "configId1", "isAuthenticated": true }]
}

Multiple Configs​

{
  "isAuthenticated": false,
  "allConfigsAuthenticated": [
    { "configId": "configId1", "isAuthenticated": true },
    { "configId": "configId2", "isAuthenticated": false }
  ]
}

authenticated​

A signal implementation of isAuthenticated$. The authenticated signal returns a Signal<AuthenticatedResult>.

Example​

authenticated = this.oidcSecurityService.authenticated;

console.log(authenticated().isAuthenticated);
console.log(authenticated().allConfigsAuthenticated);

isLoading$​

The property is disabled and will be removed in future versions. Please use the PublicEventsService with the events EventTypes.CheckingAuth, EventTypes.CheckingAuthFinished, EventTypes.CheckingAuthFinishedWithError instead

The isLoading$ property returns an Observable<boolean>. Emits false when the observable, returned by either of the checkAuth() methods, emits a value, or errors. Initial value: true.

Example​

this.isLoading$ = this.oidcSecurityService.isLoading$;

Example use case​

An auth guard subscribes to isAuthenticated$ before the observable, returned by checkAuth(), emits a value. The isAuthenticated$ emits false, and prompts an authorize, causing an infinite redirect loop. Use the isLoading$ in combination with the isAuthenticated$ to ensure that there is no race condition.

checkSessionChanged$​

The checkSessionChanged$ observable emits values every time the server comes back with a check session and the value changed. If you want to get information about when the CheckSession Event has been received, please take a look at the public events.

this.checkSessionChanged$ = this.oidcSecurityService.checkSessionChanged$;

stsCallback$​

The stsCallback$ observable emits after the library has handled the possible Security Token Service callback. You can perform initial setups and custom workflows inside your application when the Security Token Service redirects you back to your app.

this.stsCallback$ = this.oidcSecurityService.stsCallback$;

preloadAuthWellKnownDocument(configId?: string)​

This method allows you to explicitly load the secure token servers well-known endpoints and persist the settings to the configured storage of this library. This method will perform an http call to load and save the information. If you do not call this method explicitly, the lib will call it when it is needed for the first time automatically.

// single config
this.oidcSecurityService.preloadAuthWellKnownDocument().subscribe((authWellKnown)=> ... );

// multiple configs
this.oidcSecurityService.preloadAuthWellKnownDocument('configId').subscribe((authWellKnown)=> ... );

getConfigurations()​

This method returns all configurations you have configured as an OpenIdConfiguration[]. The config includes all your values merged with the ones the library created.

const allConfigs = this.oidcSecurityService.getConfigurations();

getConfiguration(configId?: string)​

This method returns an observable of one single configuration. If you are running with multiple configs and pass a configId, the configuration or null is returned. If you are running with multiple configs and do not pass the configId, the first one is returned. If you are running with a single config, then this config is returned.

// one config or the first one in case of multiple or null
this.oidcSecurityService.getConfiguration().subscribe((config)=> ... );

// one config or null
this.oidcSecurityService.getConfiguration('configId').subscribe((config)=> ... );

getUserData(configId?: string)​

This method returns an observable of the user data. If you are running with multiple configs and pass a configId, the user data for this config or null is returned. If you are running with multiple configs and do not pass the configId, the user data for the first config is returned. If you are running with a single config, the user data for this config is returned.

// one config or the first one in case of multiple or null
this.oidcSecurityService.getUserData().subscribe((data)=> ... );

// user data for this specific config
this.oidcSecurityService.getUserData('configId').subscribe((data)=> ... );

checkAuth(url?: string, configId?: string)​

Call this once on every app load (typically from your root component's ngOnInit). Without it, the library never bootstraps and the auth state stays uninitialised.

Specifically, checkAuth() does three things:

  1. Processes the callback if the current URL contains an auth response from the identity provider (after the redirect back from sign-in).
  2. Restores an existing session from storage if one is present, so a page refresh keeps the user signed in.
  3. Starts silent token renewal and the periodic token-validity check, if configured.

It returns an Observable<LoginResponse> describing the result:

{
  isAuthenticated: boolean;
  userData: any;
  accessToken: string;
  idToken: string;
  configId: string;
  errorMessage?: string;
}

checkAuth() does not redirect the user anywhere. To start a new sign-in (e.g. on a "Login" button click), call authorize() instead.

this.oidcSecurityService.checkAuth().subscribe(({ isAuthenticated, userData, accessToken, idToken, configId }) => {
  // ...use data
});

You can also pass a configId to target a specific config, and a url to override the URL the library reads the callback from. The custom URL is mainly useful for non-browser shells like Electron or Cordova/Ionic where window.location doesn't reflect the callback.

const url = '...';
const configId = '...';

this.oidcSecurityService.checkAuth(url, configId).subscribe(({ isAuthenticated, userData, accessToken, idToken, configId }) => {
  // ...use data
});

Multiple configs: checkAuth() only bootstraps a single config. If you've registered more than one via provideAuth, use checkAuthMultiple() to bootstrap all of them in one call.

Already signed in elsewhere? If you want the app to detect a server-side session at the identity provider that this app hasn't observed yet (typical SSO case), use checkAuthIncludingServer().

checkAuthMultiple(url?: string)​

The multi-config equivalent of checkAuth(). Use this once on every app load if you've registered more than one provideAuth configuration — it bootstraps all of them in a single call.

It does the same three things as checkAuth() (processes the callback, restores stored sessions, starts silent renewal), applied to every registered config.

It returns an Observable<LoginResponse[]> — one LoginResponse per config, in registration order — so you can see the status of each.

[
  {
    isAuthenticated: boolean;
    userData: any;
    accessToken: string;
    idToken: string;
    configId: string;
    errorMessage?: string;
  }
]
this.oidcSecurityService.checkAuthMultiple().subscribe((responses: LoginResponse[]) => {
  // ...use data
});

You can also pass a configId to check for as well as a URL in case you want to overwrite the one in the address bar from the browser. This is useful for mobile or desktop cases like Electron or Cordova/Ionic.

const url = '...';

this.oidcSecurityService.checkAuthMultiple(url).subscribe((responses: LoginResponse[]) => {
  // ...use data
});

isAuthenticated(configId?: string)​

This method provides information if a config is authenticated or not as an Observable<boolean> return value. If you are running with multiple configs and pass the configId the authentication for this config is checked. If you are running with multiple configs and do not pass the configId the authentication for the first config is checked. If you are running with a single config this configuration is checked if you are authenticated.

this.oidcSecurityService.isAuthenticated().subscribe((isAuthenticated)=> ... );
this.oidcSecurityService.isAuthenticated('configId').subscribe((isAuthenticated)=> ... );

checkAuthIncludingServer(configId?: string)​

The same local bootstrap as checkAuth(), plus an iframe silent renew against the identity provider when the user isn't already locally authenticated.

Use this when your app needs to detect a server-side session that this app hasn't observed yet — typically the SSO scenario where the user is already signed in to the IdP via another app and you want this app to pick that up automatically on first load.

This method only works with iframe silent renew. It does not work with refresh tokens (useRefreshToken: true), because completing the flow there would require user consent.

Returns an Observable<LoginResponse>.

{
  isAuthenticated: boolean;
  userData: any;
  accessToken: string;
  idToken: string;
  configId: string;
  errorMessage?: string;
}

If you are running with multiple configs and pass the configId the authentication for this config is checked. If you are running with multiple configs and do not pass the configId the authentication for the first config is checked. If you are running with a single config this configuration is checked if you are authenticated.

this.oidcSecurityService.checkAuthIncludingServer().subscribe(/*...*/);
this.oidcSecurityService.checkAuthIncludingServer('configId').subscribe(/*...*/);

getAccessToken(configId?: string):​

Returns the access token for your login scenario as an Observable<string>. If you are running with multiple configs and pass the configId the access token for this config is returned. If you are running with multiple configs and do not pass the configId the access token for the first config is returned. If you are running with a single config the access token for this config returned.

this.oidcSecurityService.getAccessToken().subscribe(/*...*/);
this.oidcSecurityService.getAccessToken('configId').subscribe(/*...*/);

getIdToken(configId?: string):​

Returns the id token for your login scenario as an Observable<string>. If you are running with multiple configs and pass the configId the id token for this config is returned. If you are running with multiple configs and do not pass the configId the id token for the first config is returned. If you are running with a single config the id token for this config returned.

this.oidcSecurityService.getIdToken().subscribe(/*...*/);
this.oidcSecurityService.getIdToken('configId').subscribe(/*...*/);

getRefreshToken(configId?: string)​

Returns the refresh token as an Observable<string> for your login scenario if there is one. If you are running with multiple configs and pass a configId, the refresh token for this config is returned. If you are running with multiple configs and do not pass the configId, the refresh token for the first config is returned. If you are running with a single config, the refresh token for this config is returned.

this.oidcSecurityService.getRefreshToken().subscribe(/*...*/);
this.oidcSecurityService.getRefreshToken('configId').subscribe(/*...*/);

getAuthenticationResult(configId?: string)​

Returns the authentication result as an Observable, if present, for the sign-in. The configId parameter is used to define which configuration to use. This is only required when using multiple configurations. If not passed, the first config will be taken. An object with the authentication result is returned.

this.oidcSecurityService.getAuthenticationResult().subscribe(/*...*/);
this.oidcSecurityService.getAuthenticationResult('configId').subscribe(/*...*/);

getPayloadFromIdToken(encode = false, configId?: string)​

Returns the payload from the id_token as an Observable. This can be used to get claims from the token. If you are running with multiple configs and pass a configId, the payload for this config is returned. If you are running with multiple configs and do not pass a configId, the payload for the first config is returned. If you are running with a single config, the payload for this config returned.

The encode param has to be set to true if the payload is base64 encoded.

this.oidcSecurityService.getPayloadFromIdToken().subscribe(/*...*/);
this.oidcSecurityService.getPayloadFromIdToken(true, 'configId').subscribe(/*...*/);

getPayloadFromAccessToken(encode = false, configId?: string)​

Returns the payload from the access token as an Observable. This can be used to get claims from the token. If you are running with multiple configs and pass a configId, the payload for this config is returned. If you are running with multiple configs and do not pass a configId, the payload for the first config is returned. If you are running with a single config, the payload for this config returned.

The encode param has to be set to true if the payload is base64 encoded.

this.oidcSecurityService.getPayloadFromAccessToken().subscribe(/*...*/);
this.oidcSecurityService.getPayloadFromAccessToken(true, 'configId').subscribe(/*...*/);

setState(state: string, configId?: string)​

You can set the state value used for the authorize request, if you have autoCleanStateAfterAuthentication in the configuration set to false. This can be used for custom state logic handling, the state is not automatically reset when set to false. If you are running with multiple configs and pass a configId, the passed config is taken. If you are running with multiple configs and do not pass a configId, the first config is taken. If you are running with a single config, then this config is taken.

this.oidcSecurityService.setState('some-state').subscribe(/*...*/);
this.oidcSecurityService.setState('some-state', 'configId').subscribe(/*...*/);

getState(configId?: string)​

Returns the state value used for the authorize request as an Observable. If you are running with multiple configs and pass a configId, the passed config is taken. If you are running with multiple configs and do not pass a configId, the first config is taken. If you are running with a single config, then this config is taken.

this.oidcSecurityService.getState().subscribe(/*...*/);
this.oidcSecurityService.getState('configId').subscribe(/*...*/);

authorize(configId?: string, authOptions?: AuthOptions)​

Call this when the user initiates a sign-in — typically from a "Login" button click handler, or when an auth guard determines the user needs to authenticate. It redirects the browser to the identity provider's login page.

authorize() does not check or restore session state. That's the job of checkAuth(), which you call once on app load.

This method takes a configId if you want to target a specific config and an authOptions object with customParams or redirectUrl for per-call customization. It also accepts a urlHandler that is called instead of the redirect (useful if you need to construct the navigation yourself).

See also: Custom parameters.

export interface AuthOptions {
  customParams?: { [key: string]: string | number | boolean };
  urlHandler?(url: string): any;
  redirectUrl?: string;
}
this.oidcSecurityService.authorize();
const authOptions = {
  customParams: {
    some: 'params',
  },
  urlHandler: () => {
    /* ... */
  },
};
this.oidcSecurityService.authorize('configId', authOptions);

authorizeWithPopUp(authOptions?: AuthOptions, popupOptions?: PopupOptions, configId?: string)​

This method must be called when you want to redirect to the Security Token Service in a popup and login your user. This method takes a configId as parameter if you want to use a specific config and it also takes authOptions adding customParams or redirectUrl which can change every time you want to login. It also accepts an urlHandler which is getting called instead of the redirect. You can pass additional PopupOptions to define where and how the popup should open.

The method returns an Observable<LoginResponse> containing

{
  isAuthenticated: boolean;
  userData: any;
  accessToken: string;
  idToken: string;
  configId: string;
  errorMessage?: string;
}
export interface PopupOptions {
  width?: number;
  height?: number;
  left?: number;
  top?: number;
}
export interface AuthOptions {
  customParams?: { [key: string]: string | number | boolean };
  urlHandler?(url: string): any;
  redirectUrl?: string;
}

Examples​

this.oidcSecurityService.authorizeWithPopUp().subscribe(({ isAuthenticated, userData, accessToken, idToken, configId }) => {
  // ...use data
});
const authOptions = {
  customParams: {
    some: 'params',
  },
  urlHandler: () => {
    /* ... */
  },
  redirectUrl: '/path-to/custom-popup-login-page.html',
};

this.oidcSecurityService
  .authorizeWithPopUp(authOptions, null, 'configId')
  .subscribe(({ isAuthenticated, userData, accessToken, idToken, configId }) => {
    // ...use data
  });

forceRefreshSession(customParams?: { ... }, configId?: string)​

This method provides the functionality to manually refresh the session at any time you require. If a current process is running this method will do nothing. After the run is finished the method forces to refresh again.

This method takes customParams for this request as well as a configId as parameter if you want to use a specific config. If you are running with multiple configs and pass a configId, the passed config is taken. If you are running with multiple configs and do not pass a configId, the first config is taken. If you are running with a single config, then this config is taken.

See also: Custom parameters

The method returns an Observable<LoginResponse> containing

{
  isAuthenticated: boolean;
  userData: any;
  accessToken: string;
  idToken: string;
  configId: string;
  errorMessage?: string;
}

Examples​

this.oidcSecurityService.forceRefreshSession().subscribe(({ isAuthenticated, userData, accessToken, idToken, configId }) => {
  // ...use data
});
const customParams: {
  some: 'params',
}

this.oidcSecurityService
  .forceRefreshSession(customParams, 'configId')
  .subscribe(({ isAuthenticated, userData, accessToken, idToken, configId }) => {

logoffAndRevokeTokens(configId?: string, authOptions?: AuthOptions)​

With this method the user is being logged out and the refresh token and the access token are revoked on the server. If the refresh token does not exist only the access token is revoked. Then the logout runs normally.

This method takes a configId and authOptions as parameter and returns an observable. If you are running with multiple configs and pass the configId the passed config is taken. If you are running with multiple configs and do not pass the configId the first config is taken. If you are running with a single config this config is taken.

this.oidcSecurityService.logoffAndRevokeTokens().subscribe(/* ... */);
const authOptions = {
  customParams: {
    some: 'params',
  },
  urlHandler: () => {
    /* ... */
  },
};

this.oidcSecurityService.logoffAndRevokeTokens('configId', authOptions).subscribe(/* ... */);

logoff(configId?: string, logoutAuthOptions?: LogoutAuthOptions)​

This method logs out on the server and the local client. If the server state has changed, check session, then only a local logout. The method takes a configId and logoutAuthOptions as parameter. If you are running with multiple configs and pass the configId the passed config is taken. If you are running with multiple configs and do not pass the configId the first config is taken. If you are running with a single config this config is taken.

The method returns an Observable<unknown>.

Examples:

this.oidcSecurityService.logoff().subscribe((result) => console.log(result));
const authOptions = {
  customParams: {
    some: 'params',
  },
  urlHandler: () => {
    /* ... */
  },
};

this.oidcSecurityService.logoff('configId', authOptions).subscribe((result) => console.log(result));

logoffLocal(configId?: string)​

This method is used to reset your local session in the browser, but not sending anything to the server. If you are running with multiple configs and pass a configId, the passed config is taken. If you are running with multiple configs and do not pass a configId, the first config is taken. If you are running with a single config, then this config is taken.

this.oidcSecurityService.logoffLocal();
this.oidcSecurityService.logoffLocal('configId');

logoffLocalMultiple()​

This method is used to reset your local session in the browser for multiple configs, but not sending anything to the server.

this.oidcSecurityService.logoffLocalMultiple();

revokeAccessToken(accessToken?: any, configId?: string)​

This method revokes an access token on the Security Token Service (STS). This is only required in the code flow with refresh tokens. If no token is provided, then the token from the storage is revoked. You can pass any token to revoke. This makes it possible to manage your own tokens.

This method also takes a configId. If you are running with multiple configs and pass the configId the passed config is taken. If you are running with multiple configs and do not pass the configId the first config is taken. If you are running with a single config this config is taken.

this.oidcSecurityService.revokeAccessToken().subscribe(/* ... */);
this.oidcSecurityService.revokeAccessToken('accessToken', 'configId').subscribe(/* ... */);

More info: https://tools.ietf.org/html/rfc7009

revokeRefreshToken(refreshToken?: any, configId?: string)​

This method revokes a refresh token on the Security Token Service (STS). This is only required in the code flow with refresh tokens. If no token is provided, then the token from the storage is revoked. You can pass any token to revoke. This makes it possible to manage your own tokens.

This method also takes a configId. If you are running with multiple configs and pass a configId, the passed config is taken. If you are running with multiple configs and do not pass a configId, the first config is taken. If you are running with a single config, then this config is taken.

this.oidcSecurityService.revokeRefreshToken().subscribe(/* ... */);
this.oidcSecurityService.revokeRefreshToken('refreshToken', 'configId').subscribe(/* ... */);

More info: https://tools.ietf.org/html/rfc7009

getEndSessionUrl(customParams?: { ... }, configId?: string)​

Creates the end session URL which can be used to implement your own custom server logout. You can pass custom params directly into the method. This method also takes a configId. If you are running with multiple configs and pass a configId, the passed config is taken. If you are running with multiple configs and do not pass a configId, the first config is taken. If you are running with a single config, then this config is taken.

this.oidcSecurityService.getEndSessionUrl().subscribe(/* ... */);
const customParams = {
  some: 'params',
};

this.oidcSecurityService.getEndSessionUrl(customParams, 'configId').subscribe(/* ... */);

getAuthorizeUrl(customParams?: { ... }, configId?: string)​

Creates the authorize URL which can be used to get the URL for the authentication the lib uses internally. You can pass custom params directly into the method. This method also takes a configId. If you are running with multiple configs and pass a configId, the passed config is taken. If you are running with multiple configs and do not pass a configId, the first config is taken. If you are running with a single config this config is taken.

const authorizeUrl = this.oidcSecurityService.getAuthorizeUrl();
const customParams = {
  some: 'params',
};

const authorizeUrl = this.oidcSecurityService.getAuthorizeUrl(customParams, 'configId');