To use IDPay, it is necessary to authenticate via access token, using the OAuth2 authentication system.

Unico's OAuth2 authentication system supports server-to-server interaction between a web application and Unico's services.

For this scenario, you will need a service account, which is a non-personal account that belongs to your application and not to an individual user. Your application calls Unico's APIs on behalf of the service account, so users are not directly involved. This scenario is called 'two-legged OAuth' or '2LO'. Typically, an application uses a service account when the application calls Unico's APIs to work with its own data rather than user data.

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 Help Center.

const fs = require('fs')
const path = require('path')
const jwt = require('jsonwebtoken')
const request = require('request')

// settings
const basePath = 'https://identityhomolog.acesso.io'

// entry point
let options = {
    serviceAccount: 'svcapp1',
    tenant: "9ea3c3bd-4447-4c3b-ae2e-504b795d3733"
}

requestAnAccessToken(createServiceAccountToken(options), (err, accessToken) => {
    let payload = jwt.decode(accessToken.access_token)
    console.log('Response:')
    console.log(' Access Token: ', accessToken.access_token)
    console.log(' ID: ', payload.jti)
    console.log(' Issuer: ', payload.iss)
    console.log(' Subject: ', payload.sub)
    console.log(' expires_in: ', accessToken.expires_in)
    console.log(' Expiration Date: ', new Date(payload.exp))
    console.log(' Creation Date: ', new Date(payload.iat))
})

// functions
function createServiceAccountToken({tenant, serviceAccount, account = ''}) {
    // Reads the service account private key
    let privateKey = fs.readFileSync(path.resolve(`${serviceAccount}.key.pem`))

    // Prepare the request
    let payload = {
        iss: `${serviceAccount}@${tenant}.iam.acesso.io`,
        aud: basePath,
        scope: '*',
        exp: Math.floor(Date.now() / 1000) + 3600,
        iat: Math.floor(Date.now() / 1000)
    }
    // Service account is requesting an access token for another user?
    if (account) {
        payload.sub = account
    }

    // Create JWS
    return jwt.sign(payload, privateKey, { algorithm: 'RS256' })
}

function requestAnAccessToken(serviceToken, callback) {
    // Prepare the request
    let options = {
        method: 'POST',
        url: `${basePath}/oauth2/token`,
        headers: {'content-type': 'application/x-www-form-urlencoded'},
        form: {
            grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer' ,
            assertion: serviceToken
        }
    }
    console.log('Requesting Access Token with self created token:' )
    console.log('', serviceToken)

    // Ask identity and authorization server for an access token
    request(options, (error, response, body) => {
        if (error) {
            callback(new Error(error))
        }

        body = JSON.parse(body)

        if (body.error) {
            callback(new Error(`${body.error}: ${body.error_description}`))
        }

        callback(null, body)
    })
}

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 Help Center.

The errors returned in the request can be identified by the codes below and have the following structure:

{
  "error": "server_error",
  "error_description": "Falha na autenticação x.x.x"
}

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 Help Center.

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 (AccessToken) from the OAuth2 authentication platform;

3. Handle the JSON response that the authentication platform will return.

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

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

1 - Creating the JWT

A JWT consists of three parts: a header, a payload, and a signature. The header and payload are JSON objects. These JSON objects are serialized in UTF-8 and then encoded using Base64url encoding¹. This encoding provides resilience against encoding changes in cases of repeated encoding operations. The header, payload, and signature are concatenated with a period (.) character.

A JWT is composed as follows:

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

The base text for the signature is composed as follows:

{Header in Base64url}.{Payload in 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

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 when the token was issued, and the token's lifetime. Most fields are mandatory. Just like the JWT header, the payload is a JSON object and is used in the composition of the signature.

1.3 - Mandatory Fields

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

Understand how the conversion works for the issuance (iat) and expiration (exp) fields of the JWT, and also see examples of how to use these field values here. In addition, the 'iat' field must represent the current time in the required format, and the 'exp' field must respect the following calculation:

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 JWT header must be used for calculating the signature. 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 the 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 then needs to be encoded in Base64url. The header, payload, and signature should be concatenated with a period character. The result is the JWT. It should be as follows:

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

Here 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 da assinatura]

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

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 jwt.io website.

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 should be URL encoded. The URL is shown below:

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

The following parameters are mandatory in the POST HTTPS request:

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 Authentication Platform's Response

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

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

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

4 - Duration of the Access Token

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

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 following calculation:

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

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

Examples:

Standard scenario:
expires_in: 3600 (1h) - Token generated at 14:42

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

Scenario with modified duration:
expires_in: 7200 (2h) - Token generated at 14:42

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

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

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

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

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 Help Center.

Download the file below, import it into Postman, and replace the values of the parameters "service_account", "tenant_id", and "secret_key" to test the call.

To use server-to-server interactions, you need to request the creation of a service account by contacting the project manager responsible for your company and sending the following information: company name, application name, name, email, and phone number of the person responsible for the application within the company. Separate accounts must be created for the Testing and Production environments.

Once these details are received, a service account will be created to authenticate your application, and we will send an email for you to generate the key pair for the account.

A service account credential includes a unique account name, a company identifier (Tenant ID), and at least one key pair (public and private). After generating the keys, you will only receive the private key (file .key.pem), as well as the payload that should be used to create the JWT. This payload will have the following format:

If you need the public key to configure it in your system, please contact the project manager responsible for your account. It is also possible to generate a public key using the following openssl command:

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

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 Help Center.