An Overview of the OAuth2 Authorization Process

This is an overview of authentication and authorization for Avaya Spaces. For a detailed tutorial click 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 does not 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. Since 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.

PKCE (Proof Key for Code Exchange) is an extension to the OAuth authorization code flow. It was originally designed to protect mobile apps, but its ability to prevent authorization code injection makes it useful for every OAuth client, even web apps that use a client secret.

To use PKCE flow your application should create a cryptographically-random 'code_verifier' and from this generate a 'code_challenge' using 'plain' or 'S256' transformation method. See https://oauth.net/2/pkce/ for more information about PKCE.

You can use OAuth authorization code flow with or without PKCE, but we recommend to use authorization code flow with PKCE with 'SHA-256' ('S256') hashing method for code challenge generation where it is acceptable.

The process is as follows:

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

   Without PKCE

   For Production: GET https://accounts.avayacloud.com/oauth2/authorize?redirect_uri=[REDIRECT_URI]&response_type=code&client_id=[CLIENT_ID]&scope=email%20profile%20spaces&state=0&access_type=offline&grant_type=[GRANT_TYPE]

   For Staging: GET https://onesnastaging.esna.com/oauth2/authorize?redirect_uri=[REDIRECT_URI]&response_type=code&client_id=[CLIENT_ID]&scope=email%20profile%20spaces&state=0&access_type=offline&grant_type=[GRANT_TYPE]

   Example:

   GET https://onesnastaging.esna.com/oauth2/authorize?redirect_uri=http://localhost:3000&response_type=code&client_id=8221d68a544225a02f3f&scope=email%20profile%20spaces&state=0&access_type=offline&grant_type=authorization_code

   With PKCE

   For Production: GET https://accounts.avayacloud.com/oauth2/authorize?redirect_uri=[REDIRECT_URI]&response_type=code&client_id=[CLIENT_ID]&scope=email%20profile%20spaces&state=0&access_type=offline&grant_type=[GRANT_TYPE]&code_challenge=[CODE_CHALLENGE]&code_challenge_method=[CODE_CHALLENGE_METHOD]

   For Staging: GET https://onesnastaging.esna.com/oauth2/authorize?redirect_uri=[REDIRECT_URI]&response_type=code&client_id=[CLIENT_ID]&scope=email%20profile%20spaces&state=0&access_type=offline&grant_type=[GRANT_TYPE]&code_challenge=[CODE_CHALLENGE]&code_challenge_method=[CODE_CHALLENGE_METHOD]

   Example:

   GET https://onesnastaging.esna.com/oauth2/authorize?redirect_uri=http://localhost:3000&response_type=code&client_id=8221d68a544225a02f3f&scope=email%20profile%20spaces&state=0&access_type=offline&grant_type=authorization_code&code_challenge=EShDYJmrAWSYOR6QTSrksvzz4b6mMA0Jm50rgwcP2ho&code_challenge_method=S256

   This URL displays 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.

   Note: You can configure multiple redirect URI in your OAuth application in the Developer Dashboard so that you can choose to use any of them. You need to start a new line for each new direct URI entry

2. Upon logging in, the user will be prompted by Avaya Cloud Identity to authorize the 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://[avayacloud_accounts_url]/oauth2/access_token. The payload is of form-data type, with the following parameters:

   Without PKCE:

   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, you should apply for it through Developer Dashboard	String	Yes
   client_secret	The secret code, you should apply for it through Developer Dashboard as well.	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

   Curl example:

   For Production: curl --location --request POST 'https://accounts.avayacloud.com/oauth2/access_token' --header 'accept:  application/json' --header 'content-type: application/x-www-form-urlencoded'
                    --data-urlencode 'client_secret=[client_secret]' --data-urlencode 'grant_type=authorization_code' --data-urlencode 'client_id=[client_id]' --data-urlencode 'redirect_uri=http://localhost:3000' --data-urlencode 'code=[code]'
                     

   For Staging: curl --location --request POST 'https://onesnastaging.esna.com/oauth2/access_token' --header 'accept:  application/json' --header 'content-type: application/x-www-form-urlencoded'
                    --data-urlencode 'client_secret=[client_secret]' --data-urlencode 'grant_type=authorization_code' --data-urlencode 'client_id=[client_id]' --data-urlencode 'redirect_uri=http://localhost:3000' --data-urlencode 'code=[code]'
                     

   With PKCE:

   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, you should apply for it through Developer Dashboard	String	Yes
   client_secret	The secret code, you should apply for it through Developer Dashboard as well.	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
   code_verifier	Code verifier which was used to generate a 'code_challenge' in step 1.	String	Yes

   Curl example:

   For Production: curl --location --request POST 'https://accounts.avayacloud.com/oauth2/access_token' --header 'accept:  application/json' --header 'content-type: application/x-www-form-urlencoded'
                    --data-urlencode 'client_secret=[client_secret]' --data-urlencode 'grant_type=authorization_code' --data-urlencode 'client_id=[client_id]' --data-urlencode 'redirect_uri=http://localhost:3000' 
                    --data-urlencode 'code=[code]' --data-urlencode 'code_verifier=[code_verifier]'
                     

   For Staging: curl --location --request POST 'https://onesnastaging.esna.com/oauth2/access_token' --header 'accept:  application/json' --header 'content-type: application/x-www-form-urlencoded'
                    --data-urlencode 'client_secret=[client_secret]' --data-urlencode 'grant_type=authorization_code' --data-urlencode 'client_id=[client_id]' --data-urlencode 'redirect_uri=http://localhost:3000' 
                    --data-urlencode 'code=[code]'  --data-urlencode 'code_verifier=[code_verifier]'
                     




