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:
- OpenID Connect Integration API's
- OAuth 2.0 Integration API's
- 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"}
