OpenID Connect and OAuth 2.0 API References

miniOrange provides OAuth 2.0 and OpenID Connect compliant API’s which can be integrated with your Web and Mobile applications. This document contains detailed information about the OAuth 2.0 and OpenID Connect endpoints/API’s that miniOrange exposes on it.

API References:
  1. OpenID Connect Integration API's
  2. OAuth 2.0 Integration API's
  3. User Management API's

OpenID Connect Integration API's

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. OpenID Connect allows easy integration with applications of all types including Web, Mobile, and JavaScript applications to request information about authenticated user sessions from IdP. OpenID is more suitable for native and mobile applications and also support robust signing and encryption with JWT tokens. Given below are some highlighting security scenario that OpenID follows while doing miniOrange OpenID Connect Integration.

 

A. Authorization for OpenID Connect Integration:

This API helps you obtaining the code parameter after the user authenticates with the account credentials using authorization grant.

API Endpoint: https://login.xecurify.com/moas/idp/openidsso

Request Type:  GET (browser redirect)

Request Parameters:  client_id: Client ID obtained from miniOrange

redirect_uri: Callback URL of your application

scope: openid

response_type: code

state: Security Token which will be sent back in response for verification at your client application

Response:

You will be redirected to OpenID callback endpoint with generated code parameter and state parameter from the request.  

B. TOKEN API for OpenID Connect Integration:

This API can be used to obtain OpenID Connect JSON Web Token (JWT) in exchange of code parameter received in the above step.

API Endpoint: https://login.xecurify.com/moas/rest/oauth/token

Request Type: POST

Request parameters: grant_type: authorization_code

client_id: Client ID obtained from miniOrange

client_secret: Client Secret obtained from miniOrange

redirect_uri: Callback URL of your application

code: Code parameter received in the Authorization request above

Response:

id_token: Contains user attributes and signature in JSON Web Tokens (JWT) format which you have to validate with provided public certificate.  

C. Verify JWT token and parse user details for SSO:

On your Callback endpoint, you can read and parse the JWT token. Structure of JSON Web Token (JWT):  JSON Web Tokens consist of three parts separated by dots (.), which are:
  • Header: Contains signature algorithm name used to sign the payload
  • Payload: Contains user attributes
  • Signature: Signature value of the payload
e.g  xxxx.yyyyyyyyyyyy.zzzzzz You will need to download a certificate from App > Manage Apps, and clicking Certificate link against your configured application. This certificate will be used for signature validation of JWT response.

OAuth 2.0 Integration API's

Given below are the security scenarios supported by miniOrange for  OAuth 2.0 Integration. The OAuth 2.0 authorization enables a third-party application to obtain limited access to miniOrange resources. This page gives an overview of the OAuth 2.0 authorization scenarios that miniOrange supports. It mainly includes Authorization, Token API, Get user info End point,  Revoke Token API Reference  and Refresh Token Grant API Reference.  

A. Authorization for OAuth 2.0 Integration:

This API helps you obtaining the code parameter after the user authenticates with the account credentials using OAuth 2.0 authorization grant.

API Endpoint: https://login.xecurify.com/moas/idp/openidsso

Request Type:  GET (browser redirect)

Request Parameters: 

client_id: Client ID obtained from miniOrange

redirect_uri: Callback URL of your application

scope: profile or email

response_type: code

state: Security Token which will be sent back in response for verification at your client application

Response: You will be redirected to OAuth callback end point with generated code parameter and state parameter from the request.  

B. TOKEN API for OAuth 2.0 Integration:

This API can be used to obtain OAuth 2.0 Access Token in exchange of code parameter received in the above step.

API Endpoint: https://login.xecurify.com/moas/rest/oauth/token

Request Type: POST

Request parameters:

grant_type: authorization_code

client_id: Client ID obtained from miniOrange

client_secret: Client Secret obtained from miniOrange

redirect_uri: Callback URL of your application

code: Code parameter received in the Authorization request above

Response:

access_token: Valid for 1 hour and can be used to access user info or other endpoints until it is expired.

