- 08 Jul 2022
- 3 Minutes to read
-
Print
-
DarkLight
OAuth API
- Updated on 08 Jul 2022
- 3 Minutes to read
-
Print
-
DarkLight
Document Version | API Version | Release notes | Release Date | Author |
---|---|---|---|---|
V1.0 | V1 | 2022-05-19 | Hardy, Cyrus |
Contents
Authorize
The authorize
endpoint can be used to request tokens or authorization codes via the browser. This process typically involves authentication and authorization confirmation of the end-user.
GET /oauth/authorize
- Get authorization code
Get authorization code
GET /oauth/authorize
Parameters:
Name | Type | in | Required | Description |
---|---|---|---|---|
client_id |
string | query | yes | Client ID. |
response_type |
string | query | yes | The value is "code". |
redirect_uri |
string | query | yes | Must exactly match one of the allowed redirect URIs for that client. |
Response
- Redirect to sign-in page
- Redirect to grant-confirmation page
- Redirect to
redirect_uri
with query parameters
Name | Type | in | Description |
---|---|---|---|
code |
string |
query | Authorization Code. |
Example
Sample Request:
https://partner.comm100.io/oauth/authorize?client_id=1d29e6d7-18cf-407d-a064-e4f8c4baefab&response_type=code&redirect_uri=https://client1.company.com
Response
HTTP/1.1 302 Redirect
- Redirect to https://partner.comm100.io/login?retUrl=https%3A%2F%2Fpartner.comm100.io%2Foauth%2FAccount%2FLogin%3FReturnUrl%3D%252Fconnect%252Fauthorize%252Fcallback%253Fclient_id%253Dclient1%2526response_type%253Dcode%2526redirect_uri%253Dhttps%25253A%25252F%25252Fclient1.company.com%25252Fauth%25252Foauth%25252Freturn%25252FComm100CLIAPI%25252F%2526scope%253Dids.scope%252520offline_access
- Redirect to https://partner.comm100.io/oauth/account/login?ReturnUrl=%2Fconnect%2Fauthorize%2Fcallback%3Fclient_id%3Dclient1%26redirect_uri%3Dhttps%253A%252Fclient1.company.com%252Fauth%252Foauth%252Freturn%252FComm100CLIAPI%252F%26scope%3Dids.scope%2520offline_access
- Redirect to https://partner.comm100.io/auth/oauth/return/Comm100CLIAPI/?code=******&scope=ids.scope%20offline_access
- Click the
Allow
button. - Redirect to https://client1.company.com/?code=4D5B8C97FBD59B5A01D9FB7C4FCCA8B7802652DFB274C3772BDF42E2C2DE9F76&scope=comm100%20offline_access%20openid&session_state=nJPx3fSHGXPpoYvr1YGCgntZ-mmNDwpK6DiIh82rEE0.8410B9C95EC984EA837765F7E6DFB171
The code information is returned in above url 'code=4D5B8C97FBD59B5A01D9FB7C4FCCA8B7802652DFB274C3772BDF42E2C2DE9F76
'.
Token
The token endpoint can be used to programmatically request tokens. It supports the password
, authorization_code
and refresh_token
.
POST /oauth/token
- Request token by Authorization CodePOST /oauth/token
- Request token by PasswordPOST /oauth/token
- Refresh_token
Token JSON Format
Token is represented as simple flat JSON objects with the following keys:
Name | Type | Description |
---|---|---|
access_token |
string |
Access token. |
expires_in |
integer |
The lifetime in seconds of the token. |
token_type |
string |
Token type. |
refresh_token |
string |
The refresh token. |
Request token by Authorization Code
POST /oauth/token
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
client_id |
string |
form | yes | Client ID. |
client_secret |
string |
form | yes | Client secret. |
grant_type |
string |
form | yes | The value is "authorization_code". |
redirect_uri |
string |
form | yes | Redirect URI. |
code |
string |
form | yes | The authorization code. |
Response
The response is a Token object.
Example
Sample Request:
curl https://partner.comm100.io/oauth/token \
-H 'Content-Type:x-www-form-urlencoded' \
-X 'POST' \
-D 'client_id=1d29e6d7-18cf-407d-a064-e4f8c4baefab&client_secret=******&grant_type=authorization_code&code=4D5B8C97FBD59B5A01D9FB7C4FCCA8B7802652DFB274C3772BDF42E2C2DE9F76&redirec_uri=https://client1.company.com'
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9.eyJuYmYiOjE2NTI5NDAwMDMsImV4cCI6MTY1Mjk4MzIwMywiaXNzIjoiaHR0cDovL2ludGVybmFsZGFzaC50ZXN0aW5nLmNvbW0xMDBkZXYuaW8iLCJhdWQiOiJpZHMucmVzb3VyY2UuMSIsImNsaWVudF9pZCI6InphcGllciIsInN1YiI6IjJmYTUwMGJmLTA2YWUtNGQ5YS1hNTA5LThjNjY5OGIxZTFjZiIsImF1dGhfdGltZSI6MTY1MjkzOTc2MiwiaWRwIjoibG9jYWwiLCJzaXRlSWQiOiI1MDAwMDAzIiwiYWdlbnRJZCI6IjJmYTUwMGJmLTA2YWUtNGQ5YS1hNTA5LThjNjY5OGIxZTFjZiIsInRodW1icHJpbnQiOiI5NjE2NkNBM0IzNEFCRjJEMDRERjk2QTAxNUJCREREMDlCMEE3QzU5Iiwic3VjY2VzcyI6IlRydWUiLCJyb2xlIjoiYWdlbnQiLCJqdGkiOiI5MzlGMTIxRkUwMEY1MTRCRkEzREYzNzU4MTEwNEQ0RiIsInNpZCI6IkVEMkEwMzNBMDNFOTFGOEFCNjhENUE2M0E3RkUwNTU4IiwiaWF0IjoxNjUyOTQwMDAzLCJzY29wZSI6WyJpZHMuc2NvcGUiLCJvZmZsaW5lX2FjY2VzcyJdLCJhbXIiOlsicHdkIl19.xbBhIjWmnNvbnJk2wPtV4kvdJeU8k3dUyq5vvLP5R1R-aA7VGaLTq5y7fROCv01ggsqoSH-YEsQvdh4xX9YZk5dP7O62OWxITwdH8Z27DN63cJ3TLwvMRbZaAqXzcd-mkR8f5NH57Un2E8jvTtmWq1N3rDB9D0dwECzWqbSd1FgHxDg3e_o5VsNgq2jCvyTBFDSDFvIerO2xIpZJ-zfI5dKa1lIdn-89l0IDS5Z4pCAbjEr2YPYqhFfguUvKvvpWoJX2ivRuFSlwuIkFes9ivWIFomZyHAjzLccNopT4nqBc_0UE-3xfnM0ukr0jUT2ig9DUrHE6G5AhskzxjNizNQ",
"expires_in": 43200,
"token_type": "Bearer",
"refresh_token": "B9C62B757597F7C923415953512FB7DB2937BE065DDF920E8136DFECCFCBBB2B"
}
Request token by Password
POST /oauth/token
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
client_id |
string |
form | yes | Client id. |
client_secret |
string |
form | yes | Client secret. |
grant_type |
string |
form | yes | The value is "password". |
email |
string |
form | yes | Resource owner email. |
password |
string |
form | yes | Resource owner password. |
Response
The response is a Token object.
Example
Sample Request:
curl https://partner.comm100.io/oauth/token \
-H 'Content-Type:x-www-form-urlencoded' \
-X 'POST' \
-D 'client_id=1d29e6d7-18cf-407d-a064-e4f8c4baefab&grant_type=password&email=client1@company.com&password=******'
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9.eyJuYmYiOjE2NTI5MzkzOTEsImV4cCI6MTY1Mjk4MjU5MSwiaXNzIjoiaHR0cDovL2ludGVybmFscGFydG5lci50ZXN0aW5nLmNvbW0xMDBkZXYuaW8iLCJhdWQiOiJpZHMucmVzb3VyY2UuMSIsImNsaWVudF9pZCI6ImRhdGFzeW5jIDEwMDAwIiwic3ViIjoiYmZlYjQ1ZDctNTBkYy00MTZkLWIzYzgtMzVkYjY0ZDI4OGYzIiwiYXV0aF90aW1lIjoxNjUyOTM5MzkxLCJpZHAiOiJsb2NhbCIsInVzZXJJZCI6ImJmZWI0NWQ3LTUwZGMtNDE2ZC1iM2M4LTM1ZGI2NGQyODhmMyIsInBhcnRuZXJJZCI6IjEwMDAwIiwidGh1bWJwcmludCI6Ijk2MTY2Q0EzQjM0QUJGMkQwNERGOTZBMDE1QkJEREQwOUIwQTdDNTkiLCJzdWNjZXNzIjoiVHJ1ZSIsInJvbGUiOiJVc2VyIiwianRpIjoiODVFNzUzQTYwRDY4MzI4MjlEMkU4MDEwNUU3NTAwNjIiLCJpYXQiOjE2NTI5MzkzOTEsInNjb3BlIjpbImlkcy5zY29wZSIsIm9wZW5pZCIsInByb2ZpbGUiLCJvZmZsaW5lX2FjY2VzcyJdLCJhbXIiOlsicHdkIl19.ADZQq2R3-zJl_Bg9jOUREvrXvvmLc669iZSUZhU6oRmd6vu1UXU8VkXgxQZSk4pFxCW7j2UGuDi0jTF27e5W4PzyGWmE-qj9gE-iY9b7PSOPwYENS8rylFwB3dL7f_qlQCbzQ2kUoCoAlIPLqVbQHN76ftMoo57Ge9rg0xOw-BJT4GBKiflgE6dz8ikQhlg7_DAM-JY51Vk7bmsvny356P5Rv5cdJnBvrCCqAJeV-Y5jzUblAKx61HSZE9gBoRhYOprYgK37pw3XMqG9H5BvCr32DSufA0U91rA1sOX945yNLrYAAsDHlMO2-nmEHgOMFrnIOvzsgjnMktcxkR0NQG",
"expires_in": 43200,
"token_type": "Bearer",
"refresh_token": "F13741023427FFB7404FDE64EF485D858721D88A488763592B08CF303E721BE0",
"scope": "comm100 offline_access"
}
Refresh_token
POST /oauth/token
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
client_id |
string |
form | yes | Client ID. |
client_secret |
string |
form | yes | Client secret. |
grant_type |
string |
form | yes | The value is "refresh_token". |
refresh_token |
string |
form | yes | The refresh token. |
Response
The response is a Token object.
Example
Sample Request:
curl https://partner.comm100.io/oauth/token \
-H 'Content-Type:x-www-form-urlencoded' \
-X 'POST' \
-D 'client_id=1d29e6d7-18cf-407d-a064-e4f8c4baefab&client_secret=******&grant_type=refresh_token&refresh_token=F13741023427FFB7404FDE64EF485D858721D88A488763592B08CF303E721BE0'
Response
HTTP/1.1 200 OK
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9.eyJuYmYiOjE2NTI5NDAxODIsImV4cCI6MTY1Mjk4MzM4MiwiaXNzIjoiaHR0cDovL2ludGVybmFscGFydG5lci50ZXN0aW5nLmNvbW0xMDBkZXYuaW8iLCJhdWQiOiJpZHMucmVzb3VyY2UuMSIsImNsaWVudF9pZCI6ImRhdGFzeW5jIDEwMDAwIiwic3ViIjoiYmZlYjQ1ZDctNTBkYy00MTZkLWIzYzgtMzVkYjY0ZDI4OGYzIiwiYXV0aF90aW1lIjoxNjUyOTQwMTc0LCJpZHAiOiJsb2NhbCIsInVzZXJJZCI6ImJmZWI0NWQ3LTUwZGMtNDE2ZC1iM2M4LTM1ZGI2NGQyODhmMyIsInBhcnRuZXJJZCI6IjEwMDAwIiwidGh1bWJwcmludCI6Ijk2MTY2Q0EzQjM0QUJGMkQwNERGOTZBMDE1QkJEREQwOUIwQTdDNTkiLCJzdWNjZXNzIjoiVHJ1ZSIsInJvbGUiOiJVc2VyIiwianRpIjoiQ0Q4QTZCNjU4QzNGODZFMzBEN0REQkZBODM2RkVEM0IiLCJpYXQiOjE2NTI5NDAxNzQsInNjb3BlIjpbImlkcy5zY29wZSIsIm9wZW5pZCIsInByb2ZpbGUiLCJvZmZsaW5lX2FjY2VzcyJdLCJhbXIiOlsicHdkIl19.zSMnpHkpVBkuIhoiTMWQxWDszPZASTffnMO8cD8xmsmkVRdGJZlRmfcvg6HWi4OR1Ik9dfFHTL-T7UNM-8c4eoHc3lbooWyITk6RJ_JvYQI1bQ-eaaAXeRuvbn9VH3IfM9cy2KYChlPd2A6Ul7W7mVXP61SSjKjioOzZmtdFAkHtZmtJo5a1b0ed6Rk9e1_7wjS2i6YVf1lcJaLD3B4KmIYJHlwAVZs6m2xDqZASaFhim9rdF1iw4Lvn0EM2p6LkE41oWRUSClrtHIEvTjNNXqyjwNd1885JTLhu8qyNM9yZDVg9j0MISYgt0p-eUVCNx6vpXy_XmkjJnv4TS2mHWW",
"expires_in": 43200,
"token_type": "Bearer",
"refresh_token": "ECC1CCF28E73B9F241D3433CC0A7D91E5CC2760F43230510A74F4F01A39BAD7F",
"scope": "comm100 offline_access"
}
User Info
The UserInfo
endpoint can be used to retrieve identity information of a user.
GET /oauth/userinfo
- Get user info
User Info JSON Format
User Info is represented as simple flat JSON objects with the following keys:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
sub |
string |
yes | no | Subject. |
auth_time |
long |
yes | no | Timestamp in seconds. |
idp |
string |
yes | no | IDP. |
agentId |
string |
yes | no | Agent ID. |
siteId |
string |
yes | no | Site ID. |
userId |
string |
yes | no | User ID. |
partnerId |
string |
yes | no | Partner ID. |
thumbprint |
string |
yes | no | Thumbprint. |
success |
bool |
yes | no | Whether success or not. |
role |
string |
yes | no | Role. |
arm |
string |
yes | no | ARM. |
Get user info
GET /oauth/userinfo
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
Authorization |
string |
header | yes | Bearer <access_token>. |
Response
The response is a User Info object.
Example
Sample Request:
curl https://partner.comm100.io/oauth/userinfo \
-H 'Authorization:Bearer <access_token>' \
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"sub": "bfeb45d7-50dc-416d-b3c8-35db64d288f3",
"auth_time": 1652940304,
"idp": "local",
"userId": "ffeb45d7-50dc-416d-b3c8-35db64d288f3",
"partnerId": "10000",
"thumbprint": "96166CA3B34ABF2D04DF96A015BBDDD09B0A7C60",
"success": "True",
"role": "User",
"amr": "pwd"
}