Authenticating users

Suggest Edits

NET2GRID uses OAuth 2.0 for authorization to its CE-API. OAuth 2.0 is the industry-standard protocol for authorization, focusing on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.

Authenticating users with username/password

CE-API provides the Requests token for a user. endpoint to obtain the access and refresh tokens to be used for calls to API endpoints. To authenticate with the CE-API an end-user must supply a username, password, client_id and client_secret to the /token endpoint to obtain an access token (access_token) and refresh token (refresh_token). Once authenticated the access token can be used for calls to API endpoints. The access token is short-lived (1 hour).

📘

The client_id and client_secret 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.

An example call in cURL format is described below:

curl --location --request POST '<CE_API_BASE_URL>/v2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'username=<EMAIL_ADDRESS>' \
--data-urlencode 'password=<PASSWORD>' \
--data-urlencode 'grant_type=password'

The response of the token call will be like:

{
    "access_token": "<ACCESS_TOKEN>",
    "refresh_token": "<REFRESH_TOKEN>",
    "id_token": "<ID_TOKEN>",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": []
}

🚧

It is important that applications do not store the username and password for end-users, but instead rely on the refresh token flow to renew access tokens once they're no longer valid.

When a new access token is needed, the application can make a POST request back to the token endpoint using a grant type of refresh_token to request a new access token. Refresh tokens are much longer lived, usually configured to expire in 30 days.

An example call in cURL format is described below:

curl --location --request POST '<CE_API_BASE_URL>/v2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'refresh_token=<REFRESH_TOKEN>' \
--data-urlencode 'grant_type=refresh_token'

And the response will be similar to the above

The response of the token call will be like:

{
    "access_token": "<ACCESS_TOKEN>",
    "refresh_token": "<REFRESH_TOKEN>",
    "id_token": "<ID_TOKEN>",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": []
}

MFA

The CE-API also supports Multi Factor Authentication (MFA). MFA requires end-users to also provide a Time-based One-Time Password (TOTP) during the authentication flow, after the initial combination of username and password is correct. NET2GRID supports TOTP tokens retrieved from authenticator apps like (Google Authenticator, Twilio, LastPass etc). This flow provides an extra security layer on top of the username and password as it is actually a two step authentication.

Enable MFA

To enable MFA, end-users should start by triggering /mfa/enable to initiate the MFA process.

This endpoint returns a secret code that can then be displayed by an app as text or translated into a QR code:

{
  "status": "ok",
  "data": {
    "secret_code": "5G5CNH5AFODUNIUKXA7MXAO7S5LXJPFDG5PMPOJLMCXL6LZ2HSXQ"
  }
}

In order to finish MFA setup, end-users verify the TOTP token that is generated on the authenticator app via /mfa/verify-software-token providing the access token and the TOTP token. If the correct TOTP token is given, then MFA setup is complete. From now on, end-users should provide their TOTP token to complete their login.

Disable MFA

MFA can be disabled at any time by using /mfa/disable.

Reset password

In order to reset the password of a user CE-API provides the /registration/resetpassword endpoint that will send an email to the end user containing a URL that will be used to set their new password. 

POST /v2/registration/resetpassword/<EMAIL_ADDRESS>

Change password

If the end-user knows their current password and wants to update it, CE-API provides the Updates the password for a user. endpoint that can be used as follows giving both the old and the new password as input:

PUT /v2/registration/setpassword
Authorization: Bearer <access_token>

Authentication using single sign-on and token introspection

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.

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>"
}

Authenticate user

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": []
}

Updated 7 days ago

What’s Next