5. You can also use the id_token that you received from the API call above to get basic user information from the token by performing a GET request on the URL:
   

   For Production: https://accounts.avayacloud.com/api/1.0/id_token/get_token_info?id_token=[id_token]

   For Staging: https://onesnastaging.esna.com/api/1.0/id_token/get_token_info?id_token=[id_token]

   - The Avaya cloud identity returns the basic user information directly

6. You can get basic information about access_token that you received from the API call in step 4 by performing a GET request on the URL:
   

   For Production: https://accounts.avayacloud.com/oauth2/tokeninfo?access_token=[access_token]

   For Staging: https://onesnastaging.esna.com/oauth2/tokeninfo?access_token=[access_token]

7. To call all other Spaces APIs, use the access_token with Bearer Authorization. For example, if your access_token is 76731740bc9341692e94de76d8f6d355, the Authorization header should be added to your API request.

   curl example:

   For Production: curl --location --request GET 'https://spacesapis.avayacloud.com/api/users/me' \ --header 'Authorization: bearer 76731740bc9341692e94de76d8f6d355'

   For Staging: curl --location --request GET 'https://loganstagingapis.esna.com/api/users/me' \ --header 'Authorization: bearer 76731740bc9341692e94de76d8f6d355'

8. The access_token will expire in one hour. You can use the refresh_token to get a new one by calling https://[avayacloud_accounts_url]/oauth2/access_token using the POST method with a x-www-form-urlencoded body containing client_id [client_id], client_secret [client_secret], grant_type: refresh_token, refresh_token [refresh_token]. Curl example:

   For Production: curl --location --request POST 'https://accounts.avayacloud.com/oauth2/access_token' \ --header 'accept:  application/json' \ --header 'content-type: application/x-www-form-urlencoded' \ --data-urlencode 'client_secret=e6f6eef1023105b0de20963dc2c76059e70bf8b9' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'client_id=6702b20d233fdebcf743' \ --data-urlencode 'refresh_token=57c4ce7a90d5c94b927a6a5e252b2598c610e39c'

   For Staging: curl --location --request POST 'https://onesnastaging.esna.com/oauth2/access_token' \ --header 'accept:  application/json' \ --header 'content-type: application/x-www-form-urlencoded' \ --data-urlencode 'client_secret=e6f6eef1023105b0de20963dc2c76059e70bf8b9' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'client_id=6702b20d233fdebcf743' \ --data-urlencode 'refresh_token=57c4ce7a90d5c94b927a6a5e252b2598c610e39c'

9. To allow the user to sign out of an OAuth2 client.

   For Production: curl --location --request POST 'https://accounts.avayacloud.com/oauth2/revoke_token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=TestClientId' \ --data-urlencode 'refresh_token=5787989087dnbjkr47898074fjmjkl459900f6761f'

   For Staging: curl --location --request POST 'https://onesnastaging.esna.com/oauth2/revoke_token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=TestClientId' \ --data-urlencode 'refresh_token=5787989087dnbjkr47898074fjmjkl459900f6761f'

Password grant: This authorization flow is used to get access token using username and password.

The process is as follows:

1. When logging in your OAuth2 application using the password grant type the following URL should be used:

   For Production: POST https://accounts.avayacloud.com/oauth2/access_token

   For Staging: POST https://onesnastaging.esna.com/oauth2/access_token

2. Form Parameters

   Format used for the POST method: application/x-www-form-urlencoded

   Key	Value
   client_id	[client_id]
   client_secret	[client_secret]
   grant_type	password
   scope	[scope]
   username	[username]
   password	[password]

3. You can also use the id_token that you received from the API call above to get basic user information from the token by performing a GET request on the URL:
   

   For Production: https://accounts.avayacloud.com/api/1.0/id_token/get_token_info?id_token=[id_token]

   For Staging: https://onesnastaging.esna.com/api/1.0/id_token/get_token_info?id_token=[id_token]

   - The Avaya cloud identity returns the basic user information directly

4. To allow the user to sign out of an OAuth2 client.

   For Production: curl --location --request POST 'https://accounts.avayacloud.com/oauth2/revoke_token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=TestClientId' \ --data-urlencode 'refresh_token=5787989087dnbjkr47898074fjmjkl459900f6761f'

   For Staging: curl --location --request POST 'https://onesnastaging.esna.com/oauth2/revoke_token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=TestClientId' \ --data-urlencode 'refresh_token=5787989087dnbjkr47898074fjmjkl459900f6761f'

The following OAuth2 scopes are used for Spaces API:

When possible, use short scope forms.