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.

This is a feature only available at the Enterprise plan.

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.