How to Authenticate with Avaya Experience Platform™ APIs

Introduction

The Avaya Experience Platform™ A&A Service provides the following capabilities:

• Authenticate users locally or with enterprise IDPs via OIDC and SAML.
• Authenticate clients or applications using OAuth2 Access Tokens passed as Bearer token in the request.
• Provide a means to applications to authorize users and other applications by virtue of the roles and permissions present in the access token.

This document describes the APIs supported in order to meet the capabilities described above. Before that, a few terminologies:

The Avaya Experience Platform™ A&A Service (henceforth called A&A) facilitates both authentication and authorization. The authentication is not done very frequently (often only at startup or when trying to refresh tokens). After successfully authenticating itself and (optionally) a user, a client is issued an “access token” which is then presented to the resource server along with each request. The resource server does not authenticate the entity making the request, but validates the token and ensures that the token indicates that the requested operation may be invoked by the client holding the token.

Supported OAuth2 Flows

OAuth 2.0 defines four grant types, which clients can use to request access tokens. For the current release, A&A supports three of them. A&A requires the client to authenticate itself with every one of these grant types, even those that additionally authenticate a user.

• Client Credentials (CC) Grant Type
  • This grant type only authenticates the client (not a user). It is generally useful for server-based applications that are not acting on the behalf of a particular user.
• Authorization Code (Code) Grant Type
  • This grant type authenticates both the client and the user. It is a redirect-based flow.
  • Your application does not handle the user’s credentials, instead of redirecting the user’s browser to A&A for validation of the user's credentials.
  • Once the user’s credentials have been validated by A&A, it redirects the browser back to your application with an authorization code, which your application then exchanges for an access token.
  • The benefit of this flow is that it enables SAML and OIDC based authentication with external IDPs.
  • This grant type is used to login a user to the Avaya Experience Platform™ Admin Portal and Agent Desktop.
• Resource Owner Password Credentials (ROPC) Grant Type
  • This grant type authenticates both the client and the user. It is NOT a redirect-based flow.
  • This flow is simpler than the Authorization Code Grant Type flow, but it is more limited as it does not allow for SAML and OIDC. In other words, it only works if user identities (Administrators, Agents, etc) are managed locally by Avaya Experience Platform™.
  • In this flow, the client passes its own credentials as well as the end-user's credentials in a single request and can obtain an access token after successful authentication of both entities.

Diagram of Avaya Experience Platform™ APIs Supported OAuth2 Flow

Here is a high-level overview of how Avaya Experience Platform™ APIs utilize an OAuth2 Flow to authenticate Avaya Experience Platform™ API use:

Client Registration

Clients need to be registered first before they can request access tokens - either for users or themselves. At present, an Account (Tenant) Administrator must make a request to an Avaya Experience Platform™ Administrator to create a client on their behalf.

The request needs the following information:

• Client ID - A name (string) to uniquely identify the client. It can contain letters, numbers, and special character '-' (hyphen). Client ID is not case sensitive.
• Scope - Provide the name of the APIs that the client will invoke. The Avaya Experience Platform™ Administrator will use this information to set up the client with relevant roles and permissions.

🚧

Please Contact Your Avaya Experience Platform™ Administrator or Representative to Start Client Registration Process

You will need to provide the following information:

• Client ID - A name (string) to uniquely identify the client. It can contain letters, numbers, and special character '-' (hyphen). Client ID is not case sensitive.
• Scope - Provide the name of the APIs that the client will invoke. The Avaya Experience Platform™ Administrator will use this information to set up the client with relevant roles and permissions.

Avaya Experience Platform™ Administrator registers a client and shares the Account ID, Client ID, and Secret with Account (Tenant) Administrator via Email or other means of communication.

A future revision of Avaya Experience Platform™ will provide Account (Tenant) Administrators the ability to provision their client from Avaya Experience Platform™ Admin Portal.

Acquiring Tokens

Client Credentials Grant

Request

curl -X POST https://REGION.cc.avayacloud.com/auth/realms/{accountId}/protocol/openid-connect/token -H 'Content-Type:application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id={clientId}&client_secret={secret}'

Response

• Content-Type: application/json
• Success (200)

{
    "access_token": "eyJhbGciOiJSUzI1....",
    "expires_in": 900,
    "refresh_expires_in": 9000,
    "refresh_token": "eyJhbGciOiJIUzI1....",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "e516c8cc-a90c-4e5f-b4d2-d0551681f0e7",
    "scope": "profile email"
}

• Failures
  • Bad Request (400) - grant_type or client_id is invalid
  • Unauthorized (401) - secret is wrong.
  • Not Found (404) - account id is invalid.

{
    "error": "unauthorized_client",
    "error_description": "Invalid client secret"
}

Resource Owner Password Credentials Grant

Request

curl -X POST https://REGION.cc.avayacloud.com/auth/realms/{accountId}/protocol/openid-connect/token -H 'Content-Type:application/x-www-form-urlencoded' -d 'grant_type=password&client_id={clientId}&client_secret={secret}&username={userName}&password={userPassword}'

Response

• Content-Type: application/json
• Success (200)

{
    "access_token": "eyJhbGciOiJSUzI1....",
    "expires_in": 900,
    "refresh_expires_in": 9000,
    "refresh_token": "eyJhbGciOiJIUzI1....",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "e516c8cc-a90c-4e5f-b4d2-d0551681f0e7",
    "scope": "profile email"
}

• Failures
  • Bad Request (400) - grant_type or client_id is invalid
  • Unauthorized (401) - secret is wrong.
  • Unauthorized (401) - username password combination is wrong.
  • Not Found (404) - account id is invalid.

{
    "error": "unauthorized_client",
    "error_description": "Invalid client secret"
}

Token Refresh

Request

curl -X POST https://REGION.cc.avayacloud.com/auth/realms/{accountId}/protocol/openid-connect/token -H 'Content-Type:application/x-www-form-urlencoded' -d 'grant_type=refresh_token&client_id={clientId}&client_secret={secret}&refresh_token={refresh_token}'

Response

• Content-Type: application/json
• Success (200)

{
    "access_token": "eyJhbGciOiJSUzI1....",
    "expires_in": 900,
    "refresh_expires_in": 9000,
    "refresh_token": "eyJhbGciOiJIUzI1....",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "e516c8cc-a90c-4e5f-b4d2-d0551681f0e7",
    "scope": "profile email"
}

• Failures
  • Bad Request (400) - grant_type, client_id or refresh_token is invalid
  • Unauthorized (401) - secret is wrong.
  • Not Found (404) - account id is invalid.

{
    "error": "invalid_grant",
    "error_description": "Invalid refresh token"
}

Making an API Call

An access_token proves the identify of the caller at the Resource Server and enforce access control. Include the access_token in the Authorization header of a REST API request as follows.

Authorization: Bearer eyJhbGciOiJSUzI1....

A&A Failure Codes:

• Unauthorized (401) - Missing or Invalid token.
• Access Denied (403) - Token validation successful, but insufficient privileges.

Additional Resources

Avaya Learning Videos

How to Authenticate With Avaya Experience Platform™ APIs