Unico IDCloud - DevCenter
HomepageAuthenticationAPIsSDKs
English (United States)
English (United States)
  • Welcome
  • GETTING STARTED
    • Unico IDCloud
    • Capabilities
    • Integration Methods
    • Capabilities and Integration Methods
  • INTEGRATIONS
    • Quickstart
    • Authentication
      • Creating a Service Account
      • Preparing to Make an Authenticated API Request
      • Additional Resources
        • Example in Javascript
        • Authentication Errors
        • Postman Collection
    • Integration by Unico
      • Overview
      • API
        • API Reference
          • CreateProcess
            • CreateProcess separated by flows
          • GetProcess
          • GetSelfie
          • GetEvidenceSet
            • Specification of the evidential set
          • GetDocumentSigned
          • GetEvidenceSign
        • Errors
      • Controlling the experience
        • Redirecting the user
        • SDK
        • QR Code
        • Customizations
      • Additional Resources
        • Postman Collection
        • PoCs available
    • Integration by Client
      • Overview
      • API
        • API Reference
          • Liveness + Identity Verification + Behavior Alert
          • Liveness + Identity Verification + Behavior Alert + Risk Score
          • Liveness + Validation (1:1) + Behavior Alert
          • Document Capture and Reuse
        • Response Scenarios
        • Additional Resources
          • Postman Collection
      • Capture standard (without SDK)
    • Webhook
    • SDK
      • Overview
      • Update Policy
      • SDK Integration
        • Android SDK
          • Installation Guide
          • Usage and Integration Guide
            • Selfie Capture
            • Document Capture
          • Error Handling Guide
          • Android Customization
          • Troubleshooting
          • Release notes
        • iOS SDK
          • Installation Guide
          • Usage and Integration Guide
            • Selfie Capture
            • Document Capture
          • Error Handling Guide
          • iOS Customization
          • Troubleshooting
          • Release notes
        • Flutter SDK
          • Installation Guide
          • Usage and Integration Guide
            • Selfie Capture
            • Document Capture
          • Error Handling Guide
          • Flutter Customization
          • Troubleshooting
          • Release notes
        • Web SDK
          • Installation Guide
          • Usage and Integration Guide
            • Selfie Capture
            • Document Capture
            • Accessibility
          • Error Handling Guide
          • Web Customization
          • Release notes
      • Additional Resources
        • Available PoCs
        • Best Practices for SDK Implementation
  • help & faq
    • Glossary
    • Help Center
Powered by GitBook

Institucional

  • Sobre nós

Copyright © 2024 unico. All rights reserved

On this page
  • 1 - Creating the JWT
  • 1.1 - Forming the JWT Header
  • 1.2 - Forming the JWT Payload
  • 1.3 - Required Fields
  • 1.4 - Calculating the Signature
  • 2 - Making a Request for an Access Token
  • 3 - Handling the response from the authentication platform​
  • 4 - The duration of the access token

Was this helpful?

Export as PDF
  1. INTEGRATIONS
  2. Authentication

Preparing to Make an Authenticated API Request

In this section, you’ll find instructions on how to complete the authentication process on the Unico IDCloud platform

PreviousCreating a Service AccountNextAdditional Resources

Last updated 17 days ago

Was this helpful?


After creating and configuring a service account, your application needs to complete the following steps:

  1. Create a JSON Web Token (JWT), which includes the header, payload, and signature.

  2. Request an Access Token from the OAuth2 authentication platform.

  3. Process the JSON response returned by the authentication platform.

If the response includes an access token, you can use it to make requests to Unico product APIs for which the service account has access permissions. (If the response does not include an access token, your JWT or token request may be incorrect, or the service account might lack the necessary permissions to access the requested resources.)

The access token generated in the above request has a default validity of 3600 seconds, but this may vary based on the security configuration set for your company. When the access token expires, your application must generate a new JWT, sign it, and request a new access token from the authentication platform.

1 - Creating the JWT


A JWT (JSON Web Token) consists of three parts: a header, a payload, and a signature. The header and payload are JSON objects, which are serialized in UTF-8 and then encoded using Base64url encoding. This encoding ensures resilience against modifications due to repeated encoding operations. The header, payload, and signature are concatenated using a period (.) separator.

A JWT is structured as follows:

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

The base text for the signature is formed in the following way:

{Header in Base64url}.{Payload em Base64url}

1.1 - Forming the JWT Header


The header consists of two fields that specify the signing algorithm and the token format. Both fields are mandatory, and each field has only one value. Service accounts rely on the RSA SHA-256 algorithm and the JWT token format.

As a result, the JSON representation of the header is as follows:

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

The Base64url representation is as follows:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

This ensures that both header and payload are properly encoded before signing, which is crucial for secure authentication.

1.2 - Forming the JWT Payload


The JWT payload contains information about the JWT, including the requested permissions (scopes), the account requesting access, the issuer, the time the token was issued, and the token's lifespan. Most fields are mandatory. Like the JWT header, the payload is a JSON object and is used in the composition of the signature.

1.3 - Required Fields


The required fields in the JWT are shown in the table below. They can appear in any order within the payload.

Name
Description

iss

The identifier of the service account within the company.

scope

A space-delimited list or a list separated by the plus sign (+) of the permissions that the application is requesting. If all permissions of the account are required, use the asterisk sign (*) for that purpose.

aud

exp

