Para utilizar interações server-to-server, é preciso solicitar a criação da conta de serviço com o gerente de projetos responsável pela sua empresa enviando os seguintes dados: nome da empresa, nome da aplicação, nome, e-mail e celular do responsável pela aplicação na empresa. É preciso criar contas diferentes para os ambientes de Homologação e Produção.

Após o recebimento desses dados, será criada uma conta de serviço responsável por autenticar a sua aplicação e enviaremos um e-mail para que seja gerado o par de chaves para a conta.

Uma credencial de conta de serviço inclui um nome único de conta, um identificador da empresa (Tenant ID) e ao menos um par de chaves (pública e privada). Ao final da geração das chaves, você recebe apenas a chave privada (arquivo .key.pem), bem como o payload que deve ser utilizado para montar o JWT. Este payload terá o seguinte formato:

Caso precise da chave pública para configurar em seu sistema, contate o gerente de projetos responsável por sua conta. Também é possível gerar uma chave pública através do comando openssl a seguir:

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

Dúvidas?​

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.

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

Dúvidas?​

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.

Os erros retornados na requisição podem ser identificados através dos códigos abaixo e possuem a seguinte estrutura:

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

Dúvidas?​

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.

Para utilizar a plataforma IDCloud é necessário se autenticar via token de acesso, utilizando o sistema de autenticação conhecido como OAuth2.

O sistema de autenticação OAuth2 da unico suporta a interação server-to-server entre uma aplicação web e os serviços da unico.

Para este cenário, você precisará de uma conta de serviço, que é uma conta impessoal que pertence à sua aplicação e não a um usuário individual. Sua aplicação chama as APIs da unico em nome da conta de serviço, portanto usuários não estão diretamente envolvidos. Este cenário é chamado “two-legged OAuth”, ou “2LO”. Tipicamente, uma aplicação utiliza uma conta de serviço quando a aplicação chama as APIs da unico para trabalhar com seus próprios dados ao invés dos dados do usuário.

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da .

Após a criação e configuração de uma conta de serviço, sua aplicação precisa completar as seguintes etapas:

1. Criar um JSON Web Token (JWT), que inclui cabeçalho, payload e assinatura;

2. Requisitar um token de acesso (AccessToken) da plataforma de autenticação OAuth2;

3. Tratar a resposta JSON que a plataforma de autenticação retornará.

Se na resposta estiver incluso um token de acesso, você poderá usá-lo para fazer requisições às APIs dos produtos da unico para os quais a conta de serviço possui permissão de acesso. (Se na resposta não estiver incluso um token de acesso, seu JWT e requisição de obtenção do token podem estar incorretos ou a conta de serviço pode não ter as permissões necessárias para acessar os recursos solicitados.)

O token de acesso gerado na requisição mencionada acima tem validade padrão de 3600 segundos, podendo variar de acordo com a configuração de segurança estabelecida para sua empresa. Quando o token de acesso expirar, sua aplicação deverá gerar um novo JWT, fazer a assinatura e requisitar um novo token de acesso na plataforma de autenticação.

1 - Criando o JWT

Um JWT é composto por três partes: um cabeçalho, um payload e uma assinatura. O cabeçalho e o payload são objetos JSON. Esses objetos JSON são serializados em UTF-8 e então codificados usando codificação Base64url¹. Esta codificação provê resliência contra alterações de codificação em casos de repetidas operações de codificação. O cabeçalho, o payload e a assinatura são concatenadas com um caractere de ponto final ..

Um JWT é composto da seguinte forma:

O texto base para a assinatura é composto pela seguinte forma:

1.1 - Formando o cabeçalho JWT

O cabeçalho consiste em dois campos que indicam o algorítimo de assinatura e o formato do token. Ambos os campos são obrigatórios e cada campo possui apenas um valor. Contas de serviço dependem do algorítimo RSA SHA-256 e do formato de token JWT. Como resultado, a representação JSON do cabeçalho se dá da seguinte forma:

A representação em Base64url se dá da seguinte forma:

1.2 - Formando o payload JWT

O payload JWT contém informações sobre o JWT, incluindo as permissões sendo requisitadas (scopes), a conta solicitando acesso, o emissor, o momento em que o token foi emitido e o tempo de vida do token. A maioria dos campos são obrigatórios. Assim como o cabeçalho JWT, o payload é um objeto JSON e é usado na composição da assinatura.

1.3 - Campos Obrigatórios

Os campos obrigatórios no JWT são mostrados na tabela abaixo. Eles podem aparecer em qualquer ordem dentro do payload.

Entenda como funciona a conversão para os campos de emissão (iat) e expiração (exp) do jwt, e veja também exemplos de utilização dos valores dos campos aqui. Além disso, o campo “iat” deve ser o horário atual no formato exigido e o “exp” deve respeitar a conta abaixo:

A representação dos campos JSON obrigatórios no payload do JWT se dá da seguinte forma:

1.4 - Calculando a assinatura

A especificação JSON Web Signature (JWS)² é a mecânica que guia o cálculo da assinatura para um JWT. O conteúdo de entrada para o cálculo da assinatura é o byte array do seguinte conteúdo:

O mesmo algoritmo sinalizado no cabeçalho do JWT precisa ser utilizado para o cálculo da assinatura. O único algorítimo de assinatura suportado pela plataforma de autenticação OAuth2 é o RSA usando SHA-256. Ele é expressado como RS256 no campo alg do cabeçaho do JWT.

Assine a representação UTF-8 do conteúdo de entrada utilizando SHA256withRSA (também conhecido como RSASSA-PKCS1-V1_5-SIGN com o hash SHA-256) com a chave privada que foi criada e associada à conta de serviço (arquivo .key.pem gerado pela solicitação recebida por e-mail). O conteúdo de saída será um byte array.

A assinatura precisará ser então codificada em Base64url. O cabeçalho, o payload e a assinatura deverão ser concatenadas com o caractere de ponto final .. O resultado é o JWT. Ele deve ser da seguinte forma:

A seguir está um exemplo de token JWT antes da codificação em Base64url:

Abaixo está um exemplo do JWT que foi assinado e está pronto para transmissão:

Após a geração do JWT assinado, uma aplicação pode utilizá-lo para requisitar um token de acesso (Access Token). A requisição do token de acesso é uma requisição POST HTTPS e o corpo deve ser URL encoded. A URL é a mostrada abaixo:

Os parâmetros abaixo são obrigatórios na requisição POST HTTPS:

Se o JWT e a requisição do token de acesso foram formados apropriadamente e a conta de serviço tem as permissões necessárias, então a resposta da plataforma de autenticação retorna um objeto JSON contendo um token de acesso. Segue um exemplo de resposta da plataforma:

A duração do token de acesso é variável. Sua duração é especificada no campo “expires_in”, retornado juntamente com o token de acesso. Deve-se utilizar o mesmo token de acesso durante a sua validade para todas as chamdas às APIs dos produtos.

Não solicite um novo token de acesso até que a validade do token atual esteja chegando ao fim. Sugerimos uma margem de 600 segundos (10 minutos). Para isso execute o cálculo:

Sendo que token.exp é o timestamp da expiração do token.

Exemplos:

Um novo token de acesso pode ser solicitado quando faltar 10 minutos pra expirar.

• ¹ De acordo com o RFC 4648 de codificação BaseN, o formato Base64url é similar ao formato Base64, com exceção do caracter = que deve ser omitido, e dos caracteres + e / que devem ser substituídospor - e _, respectivamente.

Faça download do arquivo abaixo, importe no Postman e substitua o valor dos parâmetros "service_account", "tenant_id" e "secret_key" para testar a chamada.