API Authorization

Introduction

The Atlas API implements the OAuth 2.0 authorization framework along with OpenID Connect to control access to the protected API resources. The Atlas authorization server is responsible for authenticating login credentials, determining the access level, and issuing access tokens for use with the Atlas resource server.

While OAuth 2.0 + OpenID Connect provides six flows for interacting with the authorization server to obtain access tokens, Atlas authorization currently implements the following authorization flows:

• Hybrid Grant Type
• Client Credentials Grant Type

It is the responsibility of the 3rd party client system to store the client ID and client secret and to secure the client secret.

Once the 3rd party client system has obtained an access token, it can then use the access token to make calls to the Atlas resource servers. The API Resources page details how to use the access token and what resources are available.

Access tokens are valid for twenty-four hours. When an access token expires, the client can request another access token if a refresh token is available.

Requesting Access Tokens

In order to access any of the Atlas API resource endpoints, an access token must first be obtained from the Authorization service.

The following information is required to request an access token, and must be obtained through a Atlas customer:

• Client ID
• Client Secret
• Tenant

These values may also be required when requesting an access token, but will be sent with standardized values:

• Grant Type
• Scope
• Response Type
• State
• Nonce

Currently, the Atlas API supports two workflows for authorization - Client Credentials and Implicit grant types.

Hybrid Grant Type

Overview

Hybrid grant type is an authentication workflow that was added to the OAuth2.0 protocol in the OpenID Connect authentication layer. It is a combination of the base OAuth 2.0 standards of Implicit grant type and Authorization Code grant type.

The Hybrid grant type is used when requests to the Atlas API will be made in from a 3rd party system with a user context. This grant type requires that a resource owner (Atlas user) be present to enter their username and password to authenticate the user context. This workflow involves a redirect to the Atlas authorization server, at which point the resource owner is then redirected back to the 3rd party system.

Flow

With the Hybrid grant type, the flow begins with the resource owner visiting the 3rd party client site. To begin the authorization process, the resource owner clicks a link that will send them to the Atlas authorization server. This link will contain the Client ID as one of its request parameters. The flow then branches based on the resource owner's current authentication:

• If the resource owner is already logged in to the Atlas authorization server, they will be redirected immediately to the specified redirect URI.
• If the resource owner is not already logged in to the Atlas authorization server, they are taken to the login page to enter their username and password. After a successful login they are then redirected to the specified redirect URI.

The redirect URI should point to a location controlled by the 3rd party client. Atlas will add the access token to the redirect URI fragment. The 3rd party client system will then parse the access token from the redirect URI fragment.

Authorization Request

The authorization request is an HTTP GET to the /connect/authorize endpoint. This is typically done through a link that a resource owner clicks on in their browser.

The following is the format of the authorization request:

• Client_ID: the Client ID provided by the Atlas customer
• Redirect_URI: the URI on the 3rd party website that the resource owner will be redirected to
• Response_Type: the type of token that the 3rd party website is expecting - generally this will be "code id_token token"
• Scope: a list of space delimited values that define the resources the 3rd party needs access to. Resources can be accessed with the resource scope of "PublicWebApi" and identity scopes use "openid" and one or more the following values:
  • profile
  • email
  • address
  • phone
  • roles
  • all_claims
• State: a value passed by the 3rd party system that will be returned with the redirect to be validated and reduce the risk of cross-site request forgery.
• Nonce: a random value that is embedded in the token and returned to verify that the token matches the authorization request
• Tenant: the SiteID of the Atlas client that the requests will be made for

Example

Using the example values below, the following is the resulting authorization request:

• Client_ID: AtlasExample
• Redirect_URI: https://www.example.com
• Response_Type: code id_token token
• Scope: openid PublicWebApi profile roles
• State: state12345
• Nonce: nonce12345
• Tenant: WEBLINKAPIINCOC

Authorization Response

After a successful login, the authorization server will return an HTTP 302 Found status code with a location set to the redirect URI specified in the authorization request and the access token in the URI fragment.

The following is the format of the authorization response redirect URI:

• Redirect_URI: the redirect URI specified in the authorization request
• Code: used in requesting a refresh token (not currently implemented)
• ID_Token: the ID token for the resource owner
• Access_Token the access token for accessing the resource server
• Token_Type: the token type of the ID/access token
• Expires_In: the time in seconds that the token will expire - generally set to 3600 (1 hour)
• Scope: the Resource and Identity scopes sent in the authorization resuest
• State: the state (if included) in the authorization request
• Session_State: used for OpenID Connect Session Management

Example

The following is the authorization response from the example authorization request above:

User Information Request

Once an authorization response has been obtained following the method outlined above, a secondary request to the Atlas authorization server can be made to obtain information about the user that was just authenticated.

The following is the format of the user information request:

• Authorization: the word "Bearer" plus a single space and the Access_Token from the Authorization Response

Example

Using the example values below, the following is the resulting user information request:

• Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImEzck1VZ01Gdjl0UGNsTGE2eUYzekFrZnF1RSIsImtpZCI6ImEzck1VZ01Gdjl0UGNs
  TGE2eUYzekFrZnF1RSJ9.eyJpc3MiOiJodHRwczovL3d3dy53ZWJsaW5rYXV0aC5jb20iLCJhdWQiOiJodHRwczovL3d3dy53ZWJsaW5rYXV0aC5j
  b20vcmVzb3VyY2VzIiwiZXhwIjoxNTIyMDk3NDU4LCJuYmYiOjE1MjIwOTM4NTgsImNsaWVudF9pZCI6IkNQaGlsbGlwc1Rlc3QiLCJzY29wZSI6W
  yJQdWJsaWNXZWJBcGkiLCJvcGVuaWQiLCJwcm9maWxlIl0sInN1YiI6IkNocmlzUUFJTkNPQ191XzMiLCJhdXRoX3RpbWUiOjE1MjIwOTM4NDMsIm
  lkcCI6Imlkc3J2IiwiYW1yIjpbInBhc3N3b3JkIl19.NwaRo6X72uERt1UPy0GqPVl2Qis4Pl8Nkp47nmFKpwaOhIJ2DowKmCZYhQongvZFWr-o23
  aVbWNyfjka7Cd_pMJ3Kk9DDv3MXHNj-M683CpN4R5gsuvUp6HsdZiFJJ_6_XdlHzXF3XLatCyDnFwltmZAQVRbHj-MvdRMgwh8XyeWlKFD-uBAdx5
  wi_A5ryy9LMmHbBrNWpcVrffzZ3WczQhpvPu_ydv3ZJ97_S2zJSpK3Z0sZkhcldMRFLODW-qY3bhypKMZYzo3DjnnwZ0PJJRo827gs2ogm2IfKn-b
  aP5XPuqxldei3RmmFdohrtsYVqpRjX8dTv1U5kz0Ntl9pw

User Information Response

If the user has successfully logged in, a successful user information request will return an HTTP 200 OK status code with the information about the authenticated user included in the response body.

The following is the format of the user information response:

• Sub: a unique combination of the tenant, either a "u" for user or "p" for profile, and the associated user or profile ID value
• Name: the user's full name
• Given_Name: the user's given (first) name
• Family_Name: the user's family (last) name
• Email: the user's email address
• Role: the user's role (can either be "Profile User" if the user is authenticated as a member, or an actual role such as "Administrator" if authenticated as a system user)
• Website: the website associated with the authenticated user
• Client_Id: the Atlas API Client ID associated with the Access_Token on the request
• WLI_Username: the Atlas username associated with the authenticated user
• WLI_Usernum: the Atlas usernum associated with the authenticated user (will be 0 for users authenticated as members)
• WLI_ProfileId: the Atlas profile ID associated with the authenticated user
• WLI_Customer_Id: the Atlas customer ID for the user's tenant
• WLI_User_Type: the user type for the authenticated user
• WLI_User_Access_Type: the access type granted to the authenticated user
• WLI_Tenant: the tenant name for the authenticated user
• WLI_Tenant_HTTP_URL: the non-secure HTTP root for accessing the tenant's Atlas components
• WLI_Tenant_HTTPS_URL: the secure HTTP root for accessing the tenant's Atlas components and API
• WLI_AssocInfo_OrgName: the association's organization name set in their instance
• WLI_AssocInfo_TimeZoneOffset: the offset (in hours) from GMT that is set in the tenant's database
• WLI_AssocInfo_TimeZone: the human-friendly name for the tenant's selected time zone
• WLI_AssocInfo_AssociationVerticalTypeId: the ID value for the tenant's association type
• WLI_AssocInfo_AssociationVerticalType: the association type of the tenant

Example

The following is the user information response from the example user information request above:

Client Credentials Grant Type

Overview

The Client Credentials grant type is used when requests to the Atlas API will be made in from a 3rd party system without a user context. In this workflow, an access token will be returned without an accompanying ID token. The benefit of this workflow is that a resource owner is not required and therefore the authorization requests can be made quickly and easily by using a Client ID and Client Secret.

Flow

With the Client Credentials grant type, the 3rd party system initiates the authorization process by making a request to the Atlas authorization server using the Client ID and Client Secret. This grant type is for highly trusted clients and is useful for 3rd party systems using the API to run batch or background operations without the interaction of a resource owner.

Access Token Request

The access token request is an HTTP POST to the /connect/token endpoint. The Client ID and Client Secret are passed in the body of the request.

The following is the format of the access token request:

• Client_ID: the Client ID provided by the Atlas client
• Client_Secret: the Client Secret provided by the Atlas client
• Tenant: the SiteID of the Atlas client that the requests will be made for

Example

Using the example values below, the following is the resulting access token request:

• Client_ID: AtlasExample
• Client_Secret: a36b490e-81fe-47a1-bea6-0376b7801148
• Tenant: WebLinkAPIINCOC

Access Token Response

After a successful access token request, the access token response returns an HTTP 200 OK status code with the access token included in the response body.

The following is the format of the access token response:

• Access_Token: the access token for accessing the resource server
• Expires_In: the time in seconds that the token will expire - generally set to 3600 (1 hour)
• Token_Type: the token type of this access token

Example

The following is the access token response from the example access token request above: