AuthProvider plugin
The AuthProvider plugin integrates your brand's login system into Messenger by providing your authCode and refreshToken to our Auth plugin, so it can identify each user and start an authenticated conversation.
This JavaScript plugin is authored by your web team. Add the AuthProvider plugin to your web page directly after the location where you deploy the Messenger snippet. Alternatively, use the defer keyword in your script tag to execute the AuthProvider plugin after the page is loaded.
It should contain the following commands and resolve with the data as shown in the below table.
Also see Configure Messenger for authenticated web messaging.
AuthProvider plugin commands
AuthProvider.getAuthCode
This command must contain logic related to fetching the brand's authorization code, specifically authCode and redirectUri. This command must always resolve with this data along with codeVerifier when PKCE flow is enabled. And also this command must resolves with nonce and optionally maxAge if the brand's authorization provider is chosen to be OKTA. Internally, our Auth plugin calls this command and use this data to retrieve a JWT token from the Genesys Cloud Auth API.
Resolutions:
Name | Description | Return message |
resolved | When the auth code is successfully fetched | Return Data |
rejected | When there is an error with the user credentials | - |
{
"authCode": <alphanumeric string>, // mandatory field
"maxAge": <Time in seconds>, // optionally required if the brand's authorization provider is OKTA
"nonce": <alphanumeric string>, // optionally required if the brand's authorization provider is OKTA
"redirectUri": <url>, // mandatory field
"codeVerifier": <alphanumeric string> //required if PKCE flow is enabled
}Note: The Auth plugin can call this command repeatedly as needed to fetch the latest authCode when the previously provided code has expired. Therefore, this command must always resolve with the latest authCode.
AuthProvider.reAuthenticate
This command must contain logic related to handling your brand's login process. This can be as simple as calling the login() function that is bound to your login button click. This way when the user logs in again, the new authorization code is retrieved. Messenger calls this command when the current authorization code or refresh token is expired.
Resolution: Not applicable.
AuthProvider.signIn
This command is required when Step-up conversation is enabled. It must contain logic related to brand reading user credentials from the login form and trigger the login process.
Similar to AuthProvider.getAuthCode command, this command must resolve with the same data as in there. Typically, you will call the same login method that you would have already integrated with above command and resolve with appropriate data. The difference here in having sign-in command is, it will let Messenger know that the brand is not signed-in yet (although Messenger is initialized) and it can now try to sign-in later.
Auth plugin will call this command when Messenger is trying to step-up the conversation and it will wait until the tokens are retrieved. This command must publish AuthProvider.signedIn event along with the same resolved data to let Messenger know that the sign-in was successful so it can reinitialize itself.
Resolutions:
Name | Description | Events published | Return message |
resolved | When the user is successfully signedIn | Return Data | |
rejected | When there is an error with the user credentials | - |
{
"authCode": <alphanumeric string>, // mandatory field
"maxAge": <Time in seconds>, // optionally required if the brand's authorization provider is OKTA
"nonce": <alphanumeric string>, // optionally required if the brand's authorization provider is OKTA
"redirectUri": <url>, // mandatory field
"codeVerifier": <alphanumeric string> //required if PKCE flow is enabled
}Note: Stepping up the conversation will be allowed only when this command is defined by the brand.
AuthProvider plugin events
AuthProvider.signedIn
Published when brand has signed in successfully.
Note: It is required to publish this event when Step-up conversation feature is enabled. This will let Messenger know that the user has signedIn successfully so it can re-initialize itself.
{
"authCode": <alphanumeric string>,
"maxAge": <Time in seconds>,
"nonce": <alphanumeric string>,
"redirectUri": <url>,
"codeVerifier": <alphanumeric string>
}AuthProvider.signInFailed
Published when brand fails to sign-in. This will let Messenger know that something went wrong in the sign-in process so it can set the UI state accordingly.
Note: It is required to publish this event when Step-up conversation feature is enabled. This will let Messenger know that the sign-in process has failed so it can reset its UI state.
Data: Authentication error data
Authentication with AutoStart enabled
In headless mode, when Authentication is enabled in the Messenger configuration, a WebSocket connection is automatically established to check and restore any active authenticated conversation. In this case, when AutoStart is enabled too and there is no active conversation, a new conversation is automatically started which may not be the ideal behavior. To avoid this, following setting is required in your AuthProvider plugin. This will let Messenger know to only configure the conversation session but not auto start yet.
AuthProvider.data('settings', {
headless: {
configureOnly: true
}
});Later when you are ready to start the conversation, i.e. typically when you open the Messenger, MessagingService.joinConversation command can be used which will send the JOIN event.
