1. Introduction
  2. Authorization Code
  3. Implicit Grant
  4. OAuth 2 Scopes

1 Introduction

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

Zang 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.

2 Authorization Code

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.zang.io/oauth2/authorize/%3Fredirect_uri%3DYOUR_REDIRECT_URL%26response_type%3Dcode%26client_id%3DYOUR_CLIENT_ID%26scope%3Dhttps%253A%252F%252Faccounts.zang.io%252Fauth%252Fuserinfo.email%2Bhttps%253A%252F%252Faccounts.zang.io%252Fauth%252Fuserinfo.profile%2Bhttps%253A%252F%252Faccounts.zang.io%252Fauth%252Fzangspaces%26state%3D3%26access_type%3Doffline

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

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

  3. If the user authorizes your application, Zang 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.zang.io/oauth2/access_token. The payload is of form-data type, with the following parameters:

    NameDescriptionJSON typeRequired
    grant_typeThe type of access being granted. In this case, "authorization_code"StringYes
    client_idYOUR_CLIENT_ID, the ID received from Zang IdentityStringYes
    client_secretThe secret code received from Zang IdentityStringYes
    redirect_uriYOUR_REDIRECT_URL, the URL to return the response data to.StringYes
    codeThe code received in step 2StringYes
    token_endpointA string with value https%3A%2F%accounts.zang.io%2Foauth2%2Faccess_tokenStringYes

3 Implicit Grant

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.zang.io/oauth2/authorize/%3Fredirect_uri%3DYOUR_REDIRECT_URL%26response_type%3Dtoken%26client_id%3DYOUR_CLIENT_ID%26scope%3Dhttps%253A%252F%252Faccounts.zang.io%252Fauth%252Fuserinfo.email%2Bhttps%253A%252F%252Faccounts.zang.io%252Fauth%252Fuserinfo.profile%2Bhttps%253A%252F%252Faccounts.zang.io%252Fauth%252Fzangspaces%26state%3D3%26access_type%3Donline

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

  2. Upon logging in, the user will be prompted by Zang 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.

4 OAuth 2 Scopes

The following OAuth 2 Scopes are used across all Zang Products:

ScopeDescription
https://accounts.zang.io/auth/userinfo.emailView and Update user email information associated with your account
https://accounts.zang.io/auth/userinfo.profileView user detail information associated with your account
https://accounts.zang.io/auth/zangofficeAllow calling zangoffice apis
https://accounts.zang.io/auth/zangspacesAllow calling zangspaces apis

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.