This article describes details of authentication and authorization implementation on CONTROL PANEL by REST Public API.

Overview

Authentication and authorization implementation is based on OAuth 2.0 with resource owner password credentials grant flow and refresh token flow.

The address of the service is https://cp.serverdata.net/webservices/auth/v1/token.

Client is an application making protected resource requests on behalf of the resource owner and with its authorization. The term client does not imply any particular implementation characteristics (e.g., whether the application executes on a server, a desktop, or other devices).

Resource server is the server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.

Authorization server is the server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

The authentication and authorization flow scheme:

Authentication and authorization flow

Initial Authentication and Authorization

  1. Client requests token by Public API Authorization Server using the following authentication items:
#ParameterType

Mandatory (Required (R)/ Optional (O))

Description
1 client_id string R Unique pre-registred client-specific value
2 client_secret string  R Client-specific secret (password)
3 grant_type string R

Resource owner password credentials grant type

Value MUST be set to client_credentials

Note: it is possible and preferable to use the

Authorization: Basic AUTH_FIELD (base64-encoded client_id:client_secret

header instead of related form fields. See item 2.3.1 of RFC 6749 for more information.

Request example 1:

POST /v1/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

Accept: application/json

grant_type=client_credentials&client_id=test&client_secret=abc123

  1. Public API Authorization Server responses with a token which contains the following items:
#PropertyType

Mandatory (R/O)

Description
1 access_token string R Short-lived secret token which contains encrypted claims and can be used to access resource
2 expires_in int  R Access token expiration time in seconds
3 token_type string R

Type of issued token

Value is bearer (currently it is the only supported type)

Success response example 2.1:

HTTP/1.1 200 OK

Content-Type: application/json

{

"token_type": "bearer",

"expires_in": 3600,

"access_token": "A1B2C3..."

}

Alternatively, Public API Authorization Server can response with an error. The response includes details.

Error response example 2.2:

HTTP/1.1 401 Unathorized

Content-Type: application/json

{

"error":"invalid_grant",

"error_description":"Invalid credentials."

}

Resource Access

  1. Client requests a resource from Public API Resource Server using access token

The request may contain different details, but in the headers should be the following: Authorization: Bearer ACCESS_TOKEN_HERE

Request example 3:

GET /api/v1/partners/0123456-789/contacts/003456789-123

HTTP/1.1 Authorization: Bearer A1B2C3D4...

Accept: application/json

  1. Public API Resource Server responses with the resource representation

Success response example 4.1:

HTTP/1.1 200 OK

Content-Type: application/json

{

"contactID": 003456789-123,

"accessRoleNames": [

"AG_PRIVATELABELOPERATORS"

],

"login": "paulpetit@test.com",

"name": "Paul Petit",

"email": "paulpetit@test.com",

"alternativeEmail": "petitpaul@testkato.com",

"phone": "11111111111",

"cellularPhone": "22222222222"

}

Alternatively, Public API Resource Server can response with an error (invalid or expired token).

Error response example 4.2:

HTTP/1.1 401 Unauthorized

Content-Type: application/json

{

"error": "invalid_token",

"error_description": "Access token has expired."

}

Specifics of Token Usage

The client must consider and observe the following specifics:

  • client secret, access token and refresh token should be kept secret
  • access token:
    • has short lifetime (e.g. an hour);
    • is exposed only to the Resource Server;
    • has self-contained info (claims);
    • can't be revoked
  • access token expiration time should be taken into account by the client

Client resource access flow using token is performed the following way:

  1. Try to access resource using access token
  2. Try to get a new token using authorization grant and retry (see item 1 of the Initial Authentication and Authorization section).