Skip to main content

Introduction

This library provides a set of services and utilities to handle OAuth2 authentication in your application.

Let's get started! 🎉​

Let's start by configuring the OAuth2 authentication in your application.

First of all, you need the @celerofinancas/ui-oauth library installed in your project. For more information, follow the installation guide.

OAuth2 Configuration​

To configure the OAuth2 authentication, you need to provide the following information in your app module:

app.module.ts
import { UiOAuthModule } from '@celerofinancas/ui-oauth';
import { config, environment } from './configs';

@NgModule({
  imports: [
    UiOAuthModule.forRoot(environment, config),
    // ...
  ]
})
export class AppModule {}

Environment​

The environment should be an object containing at least the following properties:

  • apiUrl: The URL of the API server.
  • colorPalette: The white label color palette. (e.g., celero)

Environment Type​

If you not provide a custom type, the Environment type is expected.

Them, you can import the Environment object from the @celerofinancas/ui-oauth library.

environments/environment.ts
import { Environment } from '@celerofinancas/ui-oauth';

export const environment: Environment = {
  apiUrl: 'https://finance-develop-celero-api-client.celero.mobi',
  colorPalette: 'celero',
};

Also, you can create your own type if needed.

environments/environment.ts
export interface CustomEnvironment {
  apiUrl: string;
  colorPalette: string;
  production: boolean;
}

export const environment: CustomEnvironment = {
  apiUrl: 'https://finance-develop-celero-api-client.celero.mobi',
  colorPalette: 'celero',
  production: false,
};

Config​

The config should be a OAuthConfiguration object containing at least the following properties:

  • issuer: The URL of the OAuth2 server.
  • clientId: The client ID of the application.
  • redirectUri: The URL to redirect after the authentication process.
  • scope: The scope of the authentication process. (e.g., openid profile email)

You can import the OAuthConfiguration object from the @celerofinancas/ui-oauth library.

configs.ts
import { OAuthConfiguration } from '@celerofinancas/ui-oauth';

export const config: OAuthConfiguration = {
  issuer: 'https://auth.celero.mobi/realms/sb',
  clientId: 'celero',
  redirectUri: 'http://localhost:4200',
  scope: 'openid profile email',
};

Config Type​

OAuthConfiguration follows the following structure:

issuer​

The OAuth issuer.

redirectUri​
tip

For popup mode, follow the popup mode guide.

The URI to redirect to after authentication.

clientId​

The OAuth client ID.

Can be client or staff.

scope​

The scope of the requested permissions.

clientSecret​
DEVELOPMENT ONLY!

Client secret should be kept confidential. Do not expose it in the client-side code.

It a optional parameter, the OAuth client secret.

postLogoutUrl​

The URL to redirect to after logout.

Set this property if you want to redirect to a custom URL after logout.

tokenEndpoint, endSessionEndpoint, authorizationEndpoint, refreshTokenEndpoint​
info

Tipically used for BFF (Backend for Frontend) scenarios. To avoid exposing the client secret in the client-side code.

By default, will use the issuer ./well-known/openid-configuration endpoint.

Whether you need to use a custom one, you can set one of this property.

enablePKCE​

Whether you want to enables PKCE (Proof Key for Code Exchange) for the authentication process.

By default, it is true.

popupConfiguration​

A object containing the width and height of the popup.

The default values are width: 440 and height: 660.

headerWhiteList​

An array of strings containing URLs that bypass the Bearer token header.

If you need to bypass the Bearer token header for some URLs, you can set this property.

refreshWhiteList​

An array of strings containing URLs that bypass the refresh token.

If you need to bypass the refresh token for some URLs, you can set this property.

An API overview of the OAuthConfiguration object is as follows:

export interface OAuthConfiguration {
  issuer: string;
  redirectUri: string;
  clientId: string;
  scope: string;
  clientSecret?: string;
  postLogoutUrl?: string;
  tokenEndpoint?: string;
  endSessionEndpoint?: string;
  authorizationEndpoint?: string;
  refreshTokenEndpoint?: string;
  enablePKCE?: boolean;
  popupConfiguration?: {
    width: number;
    height: number;
  };
  headerWhiteList?: string[];
  refreshWhiteList?: string[];
}

Expected Configuration​

The expected configuration is as follows:

configs.ts
import { OAuthConfiguration } from '@celerofinancas/ui-oauth';

export const config: OAuthConfiguration = {
  issuer: 'https://auth.celero.mobi/realms/sb',
  redirectUri: `${window.location.origin}`,
  clientId: 'client',
  scope: 'openid profile email',
  tokenEndpoint: `${environment.apiUrl}/v2/auth/access_token`,
  refreshTokenEndpoint: `${environment.apiUrl}/v2/auth/refresh_token`,
};

Done! 🎉​

After configuring the OAuth2 authentication, you can start using the services and utilities provided by the @celerofinancas/ui-oauth library.