id_token (If requested): Contains user attributes and signature which you have to validate with provided public certificate.  

C. GET USER INFO ENDPOINT

This API can be used to fetch updated profile information with access token which was assigned to the user.

API Endpoint: https://login.xecurify.com/moas/rest/oauth/getuserinfo

Request Type: GET

Request headers:

Authorization: Bearer <access-token-value>

Response:

User attributes JSON format    

D.REVOKE TOKEN API Reference:

This API invalidates the access token. API Endpoint: https://login.xecurify.com/moas/rest/oauth/revoke

Request Type: GET

Request headers:

Authorization: Bearer <access-token-value>

Sample Response:

{"message":"Token has been revoked successfully.","status":"SUCCESS"} {"message":"Access token is either invalid or expired.","status":"FAILED"}  

E.REFRESH TOKEN GRANT API Reference:

The Refresh Token grant type is used by clients to exchange a refresh token for an access token when the access token has expired. This allows clients to continue to have a valid access token without further interaction with the user. This API returns access token or JWT token which is valid for 1 hour and can be used for other API access.

API Endpoint: https://login.xecurify.com/moas/rest/oauth/token

Request Type: POST

Request headers:

Authorization: Basic Base64ValueOf(CLIENT_ID+”:”+CLIENT_SECRET)

Request parameters:

grant_type: refresh_token

refresh_token: Refresh token received in TOKEN endpoint request

Sample Response: {"access_token":"","token_type":"Bearer","expires_in":3600, “id_token” : ””} access_token: Valid for 1 hour and can be used to access user info or other endpoints until it is expired. id_token: JWT token

User Management API's

If you need to manage user, by using User Mangaement API's then you are at a right place. You need to follow  multiple operations  accordingly like CREATE, READ, UPDATE, DELETE with miniOrange OAuth 2.0 user management API's.  

User Management API's

A. CREATE USER

This API can be used to do user registrations from the web or mobile applications. You should send request body parameters in JSON format.

API Endpoint: https://login.xecurify.com/moas/rest/oauth/users/register

Request Type: POST

Request headers:

Authorization: Basic Base64ValueOf(CLIENT_ID+”:”+CLIENT_SECRET)

Content-Type: application/json

Request Body (JSON format): { "customerKey" : "1", "email" : "<user-email>", "phone" : "<mobile-number-with-country-code>", "firstName" : "<first-name>", "lastName" : "<last-name>", “password” : “<password>”, 'customAttribute1' => ' ', // Optional 'customAttribute2' => ' ', // Optional }

Sample Response: {"Status":"SUCCESS","txId":"f24beffc-8d6b-11e8-913b-40b03405cc4f","action":"SMS","messag e":"OTP has been sent to xxxxxxxxxxx42. Please verify your phone with OTP you received."} {"status":"FAILED","message":"User already exists with this email."}  

B. VERIFY USER with One Time Password:

You can verify the identity of the user by sending an OTP either on Phone or Email.

API Endpoint: https://login.xecurify.com/moas/rest/oauth/users/activate

Request Type: POST

Request headers:

Authorization: Basic Base64ValueOf(CLIENT_ID+”:”+CLIENT_SECRET)

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

Request Parameters: txId: Received from step (a) above otp: One time password received on mobile number

Sample Response: {"Status":"FAILED","txId":"f24beffc-8d6b-11e8-913b-40b03405cc4f","message":"Invalid One Time Passcode provided."} {"Status":"SUCCESS","message":"User account is activated."}  

C.RESEND OTP

In case you have not received an OTP with step (b), you can call resend OTP.

API Endpoint: https://login.xecurify.com/moas/rest/oauth/users/register/resendotp

Request Type: POST

Request headers:

Authorization: Basic Base64ValueOf(CLIENT_ID+”:”+CLIENT_SECRET)

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

Request Parameters:

txId: Received from step (a) above

Response: {"txId":"207f2ad0-da94-11e8-a05f-02b039385610","action":"SMS","message":"OTP has been sent to xxxxxxxxxxx42. Please verify your phone with OTP you received.","status":"SUCCESS"}