The expiration time of the token, specified in seconds since 00:00:00 UTC, January 1, 1970. This value has a maximum time of 1 hour after the moment of issuing the JWT. This value must be numeric. Common cases that DO NOT work:

  • Using quotes to delimit the value. For example: “1524161193” is a string and will not work. However, 1524161193 is a number and will work.

iat

The moment of issuing the JWT, specified in seconds since 00:00:00 UTC, January 1, 1970. This value must be numeric.

  • Using quotes to delimit the value. For example: “1524161193” is a string and will not work. However, 1524161193 is a number and will work.

Understand how the conversion works for the issuance (iat) and expiration (exp) fields of the JWT, and also see examples of how to use the values of these fields here. Additionally, the "iat" field should reflect the current time in the required format, and the "exp" field must adhere to the calculation below:

exp = iat + 3600

The representation of the mandatory JSON fields in the JWT payload is as follows:

{
  "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 value generated here.
  "iat": 1626293376 //This is just an example. Use the current value generated here.
}

1.4 - Calculating the Signature


The JSON Web Signature (JWS) specification is the mechanism that guides the calculation of the signature for a JWT. The input content for the signature calculation is the byte array of the following content:

{Header in Base64url}.{Payload in Base64url}

The same algorithm specified in the header of the JWT must be used for the signature calculation. The only signature algorithm supported by the OAuth2 authentication platform is RSA using SHA-256. It is expressed as RS256 in the alg field of the JWT header.

Sign the UTF-8 representation of the input content using SHA256withRSA (also known as RSASSA-PKCS1-V1_5-SIGN with SHA-256 hash) with the private key that was created and associated with the service account (the .key.pem file generated from the request received by email). The output content will be a byte array.

The signature must then be encoded in Base64url. The header, payload, and signature must be concatenated with a period (.). The result is the JWT. It should be in the following format: {Header in Base64url}.{Payload in Base64url}.{Signature in Base64url} Below is an example of a JWT token before Base64url encoding:

{Header in Base64url}.{Payload in Base64url}.{Signature in 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 value generated here.
  "iat": 1626293376 //This is just an example. Use the current value generated here.
}.
[byte array from signature]

Below is an example of the JWT that has been signed and is ready for transmission:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY291bnRf
bmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb
3BlIjoiKiIsImV4cCI6MTYyNjI5Njk3NiwiaWF0IjoxNjI2MjkzMzc2fQ.JsymP3NZdgCSqeNlgsOM2
-AQ7M450NxFnZnnaKSu4Q8g12QGEIvvM4EhCokUHfwk5s7pOpm2UD_Ng3Hb5g_wgrjfiVSLWH5Q2wYg1AvfLqo
YSoJWaMHm9KL0kpv32XdDD8TZVR-MVd2VBHmCMVbV6gvk8buUoK1HZDN7g84PaY3bfgcB3RKU-
H55lR8yyJjZxToIv17-wfla2G99uaMEFNGX0ZSE7ETn5Z8-WypmFrNAK0TM58upzvfVI6_-
gY4cj4iQvmRbuvxsAaGiHA2xd0RVm2Mrx-gQtdPqtbZPuQcH7k64Z_EOQBgiGTgVjucyHD6zBijr_P-
2mhIxuecNSw

2 - Making a Request for an Access Token


After generating the signed JWT, an application can use it to request an access token. The access token request is a POST HTTPS request, and the body must be URL encoded. The URL is as follows:

https://identityhomolog.acesso.io/oauth2/token

The parameters below are mandatory in the request:

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.

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


If the JWT and the access token request were properly formed and the service account has the necessary permissions, then the response from the authentication platform returns a JSON object containing an access token. Here’s an example of a response from the platform:

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

4 - The duration of the access token


The duration of the access token is variable. Its duration is specified in the "expires_in" field, returned along with the access token. The same access token should be used during its validity for all calls to the product APIs.

Do not request a new access token until the validity of the current token is nearing its end. We recommend a margin of 600 seconds (10 minutes). To do this, perform the calculation:

decoded token:
new Date(token.exp - 600)

Where token.exp is the timestamp of the token's expiration.

By default, the token sent to the company is valid for 1 hour, but this can be changed. It is recommended to always use the expires_in as a reference and subtract 600 seconds from it to request a new token.

Examples:

Standard scenario:
expires_in: 3600 (1h) - Token generation at 2:42 PM

Request a new token only at 3:32, that is, 2:42 + (3600 - 600)
Scenario with altered duration:
expires_in: 7200 (2h) - Token generation at 2:42 PM

Request a new token only at 4:32, that is, 2:42 + (7200 - 600)

A new access token can be requested when there are 10 minutes left until expiration.

Do not use a fixed time to obtain a new token, as the duration of the received token may be shorter than the established time, which will result in service usage failures.

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


Address of the authentication platform that issues access tokens. This value must always and exactly be Common cases that DO NOT work:

Inserting a trailing slash at the end of the address:

Using the HTTP protocol instead of HTTPS:

It is also possible to use pre-established libraries to create the JWT. As a reference, you can find a list of libraries on the website.

3 - Handling the response from the authentication platform

The access token returned in the “access_token” field of the JSON object is also a JWT that should be used for the APIs of Unico’s products. If an error occurs in the request, you can check the type of error in the error table by clicking .

² JSON Web Signature: .

Still need help?

Didn't find something or still need help? If you're already a client or partner, you can reach out through our .

jwt.io
​
here
https://tools.ietf.org/html/rfc7515
​
Help Center
https://identityhomolog.acesso.io
https://identityhomolog.acesso.io/
http://identityhomolog.acesso.io