Pega Auth

The Pega Auth repo is used to create the @pega/auth npm package.

This package contains 3 distinct libraries: oauth-client (default), auth-code-redirect and sdk-auth-manager

oauth-client

The oauth-client library is the default library and is available by a simple import of '@pega/auth'. It implements simple OAuth client library for browser or Node cli clients to leverage OAuth services provided by Pega Infinity and Pega Launchpad. The methods facilitate the implementation of supported client-side initiated grant flows to the Pega Server. Presently it supports the following grant types: authorization code (with or without PKCE), client credentials, password credentials and custom bearer.

The library contains a single JS Class named PegaAuth, which facilitates the acquisition and management of OAuth tokens for a Web or Node client.

auth-code-redirect

The auth-code-redirect library facilitates the transfer of a received code or error at the end of an authorization code grant flow to the oauth-client library code, so it may proceed with access_token acquisition or reacting or reporting to the error encountered.

sdk-auth-manager

The library facilitates additional management of Authentication tokens as well as the bootstrapping of the Constellation Orchestration Engine and will be leveraged by the Pega Constellation SDKs for React and Angular and Web Components.

oauth-client library usage

To leverage this library, import the PegaAuth class from the default @pega/auth package or from '@pega/auth/oauth-client'.

Main methods:

constructor( ssKeyConfig, ssKeyDynState='')

The PegaAuth constructor takes one required argument (ssKeyConfig) which passes in an object with various configuration properties and values or is a string value indicating a sessionStorage key from which to read a JSON stringified representation of such a config object.

The constructor also has a 2nd optional argument (ssKeyDynState) which can either pass an initial empty object which should be used to place all dynamic state runtime property values, or may be a string value indicating a sessionStorage key from which to read and update such dynamic state. If omitted, and a string value is passed as first argument, '_DS' is appended to that value and dynamic state is saved to that session storage location.

Table of config values

| Property Name | Type | Default | Description | | ------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | serverType | string | 'infinity' | 'infinity' or 'launchpad' | | clientId | string | | OAuth 2.0 client registration id | | grantType | string | 'authCode' | OAuth 2.0 grant type (or 'none' for custom auth). Supported values: 'authCode", 'customBearer', 'clientCreds', 'passwordCreds' or 'none' | | clientSecret | string | | OAuth 2.0 client secret (only for confidential OAuth 2.0 client registrations) | | redirectUri | string | | OAuth 2.0 redirect URI (only relevant for 'authCode' grant type) | | authorizeUri | string | | URI to OAuth 2.0 authorize endpoint (only relevant for 'authCode' grant type) | | authService | string | | Infinity Authentication service alias (only relevant for 'authCode' grant type) | | appAlias | string | | Application alias for pega app being accessed. If not specified will utilize the default access group within the current user's operator record | | userIdentifier | string | | Pega operator user identifier to use (only relevant for 'authCode' grant type) | | password | string | | B64 encoded Pega operator password to use (only relevant for 'authCode' and 'passwordCreds' grant types) | | noPKCE | boolean | false | Set to true to disable PKCE (only relevant for 'authCode' grant type) | | silentTimeout | integer | 5000 | Milliseconds to wait for response during 'silent authentication' (only relevant for 'authCode' grant type) | | iframeLoginUI | boolean | false | Set to true to make a failed silent authentication iframe visible, rather than opening a popup window when silent authentication fails or times out (only relevant for 'authCode' grant type) | | tokenUri | string | | OAuth 2.0 token URI | | customTokenParams | string | | JSON structure with params to pass as part of customBearer grant flow | | noPopups | boolean | false | Set to true to disable any popup window attempts (only relevant for 'authCode' grant type) | | cert | string | | Path to certificate (only relevant for node usage and for 'authCode' grant type) | | key | string | | Path to key (only relevant for node usage and for 'authCode' grant type) | | winTitle | string | | Title of window to use on a local redirect (only relevant for node usage and for 'authCode' grant type) | | winBodyHtml | string | | Markup to place within window for a local redirect (only relevant for node usage and for 'authCode' grant type) | | isolationId | string | | Deprecated (Launchpad only) | | transform | boolean | true | Set to false to disable obfuscation of values stored in sessionStorage | | fnDynStateChangedCB | function | | function to invoke when a dynamic static property has changed | | useNodeFetch | boolean | false | Set to true to force the usage of node-fetch library (only relevant for node usage) | | secureCookie | boolean | false | Set to true to have server generate secure Pega-AAT and Pega-ART cookies for housing the access token and refresh token. |

Current Dynamic State properties updated during PegaAuth usage

| Property Name | Type | Default | Description | | -------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | codeVerifier | string | | codeVerifier value at start of auth code flow (important to save and have available particularly on a main window redirect) (only relevant for 'authCode' grant type) | | state | string | | state value generated by client at start of auth code flow and used to compare with state returned with authorization code | | sessionIndex | string | | sessionIndex value returned with first token endpoint call to then be passed on subsequent full re-authentications to tie the sessions together | | sessionIndexAttempts | number | | used prior to Infinity '24 and support for proper auth code flow error reporting | | acRedirectUri | string | | redirect uri used at start of auth code flow and sent later on matching token endpoint | | silentAuthFailed | boolean | | Keeps track of if silent auth failed so any retry should be a visible one (only relevant for 'authCode' grant type) |

async login()

The login method executes the specified OAuth 2.0 grantType and returns a promise which will contain the immediate or eventual token endpoint response.

loginRedirect()

The loginRedirect method kicks off an authorization code grant flow on the main window (only relevant for grantType='authCode').

checkStateMatch(state)

Returns true if the passed in state value matches the state which was set at the start of an authorization code grant flow (only relevant for grantType='authCode').

getToken(authCode)

Uses the passed in authCode to retrieve the access_token and any optional refresh_token specified for the OAuth 2.0 client registration.

async refreshToken(refreshToken)

Uses the passed in refreshToken to generate a new access_token as well as an updated refresh_token (if a refresh_token is enabled within the OAuth 2.0 client registration).

async revokeTokens(accessToken, refreshToken=null)

Revoke the specified tokens to in effect end the authentication session.

async getUserinfo(accessToken)

Retrieve the "user information" object associated with the passed in accessToken.

License

This project is licensed under the terms of the Apache 2 license.

The full license is available within the file named "LICENSE" and on apache.org.