An Overview of the Authorization Process

This is an overview of the Authentication/Authorization for Avaya Spaces, for a detailed tutorial see here.

Avaya Cloud Identity, the SSO engine behind Avaya Spaces, uses the OAuth 2.0 model, an industry standard commonly used for REST APIs. Essentially, client applications are given access tokens that authorize them to access Spaces on behalf of the user. Avaya Spaces differs from most OAuth 2 systems in that OAuth 2 is primarily used for authentication. Avaya Spaces doesn’t provide different authorization scopes- once a client application is authenticated, it is authorized to the permissions currently held by the user interacting with the application.

API user permissions are identical to the user permissions authorizing a user in the default web interface. By exploring the range of features available to a user in their capacity as an admin, member, or guest, one tends to gain an intuitive understanding of the permissions afforded to each. Alternatively, the table below summarizes which permissions are granted to which kind of user.

Avaya Spaces Client applications have the choice to build their architecture around two OAuth 2.0 grants types: authorization code, and implicit grant.

The authorization code flow is typically used in server-side applications. Because the source code for these applications is not exposed to the public, the client secret can be kept confidential. Authorization code flow is reliant on browser redirection for routing the end user between the client application and the authorization server.

The process is as follows:

1. When a server-side application needs to authorize a user, it should redirect them to the following URL:

   GET https://accounts.avayacloud.com/oauth2/authorize/%3Fredirect_uri%3DYOUR_REDIRECT_URL%26response_type%3Dcode%26client_id%3DYOUR_CLIENT_ID%26scope%3Dhttps%253A%252F%252Faccounts.avayacloud.com%252Fauth%252Fuserinfo.email%2Bhttps%253A%252F%252Faccounts.avayacloud.com%252Fauth%252Fuserinfo.profile%2Bhttps%253A%252F%252Faccounts.avayacloud.com%252Fauth%252Fzangspaces%26state%3D3%26access_type%3Doffline

   This URL will display Avaya Cloud Identity's login page. If the user is already logged in to Avaya Cloud Identity, they will automatically be forwarded to step 2.

2. Upon logging in, the user will be prompted by Avaya Cloud Identity to authorize your application to access their account.

3. If the user authorizes your application, Avaya Cloud Identity will make a call to YOUR_REDIRECT_URL with query parameters code and state.

4. The server must the make a POST request to https://accounts.avayacloud.com/oauth2/access_token. The payload is of form-data type, with the following parameters:

   Name	Description	JSON type	Required
   grant_type	The type of access being granted. In this case, "authorization_code"	String	Yes
   client_id	YOUR_CLIENT_ID, the ID received from Avaya Cloud Identity	String	Yes
   client_secret	The secret code received from Avaya Cloud Identity	String	Yes
   redirect_uri	YOUR_REDIRECT_URL, the URL to return the response data to.	String	Yes
   code	The code received in step 2	String	Yes
   token_endpoint	A string with value https%3A%2F%accounts.avayacloud.com%2Foauth2%2Faccess_token	String	Yes

Implicit grant: the implicit grant flow is typically recommended for mobile apps, browser extensions, and other client-side applications. These types of applications cannot guarantee the confidentiality of the client secret, and as a result, cannot authenticate the identity of the application.

The process is as follows:

1. When a client-side application needs to authorize a user, it should redirect them to the following URL:

   GET https://accounts.avayacloud.com/oauth2/authorize/%3Fredirect_uri%3DYOUR_REDIRECT_URL%26response_type%3Dtoken%26client_id%3DYOUR_CLIENT_ID%26scope%3Dhttps%253A%252F%252Faccounts.avayacloud.com%252Fauth%252Fuserinfo.email%2Bhttps%253A%252F%252Faccounts.avayacloud.com%252Fauth%252Fuserinfo.profile%2Bhttps%253A%252F%252Faccounts.avayacloud.com%252Fauth%252Fzangspaces%26state%3D3%26access_type%3Donline

   This URL will display Avaya Cloud Identity's login page. If the user is already logged in to Avaya Cloud Identity, they will automatically be forwarded to step 2.

2. Upon logging in, the user will be prompted by Avaya Cloud Identity to authorize your application to access their account.

3. The user will than be redirected to the redirect URI. The user's access token will be passed as a URI fragment in the redirect URI. The webpage hosted at the redirect URI must run a script that parses this access token.

4. Now that the application has the access token, the the application is free to make API requests on behalf of the user.

The following OAuth 2 Scopes are used across all Avaya Cloud Products:

To use the Avaya Spaces API, users need only the https://accounts.zang.io/auth/userinfo.email, https://accounts.zang.io/auth/userinfo.profile, and https://accounts.zang.io/auth/zangspaces scopes.