Introduction

Authentication on the platform Unico IDCloud uses the protocol OAuth2, in the model Two-Legged OAuth (2LO).

• Is done through a service account, linked to the application (not to a user).

• The application calls Unico's APIs on behalf of the service account.

• Ideal scenario for server-to-server interactions.

Service Account Request

To create the service account, send to your company's project manager:

• Name of the service account to be created (up to 12 characters);

• Name, email and mobile phone of the person responsible for the service account.

Homologation and Production require separate accounts.

After submitting the data the service account will be created and you will receive an email to generate the private key (.PEM). The service account includes:

• Unique account name.

• Tenant ID (company identifier).

• The base payload to build the JWT

• Private key (.PEM) - the browser will automatically download it at the end of the service account generation, and it will be available in your computer's downloads folder.

💡Check your SPAM folder if you cannot find the email to generate the service account.

If you need the public key, request it from the project manager or generate it via OpenSSL:

openssl req -x509 -new -nodes -sha256 -days 720 \
-key fileName.key.pem -out fileName.cert.pem

Authentication Flow

Your application must follow 4 steps:

1. Create the JWT (header + payload + signature).

2. Request the access token (access-token) on the authentication platform.

3. Handle the response (store and use the access-token in API calls).

4. Validity of the access token.

1. Creating the JWT

Note: jwt.io can be used to visualize JWT content for learning or debugging. It should not be used as part of production workflows

1.1 Structure

A JWT has 3 parts concatenated by .:

{Header Base64url}.{Payload Base64url}.{Signature Base64url}

1.2 Header

{"alg":"RS256","typ":"JWT"}

Base64url:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

1.3 Payload

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "iat": 1626293376,
  "exp": 1626296976
}

Field	Description
iss	Identifier of the service account (Service Account). The pattern is: account name + @ + Tenant ID + iam.acesso.io. (ex: "service_account_name@tenant_id.iam.acesso.io").
scope	Requested permissions. Use "*" for all.
aud	Always https://identityhomolog.acesso.io (⚠️ no trailing slash and always with HTTPS).
iat	Time of JWT issuance, in seconds (in Unix Timestamp format).
exp	Token expiration in seconds (max. +3600s in relation to the iat). This value cannot be fixed and has a maximum time of 1 hour after the JWT issuance time.

Example calculation:

exp = iat + 3600

1.4 Signature

• Algorithm: RS256 (RSA + SHA-256).

• Input: {Header Base64url}.{Payload Base64url}.

• Signature made with the private key (.key.pem).

• Final result:

{Header Base64url}.{Payload Base64url}.{Signature Base64url}

Below is an example of a JWT token before Base64url encoding:

{"alg":"RS256","typ":"JWT"}.
{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, // This is just an example. Use the current generated value here.
  "iat": 1626293376 // This is just an example. Use the current generated value here.
}.
[byte array of the signature]

2. Requesting the Access Token

Send the signed JWT to the platform:

POST Endpoint:

• UAT: https://identityhomolog.acesso.io/oauth2/token;

• PROD: https://identity.acesso.io/oauth2/token.

Headers:

Content-Type: application/x-www-form-urlencoded

Body:

Name	Description
grant_type	Use the following text, URL-encoded if necessary: urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion	The JWT, including the signature.

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
assertion=<signed_JWT>

Request example:

POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-
bearer &
assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY
291bnRfbmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsInN1YiI6InVzZXJfaWRlbnRpZmllciIs
ImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb3BlIjoiKiIsImV4cCI
6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.TjH-mTtwP6tBB93O1sDPaAA6yUF7N2-HZDlpIPz
bf_dxO8A6KZuRWG8ZnICrxX56qj0HREiMlYy27XJgxowrUa0JHvbqc8HJkT7-6Mh7J67UnubZKG1-hi
6jDtkC9BIXBcOhtkNUfZvZetXjLzsRsSDkqxdMtzYZwkRlocvaxL5QXiQhweeEwK_Ux81Adh3z0EIhT
yl7CKJLJ69PuHS7s9IdrjUl79owipp4LF1FvtMhoe7YIL69ohPgFqSv_-Y9qpPdW6be3OEAyKlOM08S
ZBbHBwW4XMvw3uZjTY1sgJ4cBoxrftDpjYOw34oPOKxirqc5-90uOCYe1O1hRtG45w

3. Handling the Response

Example response from the platform:

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "3600"
}

• Use the access_token in all calls to Unico's APIs.

• If an error is returned, validate:

  • JWT properly formed.

  • Time set in the iat and exp;

  • Service account with necessary permissions.

4. Validity of the Access Token

• The time is reported in expires_in (seconds).

• Default: 3600s (1 hour).

• Renew the token when there are 10 minutes left to expire.

Examples:

Default scenario:
expires_in: 3600 (1h) - Token generation at 14:42

Request a new token only at 15:32, that is, 14:42 + (3600 - 600)

A new access token can be requested when there are 10 minutes left to expire.

• ¹ According to RFC 4648 on BaseN encoding, the Base64url format is similar to Base64 format, except for the character = which must be omitted, and the characters + and / which must be replaced by - and _, respectively.

• ² JSON Web Signature: https://tools.ietf.org/html/rfc7515.