Overview

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 Endpoint, Revoke Token API Reference and Refresh Token Grant API Reference.
If you wish to use any third-party client libraries or if you want to write your own client then you can use our endpoints directly to authenticate users on your website or application.

This page contains detailed information about the OAuth endpoints that miniOrange exposes on its authorization servers.
For Openid Connect endpoints go to - https://developers.miniorange.com/docs/idp/api/openid-api.

Endpoints

Scopes

Scope Claims
openid Obtain an ID token in the response. The ID token will also include the iss, aud, exp, iat, and at_hash claims, along with user information.
Profile Returns claims that represent basic profile information, including firstaname, lastname, username,email etc.
email Returns the email claim, which contains the user's email address.

Pre-requisites

  • You need to create a free trial account with us (Go to https://idp.miniorange.com/signup/).
  • You should have an account on the application where you want to single sign-on.

Steps to integrate miniOrange SSO API for Oauth

OAuth 2.0 secure delegated authorization protocol works by providing Authorization code the requesting client application.
The authorization code is a temporary code that the client will exchange for an access token (and refresh token if requested).
Later client can exchange the refresh token for a new access token, if current access token is expired.
Get user info endpoint can be used to obtain user details.

Authorization Grant

Authorization Request

You need to send ​a GET request to the authorization endpoint.
Example: (https://<your-domain>/rest/openidresponse)

Create a REST service or similar on your application to handle the response from Authorization Endpoint.

[GET] https://login.xecurify.com/moas/idp/openidsso?
        client_id=​<client-id-goes-here>
        &redirect_uri=​<callback-url-goes-here>
        &scope=email/profile
        &response_type=code
        &state=<security_token>

SAMPLE REQUEST AND RESPONSE


    Sample Request:
        http://localhost:8080/moas/idp/openidsso?response_type=code&client_id=Anzjx4Sf3aVe6gg&
        redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fsampleapp%2Foidcresponse&scope=email+profile
        &state=yAwL-57K10sIIpGeVO7nR7ZAnzdsj01uGothExyVpmo&nonce=ayLpTaFf-YzqtX3Jq_lTSKJmc7AUh5ELNwoIRs1XPmc

    Sample Response:
        code: kuwbrec8_sacca
        state: yAwL-57K10sIIpGeVO7nR7ZAnzdsj01uGothExyVpmo

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

REQUEST PARAMETERS

Parameter Value
Request Type GET (browser redirect)
Request Parameter client_id (Client ID obtained from miniOrange)
redirect_uri Callback URL of your application
scope email/ profile / openid (scope of authorization or level of access)

RESPONSE PARAMETERS

Parameter Value
code you will receive a code that you have to use in exchange for the token in the next API call.
state A value to be returned in the token. The client application can use it to remember the state of its interaction with the end-user at the time of the authentication call. 
     //Import our miniOrange API(copy all the JAR files in a lib folder and add them to build path)
     //Step 1 : Make a token request using code and state parameter received on the redirect uri.

         String token = AuthServerRequest.sendTokenRequest(code, state);
     /**
     Example string token JSON :
     {"scope":"email","expires_in":3600,"token_type":"bearer",
     "access_token":"2f6fyjXdQRgVU9w"}
     **/

Getting Access Token and JWT Token

You need to make ​a POST request to the token endpoint.

[POST] https://login.xecurify.com/moas/rest/oauth/token

Headers

Name Value
Authorization Basic base64_encode(client_id + ':' + client_secret)
Content-Type application/x-www-form-urlencoded

REQUEST PARAMETERS

Parameter Value
grant_type authorization_code
client_id <client-id-goes-here>
client_secret <client-secret-goes-here>
redirect_url <callback-URL-goes-here>
code <code-received-in-step1>
scope email/ profile /openid (scope of authorization or level of access)

RESPONSE PARAMETERS

Parameter Value
access_token Valid for 1 hour and can be used to access user info or other endpoints until it is expired.
refresh_token This token can be used to request another access token if the access token is expired
id_token ​Contains user attributes and signature which you have to validate with provided public certificate.

Password Grant

Resource Owner Password Credential (ROPC) Grant:

GETTING ACCESS TOKEN

You need to make a POST request to the token endpoint.

[POST] https://login.xecurify.com/moas/rest/oauth/token                                                                            |

Headers

Name Value
Authorization Basic base64_encode(client_id + ':' + client_secret)
Content-Type application/x-www-form-urlencoded

REQUEST PARAMETERS

Parameter Value
grant_type password
client_id <client-id-goes-here>
client_secret <client-secret-goes-here>
username <username-of-end-user-goes-here>
password <password-of-end-user-goes-here>
scope email/ profile/ openid (scope of authorization or level of access)

Note: The request parameters should be in the form of www url form encoded.

RESPONSE PARAMETERS

Parameter Value
access_token Valid for 1 hour and can be used to access user info or other endpoints until it is expired.
refresh_token This token can be used to request another access token if the access token is expired
id_token ​Contains user attributes and signature which you have to validate with provided public certificate.

Client Credential Grant

Client Credentials Grant to protect API access or resource access not specific to user:

GETTING ACCESS TOKEN

You need to make a POST request to the token endpoint.

[POST] https://login.xecurify.com/moas/rest/oauth/token                                                                            |

Headers

Name Value
Authorization Basic base64_encode(client_id + ':' + client_secret)
Content-Type application/x-www-form-urlencoded

REQUEST PARAMETERS

Parameter Value
grant_type client_credentials
client_id <client-id-goes-here>
client_secret <client-secret-goes-here>
scope <optional>

RESPONSE PARAMETERS

Parameter Value
access_token Valid for 1 hour and can be used to access user info or other endpoints until it is expired.
refresh_token This token can be used to request another access token if the access token is expired

Fetching User Details From User Info Endpoint

This API can be used to fetch user profile information with access token which was assigned to the user.
A GET request is sent to user info endpoint i.e., https://login.xecurify.com/moas/rest/oauth/getuserinfo.
In response user attributes in JSON format are received.

Request

Headers

Name Value
Authorization Bearer <access-token>

Request

[GET] /api/oauth/getuserinfo

Introspection Endpoint 

This API can be used verify if a token is active or not and to which user that token is assigned to.
A POST request is sent to Introspect endpoint i.e., https://login.xecurify.com/moas/rest/oauth/introspect.
In response active status of token in JSON format are received.

You need to make a POST request to the token endpoint.

[POST] https://login.xecurify.com/moas/rest/oauth/introspect                                                                           |

Headers

Name Value
Authorization Basic base64_encode(client_id + ':' + client_secret)
Content-Type application/x-www-form-urlencoded

REQUEST PARAMETERS

Parameter Value
token Your access token or Id token
client_id <client-secret-goes-here>
client_secret <client-secret-goes-here>
token_type_hint Optional in case of access token

RESPONSE PARAMETERS

Parameter Value
active active status of token
exp expiration time of the token, represented as a Unix timestamp
client_id Client id
username Username of user

Revoking Access Token

If at any point user decides to revoke the granted access token, this can be done by sending a GET request to the Revocation endpoint.
In response either a success message or a failure message is received as shown below -

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

Exchanging Refresh Token For Access Token

The token endpoint 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.

A POST request is made to the token endpoint with 'grant_type' set to 'refresh_token'.

[POST] https://login.xecurify.com/moas/rest/oauth/token

REQUEST PARAMETERS

Parameter Value
grant_type refresh_token
refresh_token <refresh-token>

Headers

Name Value
Authorization Basic base64_encode(client_id + ':' + client_secret)

Endpoints Explained

  • Authorization Endpoint : The authorization endpoint is the only one where the end-user interacts with the OpenID Connect provider. The other endpoints are meant for handling direct back - channel requests from the client application.

  • Token Endpoint : The token endpoint authenticates the client application and lets it exchange the code received from the authorization endpoint for an access token.

  • User info Endpoint : The endpoint is used to obtain end user details. User attributes in JSON format are received in response.

  • Introspection Endpoint : It verifies if a token is active or not and to which user that token is assigned to.

  • Discovery Endpoint : Contains URL and information of all the endpoints mentioned above, including a path to JSON JWK set.

  • Revocation Endpoint : The endpoint is used to revoke the granted access token. It invalidates the access token.

  • SLO Endpoint : On user logout event from client application send BROWSER REDIRECT to OpenID connect single logout endpoint.