Comodo ONE 3rd Party Authentication API Definition

Introduction

3rd Party Authentication and Authorization API provides a security mechanism similar to OAuth2 standard. With this mechanism client APIs can access C1 Platform Resources in a secure way. 

There are some prerequisites before usage of this API. 

• Client API credentials. Credentials will be provided by the C1 team. The credentials shall be used for HTTP Basic Authentication of endpoints.

• Resource owner credentials. Credentials shall be used for login endpoint. Username/password and TLS Client Certificate Verification.

First clients need to obtain access and refresh tokens via login endpoint. With access token clients can access protected resources. Please see section "Usage Of Access Token" to use access tokens. 

Access tokens are short-lived tokens. Therefore they expire quickly. New access tokens can be obtained without resource owner credentials via renew endpoint. Refresh tokens are used to create new access tokens. Refresh tokens are long-lived tokens and can be persisted for longer use. They are critical for the security of protected resources. Because of that please store them in a secure way and do not share them with any other 3rd parties. 

On order to access Authentication API TLS Client Certificate Verification is also performed. Therefore the test certificate must be shared with Comodo to grad access.

 

2. Endpoints

2.1. Authentication Service

Endpoint	https://api.one.comodo.com/auth/login
Method	POST
Authentication	HTTP Basic (Client API Credentials)
Content-Type	JSON (application/json)

 

Failed Response Format 

HTTP CODE	MESSAGE	DESCRIPTIONS
401	Not authorized	Client credentials or user password invalid.
400	Invalid request	Request parameters are missing or invalid.
400	Login parameters cannot be null	Request body doesn't contain username and password parameters.
400	Username or passsword is incorrect	User not found or password is wrong.
400	Certificate is not verified	SSL certificate can't verified by the server.
400	Serial number is not match	SSL certificate serial number doesn't match with the serial number in our database.
400	Certificate cn is not match	"CN=" string in the certificate DN doesn't match with the CN string in the database.

 

 

Descriptions:

REQUEST
NAME	TYPE	REQUIRED	DESCRIPTIONS
username	string	required	Username of the account admin
password	string	required	Password of the account admin
RESPONSE
NAME	TYPE	REQUIRED	DESCRIPTIONS
tokenType	string	required	bearer
accessToken	string	required	Access Token
refreshToken	string	required	Refresh Token
accessTokenExpiresAt	integer (UNIX Timestamp)	required	Access token lifetime. 1 hour
refreshTokenExpiresAt	integer (UNIX Timestamp)	required	Refresh token lifetime 1 week

 

HTTP CODE	MESSAGE	DESCRIPTIONS
401	Not authorized	Client credentials or user password invalid.
400	Invalid request	Request parameters are missing or invalid.

See the below link for details:

• Token Renew Service
• Token Validation Service
• Usage of Access Token

Execution

Sample execution can be handled via Postman Application. 

{     "username": "admin@test.com",     "password": "secret" }

Header part can be handled via Postman Application

Success Output

{     "tokenType": "bearer",     "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Imlwbmg3eHp5YmxtdnZoMmp4cDIwdW53c3Z5N3BoMHB6b3NtcTFvZmUiLCJpc3N1ZXIiOiJjMXBvcnRhbCIsInJlcXVlc3RlZEJ5IjoiNTA3ZjFmNzdiY2Y4NmNkNzk5NDM5MDExIiwiY3VzdG9tZXJJZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSIsImV4cGlyZXNBdCI6MTQ4MzcxMTY1MCwiaXNzdWVkQXQiOjE0ODM3MDgwNTAsInRva2VuVHlwZSI6ImJlYXJlciIsInNjb3BlIjp7Iml0c20tZG9tYWluIjoic3ViZG9tYWluLW1zcCJ9fQ.3ctZUI9rDMA_2Tyy0YnFgSXwoEoWfGcS9ROUSvimmro",     "refreshToken": "2xgb3cxm1qms9vg2a1f86mfe00coh7n8iyopsoep",     "accessTokenExpiresAt": 1483711650     "refreshTokenExpiresAt": 1483711650 }

Error Output