UniSignIn OAuth2 Authorization Server

Overview

UniSignIn OAuth2 Server is a standards-compliant implementation of an OAuth 2.0 authorization server. You can use UniSignIn as an OAuth2 identity provider and connect with multiple applications/clients to implement SSO.

UniSignIn OAuth2 Server

UniSignIn OAuth2 Service can be used for authorization for third party websites and applications under the same organization or used for third-party applications to access the data of users. You can create and register an OAuth App under the organization of your account.

UniSignIn's OAuth implementation supports the standard authorization code grant type.

Register a new OAuth2 application at UniSignIn Dashboard

Before creating a new OAuth2 client at UniSignIn, you need the following information:

• Redirect URIs

Redirect URIs are the Authorization callback URLs of your application.

OAuth2 servers will redirect users to a URL after they have authenticated. The URL is provided by the client and should be included in the Redirect URIs whitelist.

You can enable and set up the OAuth2 Server at Features > OAuth Service within your UniSignIn Dashboard. Once you have set up a new application or client you will get the following information:

• Client Name
• Client ID
• Client Secret
• Redirect URIs

Web application flow

The web application flow to authorize users for your app is:

• Users are redirected to request their identity at UniSignIn
• Users are redirected back to your app by UniSignIn
• Your app accesses the API with the user's access token

Authorization Steps

1. Request a user's UniSignIn identity

To begin the process, your application should send the initial authorization request to the Oauth2 server:

GET https://SUBDOMAIN.PRIMARY_DOMAIN/oauth/v2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=public&state=STATE_CODE

• SUBDOMAIN.PRIMARY_DOMAIN — The UniSignIn subdomain of the primary project.
• response_type — The type of the authorize request, it is code here.
• client_id — The client_id you got from UniSignIn dashboard.
• redirect_uri — The URL in your application where users are sent after authorization. It should be included in Redirect URIs.
• state — The random string for the auth session to avoid CSRF.

The state parameter is used to protect against cross-site request forgery (CSRF). The application generates a random string and sends it to the authorization server using the state parameter. The authorization server sends back the state parameter. Then the application should compare the state passed back from the OAuth2 server with the one saved at local to ensure the response can be trusted.

2. Users are redirected back to your site by UniSignIn Account Center

Once the user finished signing up or log in, the user will be redirected back to the application:

GET https://YOUR_APPLICATION_DOMAIN/redirect?code=CODE&state=STATE_TOKEN

• YOUR_APPLICATION_DOMAIN — The domain of your application.
• code — The code respond from Oauth2 server to exchange for an access_token
• state — The random string for the auth session to avoid CSRF.

The application compares the state param and use the CODE to send a POST request to UniSignIn server:

POST https://SUBDOMAIN.PRIMARY_DOMAIN/oauth/v2/access_token

• SUBDOMAIN.PRIMARY_DOMAIN — The UniSignIn subdomain of the primary project.
• client_id — The client_id you got from UniSignIn dashboard.
• grant_type — The grant type: authorization_code.
• client_secret — The client_secret you got from UniSignIn dashboard.
• code — The code you received as a response from the previous Step.

Response

The sample response:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIyIiwianRpIjoiNjVkOGM0NTVlNTMzODYzMDFjZTRmZWNiZTllZWRlMThkZDNjYjI0MGU0ZmRjMTJjYjE0Y2FlZmY0ZTM2NmRiNTg0YjAyMTgwNmU1OWM1MWEiLCJpYXQiOjE2MzIzMjU5NzguMDQ0NzU0LCJuYmYiOjE2MzIzMjU5NzguMDQ0NzU3LCJleHAiOjE2MzIzMjk1NzcuOTg3NTY5LCJzdWIiOiIxIiwic2NvcGVzIjpbXX0.Iq8FW34wu7zmfnFrdsHxG2AqwywRh56zVx1gNayQyti4FcEgUtbpgOlW702uLuStHHnX71X8uSJlYB4pZPKxGYWNVvyk8-806ZAo0jmT_6cdEC4VwTopD5JHtB80MTOSJ017bz6HBu8YZLXsMMmMQgXrQHoxsgAhanG_nhHoVZwUXjt4ol5qJ7yEkKhiFl-6lEmwXEbahf3Jw26OmR2FTgS2zJQc9qgtsTJ6YeQcWrOY57Lg2lCdrCayjC7u8PE4YkecuJdLbWFN_Fap7OquvPzFXoWDCaQxhAbbiVoLOpe-UkfhzpRKwptQC9lC88GQe3uoujtbbYbxKHWmEvZaEOf17V2mMKrhg061tgx3jr5T1oLIy8Z9MPPpHgfuTsGa5bOY2ArlK-VRrwSnGQzczI9diSgm7_iNQSZfSfoZ2EdOTiJvt3gMupsTpFK1pt8uvHvzHkQIfJJKHca3unr4g_pShDTSGeM6fNHei2YVCjruYtPhhFQon44RppB5mMn4IBQ_hVQojcMW8PHI6y5Em2FdEDY4kVsxWANo20NKspVbrhGK17SCFDYROKrIypfXAbcUxbUx_4q65Nh5EyayiURHaXmHBvVC_-GXsWKNtUULAY9hz8CwYfZrbV8Y6AuepaXePxVKtqU71FMgxeHPMc-R-0Mw8zTIdKLXfiMihwE",
  "refresh_token": "def50200ae155c1245fcb6beb7ab97e20d59a28657baa90562f7b9cc4f652d048850ecaf780b080abaf160cbb030167577777c07effa2b114314a711d87cb5ae96fe1bef8467b2610a62a354c8901239c73238865c05a480a344bd10582fc8f8389563be20733bafa0176f9de8e5bd21721c452fa7d311c82611af6519838e98501913b7368b7d15ba9c9ee7000ec9dd35ce5ed2f62d08b59a8824a00bda2649393e0e99a4abaa6562cc6677ed00d8cbb441caae70980f233e12d0f22cca941ccd2b10185da6df0d36f25c96d1cbff02b4a95ca640b73fb88d12f1d1c7372a362083b1b982e31bd31e9fb9e82dc6b81d34799cce1bb26b99c50fa93e62ad1297a1b3bd0a2325f058889d660727ee8804471ed121e7176eb5dd641eb740b041c2287cf1404339eee5a1367324be32a24615075a5c46e3b08c74eaae797a91730c8302830c68e682e2a197691f2b2b54c1cae6175e0d3ef133e1cc018b13e9e3"
}

3. Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user.

Authorization: Bearer OAUTH_TOKEN
https://SUBDOMAIN.PRIMARY_DOMAIN/oauth/v2/user?client_id=CLIENT_ID

• SUBDOMAIN.PRIMARY_DOMAIN — The UniSignIn subdomain of the primary project.
• client_id — The client_id you got from UniSignIn dashboard.
• OAUTH_TOKEN — access_token received in the previous step, send as HTTP header.

APP flow

Auth code flow

APP Flow

Prepare the redirect URL

Parepare code_verifier and code_challenge

The code_verifier and code_challenge can be the same when the code_challenge_method is plain. But it must contain only letters and numbers.

Prepare your redirect URL

You should define the URL scheme in your APP that you want Unisignin to redirect to. The URL scheme should like be <scheme>://<path>?<params>=<value>.

Create the redirect URL

You should make a URL like this:

https://SUBDOMAIN.PRIMARY_DOMAIN/oauth/v2/authorize?
    response_type=code&
    client_id=YOUR_CLIENT_ID&
    redirect_uri=YOUR_REDIRECT_URI&
    scope=public&
    code_challenge=CODE_CHALLENGE&
    code_challenge_method=plain

name	required	description
YOUR_CLIENT_ID	yes	The client ID is shown in Unisignin
YOUR_REDIRECT_URI	yes	The redirect URL to return your APP
CODE_CHALLENGE	yes	Only contains letters and numbers, and the length of it must be more than 48 and less than 128.

Open the redirect URL in your APP

Redirect to your APP with params

You can get the code from the URL scheme.

Request the access token

POST https://SUBDOMAIN.PRIMARY_DOMAIN/oauth/v2/access_token

name	required	description
client_id	yes	The client ID is shown in Unisignin.
grant_type	yes	Must be authorization_code.
code_verifier	yes	Same as code_challenge.
code	yes	From your app.
redirect_uri	yes	The redirect URL to return your APP.

Request the user profile

Authorization: Bearer OAUTH_TOKEN
GET https://SUBDOMAIN.PRIMARY_DOMAIN/oauth/v2/user?client_id=YOUR_CLIENT_ID

name	required	description
OAUTH_TOKEN	yes	access_token received in the previous step, send as HTTP header.
YOUR_CLIENT_ID	yes	The client ID is shown in Unisignin.

Finish login

Now you'll get the profile of the user.

Password flow

Request the access token

POST https://SUBDOMAIN.PRIMARY_DOMAIN/oauth/v2/access_token

name	required	description
client_id	yes	The client ID is shown in Unisignin.
grant_type	yes	Must be password.
username	yes	The email that users provide.
password	yes	The password that users provide.
scope	no	Should be public.

Request the user profile

Authorization: Bearer OAUTH_TOKEN

GET https://SUBDOMAIN.PRIMARY_DOMAIN/oauth/v2/user?client_id=YOUR_CLIENT_ID

name	required	description
OAUTH_TOKEN	yes	access_token received in the previous step, send as HTTP header.
YOUR_CLIENT_ID	yes	The client ID is shown in Unisignin.

Finish login

Now you'll get the profile of the user.