High-level SSO flow

Customers may prefer to use their own identity providers (IDP) for end-user authentication. In this case, end-users initiate the login process via an external provider. A successful login returns a token, then this token is communicated to NET2GRID which is then responsible to communicate this token to the external provider via an introspection endpoint so that it verifies its validity, and gets any info contained within.

After this exchange the end-user is authenticated within the CE-API.

The flow that should be followed to register an end user that will login via SSO is described in the flow below:

The prerequisites that need to be covered for an end-user to be registered and authenticated using SSO are:

1. The "external_authentication_provider_id" to have been properly specified while provisioning the account of the end user via Account Management API.
2. The customer's IDP to have been configured in order to return the "external_authentication_provider_id" in the JSON response of the introspection call (More info in Authentication using single sign-on and token introspection section).

Prerequisites on IDP

The introspection endpoint that is expected to be present on the customer’s IDP side should have the following specifications that can be considered a variation of the OAuth2.0 Token Introspection Endpoint specifications:

• Should be a POST call
• Using TLS (HTTPS)
• With a header of content type application/x-www-form-urlencoded that contains the following query data in URL-encoded format
  • token
  • token_type_hint = access_token
  • client_id
  • client_secret
• With a response in JSON format that should contain:
  • active property
  • the external_authentication_provider_id in a location of the response

The customer's IDP should be able to respond to the following request:

curl --location --request POST 'https://<introspection_url>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=<ACCESS_TOKEN>' \
--data-urlencode 'token_type_hint=access_token' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>

The customer's IDP should respond similar to the following response:

{
   "active": true,
   "account_id": "<external_authentication_provider_id>"
}

Authentication

Applications that want to authenticate to the CE-API using introspection should log in to their IDP first. Then the Exchange external's provider token with a NET2GRID token through introspection. endpoint of CE-API should be triggered for the end user to be authenticated:

POST /v2/sso/exchange-token
Authorization: API-key

📘

The API key that should be used to execute the call will be provided to the customer once the dedicated instance of the NET2GRID Insight Platform has been setup and/or when a new labelpartner is added in the platform.

with a request body containing the token of their IDP that should be used for introspection in the external_provider_access_token field.

A successful response of the call would return a response similar to:

{
    "accessToken": "<ACCESS_TOKEN>",
    "refreshToken": "<REFRESH_TOKEN>",
    "idToken": "<ID_TOKEN>",
    "expiresIn": 3600,
    "tokenType": "Bearer",
    "scope": []
}