1. Introduction
  2. Authorize with OAuth2 using authorization_code
  3. Authorize with OAuth2 using password
  4. OAuth 2 Scopes

1 Introduction

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.

2 Authorize with OAuth2 using "authorization_code"

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:

    NameDescriptionJSON typeRequired
    grant_typeThe type of access being granted. In this case, "authorization_code"StringYes
    client_idYOUR_CLIENT_ID, you should apply for it through Developer DashboardStringYes
    client_secretThe secret code, you should apply for it through Developer Dashboard as well.StringYes
    redirect_uriYOUR_REDIRECT_URL, the URL to return the response data to.StringYes
    codeThe code received in step 2StringYes

    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:

    NameDescriptionJSON typeRequired
    grant_typeThe type of access being granted. In this case, "authorization_code"StringYes
    client_idYOUR_CLIENT_ID, you should apply for it through Developer DashboardStringYes
    client_secretThe secret code, you should apply for it through Developer Dashboard as well.StringYes
    redirect_uriYOUR_REDIRECT_URL, the URL to return the response data to.StringYes
    codeThe code received in step 2StringYes
    code_verifierCode verifier which was used to generate a 'code_challenge' in step 1.StringYes

    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'

3 Authorize with OAuth2 using "password"

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

    KeyValue
    client_id[client_id]
    client_secret[client_secret]
    grant_typepassword
    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'

4 OAuth 2 Scopes

The following OAuth2 scopes are used for Spaces API:

When possible, use short scope forms.

ScopeShort scopeDescription
https://accounts.avayacloud.com/auth/userinfo.emailemailView and Update user email information associated with your account
https://accounts.avayacloud.com/auth/userinfo.profileprofileView user detail information associated with your account
https://accounts.avayacloud.com/auth/spacesspacesAllow calling zangspaces apis