1 of 22

Unico Identity

Introdução

Visão Geral

Bem-vindo à documentação das integrações dos serviços de autenticação da plataforma Unico IDCloud. Nesta página, você encontrará tudo o que precisa para integrar seu SSO e provisionar as permissões dos seus usuários nos produtos da Unico.

Integração entre Aplicação e Produto

Introdução

O sistema de autenticação OAuth2 da unico suporta a interação server-to-server entre uma aplicação web e os produtos e 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.

Por exemplo, uma aplicação que utiliza o unico | sign para enviar um documento que precisa de assinaturas de pessoas, deve utilizar uma conta de serviço para fazer a autenticação na API do unico | sign. Outros exemplos incluem uma aplicação que utiliza o unico | check para iniciar um processo de crediário, ou outra aplicação que se integra com unico | people para gerenciar posições de trabalho. Em ambos os casos, para interagirem com as API’s dos produtos da unico, requer-se que tais aplicações sejam autenticadas através de suas contas de serviço.

Este documento descreve como uma aplicação pode completar o processo de autenticação OAuth2 server-to-server através do protocolo HTTP.

Criando uma Conta de Serviço

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). 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:

Preparando para fazer uma requisição autenticada à API

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

Criar um JSON Web Token (JWT), que inclui cabeçalho, payload e assinatura;
Requisitar um token de acesso (AccessToken) da plataforma de autenticação OAuth2;
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:

{Cabeçalho em Base64url}.{Payload em Base64url}.{Assinatura em Base64url}

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

{Cabeçalho em Base64url}.{Payload em Base64url}

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:

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

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

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.

Nome

Descrição

iss

O identificador da conta de serviço na empresa.

scope

Uma lista delimitada por espaços ou pelo sinal de positivo + das permissões que a aplicação está requisitando. Se todas as permissões da conta forem necessárias, utilizar o sinal de asterisco * para tal.

aud

Casos recorrentes que NÃO funcionam:

exp

O tempo de expiração do token, especificado em segundos desde 00:00:00 UTC, 1 de Janeiro de 1970. Este valor tem um tempo máximo de 1 hora após o momento da emissão do JWT. Este valor deve ser numérico. Casos recorrentes que NÃO funcionam: - Uso de aspas na delimitação do valor. Ex.: “1524161193” é uma string e não funcionará. Já 1524161193 é um número e funcionará.

iat

O momento da emissão do JWT, especificado em segundos desde 00:00:00 UTC, 1 de Janeiro de 1970. Este valor deve ser numérico. - Uso de aspas na delimitação do valor. Ex.: “1524161193” é uma string e não funcionará. Já 1524161193 é um número e funcionará.

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:

exp = iat + 3600

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

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
  "iat": 1626293376 // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
}

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:

{Cabeçalho em Base64url}.{Payload em Base64url}

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:

{Cabeçalho em Base64url}.{Payload em Base64url}.{Assinatura em Base64url}

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

{"alg":"RS256","typ":"JWT"}.
{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
  "iat": 1626293376 // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
}.
[byte array da assinatura]

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

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

Também é possível utilizar bibliotecas previamente estabelecidas para realizar a criação do JWT. Como referência, é possível encontrar uma lista de bibliotecas no site jwt.io.

2 - Fazendo a requisição de um token de acesso

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:

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

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

Nome

Descrição

grant_type

Utilize o seguinte texto, URL-encoded se necessário: urn:ietf:params:oauth:grant-type:jwt-bearer

assertion

O JWT, incluindo a assinatura.

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 - Tratando a resposta da plataforma de autenticação

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:

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

O token de acesso retornado no campo “acess_token” do objeto JSON também é um token JWT que deverá ser utilizado nas APIs dos Produtos da unico. Caso retorne um erro na requisição, é possível consultar o tipo do erro na seção "Erros de autenticação".

4 - Duração do token de acesso

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:

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

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

Por padrão, o token enviado para a empresa tem duração de 1h, mas pode ser alterado. A sugestão é sempre usar o expires_in como base e subtrair 600s dele para pedir um novo token.

Exemplos:

Cenário padrão:
expires_in: 3600 (1h) - Geração do token as 14h42

Solicitar um novo token somente as 15h32 ou seja, 14:42 + (3600 - 600)

Cenário com a duração alterada:
expires_in: 7200 (2h) - Geração do token as 14h42

Solicitar um novo token somente as 16h32 ou seja, 14:42 + (7200 - 600)

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

Não utilize um tempo fixo para a obtenção de um novo token, pois o tempo de duração do token recebido pode ser menor que o tempo estabelecido, o que ocasionará falha na utilização dos serviços.

¹ 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.
² JSON Web Signature: https://tools.ietf.org/html/rfc7515.

Recursos adicionais

Exemplo em Javascript

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

Erros de autenticação

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

Postman Collection

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.

SSO com SAML

Introdução

O protocolo SAML (Security Assertion Markup Language) é um padrão de autenticação e autorização que permite que identidades e informações de login sejam transferidas com segurança entre Provedores de Identidade e Provedores de Serviço.

A integração com SAML é comum em sistemas de mercado que precisam permitir Single Sign-On (SSO), onde os usuários podem acessar diversos serviços usando um único conjunto de credenciais (login e senha).

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.

Usando SSO para autenticar usuários nos produtos da Unico

O Single Sign-On (SSO) simplifica o acesso aos produtos da Unico, permitindo que os usuários utilizem um único login - o mesmo utilizado internamente pela empresa - trazendo uma melhor experiência para o processo de autenticação e diversos benefícios de segurança para a empresa.

A gestão da autenticação fica sob controle da empresa diretamente em seu sistema de gestão de identidades e de acessos, eliminando a necessidade de solicitar suporte a Unico.

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.

Entendendo os Componentes do SAML

Antes de iniciar a integração, é importante entender os principais componentes do SAML:

Provedor de Identidade (IdP): O serviço que autentica o usuário. Por exemplo, um diretório corporativo (como Active Directory) ou um serviço de autenticação externo (como Okta, Azure AD, etc.).

Provedor de Serviço (SP): A aplicação ou serviço que o usuário está tentando acessar. Neste caso, o sistema de autenticação da Unico, que é o responsável pela autenticação e autorização dos usuários que precisam acessar os portais dos produtos.

Assertions: São as mensagens XML que transportam informações de autenticação e autorização entre o IdP e o SP.

SAML Metadata: Documento XML que contém a configuração necessária para que o IdP e o SP se comuniquem com segurança.

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.

Passos para Integração com SAML

Registrar o Provedor de Serviço (SP) no IdP

Você precisará fornecer ao IdP detalhes como o Entity ID (um identificador único para o SP) e ACS URL (Assertion Consumer Service URL), que é o endpoint do SP onde as assertions SAML serão enviadas.

Mapear Atributos de Usuários

É necessário fazer o mapeamento de atributos de usuários que define como as informações de um usuário (como nome, email, username, etc.) são transferidas e representadas entre dois sistemas diferentes (seu IdP e a Unico).

Os "claims" do SP criado devem seguir os parâmetros conforme tabela abaixo:

O IdP geralmente fornece um arquivo XML que contém informações como: seu certificado público, URLs de endpoints de autenticação e etc.

É necessário enviar esse arquivo para nossa Equipe de Suporte.

Aqui está um exemplo de como um metadata XML para um SP pode parecer:

Primeiro Acesso

Após a criação e configuração do SP no IdP, basta que o usuário se autentique utilizando uma das seguintes URLs:

Após inserir as informações da empresa e usuário na tela de login, o usuário será redirecionado para a autenticação externa (IdP). Após uma autenticação bem sucedida pelo IdP, o usuário será redirecionado para a URL de callback configurada e será criado no sistema de autenticação e autorização da Unico.

A integração SAML não permite o controle de autorização dos usuários, mantendo a necessidade de solicitar os acessos para a equipe de Suporte da Unico.

Caso tenha interesse em fazer a gestão completa de seus usuários de forma independente, siga os passos da seção "SCIM - Provisionamento de Usuários".

Configuração por Provedor de Identidade

Microsoft Entra

Crie um Aplicativo Enterprise

Vá para o painel Microsoft Entra ID > Enterprise Applications.

Utilize a opção New application e em seguida a opção Create your own application.

Nomeie o aplicativo com o nome do produto que está sendo contrato e clique em Create. Por exemplo, Unico Check.

Configure o Aplicativo Criado

No painel do aplicativo criado, vá para Manage > Single sign-on e escolha a opção SAML.

Edite a seção Basic SAML Configuration e preencha com as informações de Entity ID e ACS fornecidas anteriormente.

Edite todos atributos da seção Attributes & Claims conforme tabela de atributos. Remova o conteúdo do Namespace de todos os atributos editados.

Os atributos devem ficar iguais aos da imagem abaixo:

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.

SCIM - Provisionamento de Usuários

Introdução

O provisionamento envolve a criação, modificação e exclusão de contas de usuários, incluindo a atribuição de permissões para garantir o acesso adequado aos recursos necessários.

Como funcionalidades, é possível criar, editar e associar o usuário a grupos de permissões predefinidos. Esses grupos concedem acesso aos portais dos produtos da Unico.

Esse processo é realizado pelo protocolo SCIM¹, que simplifica e automatiza a gestão de identidades e acessos em ambientes distribuídos, promovendo uma integração eficiente entre sistemas e uma administração centralizada de usuários. Como resultado, os usuários podem ser gerenciados de forma independente, sem a necessidade de abertura de tickets para a equipe de suporte da Unico.

¹ SCIM: System for Cross-domain Identity Management - Protocolo que padroniza gestão de identidades e acessos.

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.

Compatibilidade

Nós temos compatibilidade com os seguintes provedores de identidade, escolha o que a sua empresa utiliza e siga os passos para criar a configuração.

Microsoft Entra ID (Azure AD)
Okta (Documentação em desenvolvimento)
JumpCloud (Documentação em desenvolvimento)

Entre em contato conosco caso o seu sistema não esteja aparecendo na lista.

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.

Configuração por Provedor de Identidade

Microsoft Entra

Esse passo a passo deve ser realizado para cada produto da Unico que for contratado pela sua empresa.

Documentação da Microsoft: Provisionamento de aplicativo - Microsoft Entra ID.

Criar um novo aplicativo

Na tela Azure Services, entre em Microsoft Entra ID.
Vá para Manage > Enterprise Applications e clique em New application.

Na próxima etapa, selecione a opção Create your own application.

Defina o nome do seu aplicativo e clique em Create (como sugestão, dê o nome do produto contratado para o seu aplicativo. Ex: Unico Check).

Configuração do single sign-on (SSO) no aplicativo

Para o provisionamento de usuários funcionar, é necessário criar uma configuração de SSO no aplicativo que você acabou de criar. Essa configuração utiliza o protocolo de federação SAML2.0 e deve ser feita em conjunto com a Unico.

Veja aqui como configurar o SSO no seu aplicativo: SSO com SAML - Microsoft Entra.

Configurar o provisionamento no aplicativo

No painel do aplicativo criado, vá para Manage > Provisioning.

Na seleção Provisioning Mode, escolha a opção Automatic.
Preencha os campos Tenant URL e Secret Token com as informações fornecidas pela Unico e clique em Test Connection.

Após ter a conexão bem sucedida, salve as configurações aplicadas.

Mapear atributos dos usuários

Após configurar as credenciais e salvar a conexão, é necessário mapear os atributos do sistema de origem com os atributos do Entra ID para garantir a sincronização correta.

Expanda a seção Mappings e clique em Provision Microsoft Entra ID Users.

Edite e remova atributos adicionais e deixe somente os exibidos na imagem abaixo:

É importante que os valores dos atributos mapeados acima sejam os mesmos dos atributos mapeados na configuração de SSO do aplicativo.

A criação dos grupos no Microsoft Entra só deve ser realizada após a Unico disponibilizar a lista.

Os nomes devem ser exatamente iguais aos disponibilizados, para garantir a sincronização correta entre o sistema da Unico e o Microsoft Entra.

Conclusão

É possível associar os grupos criados ao aplicativo que foi configurado para provisionamento e, em seguida, associar os usuários aos grupos de acordo com suas necessidades de acesso.

Os usuários membros dos grupos associados ao aplicativo serão automaticamente provisionados no sistema da Unico.

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.

Preparando para fazer uma requisição autenticada à API

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

Criar um JSON Web Token (JWT), que inclui cabeçalho, payload e assinatura;
Requisitar um token de acesso (AccessToken) da plataforma de autenticação OAuth2;
Tratar a resposta JSON que a plataforma de autenticação retornará.

1 - Criando o JWT

Um JWT é composto da seguinte forma:

{Cabeçalho em Base64url}.{Payload em Base64url}.{Assinatura em Base64url}

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

{Cabeçalho em Base64url}.{Payload em Base64url}

1.1 - Formando o cabeçalho JWT

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

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

1.2 - Formando o payload JWT

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.

Nome

Descrição

iss

O identificador da conta de serviço na empresa.

scope

aud

Endereço da plataforma de autenticação que faz a emissão de tokens de acesso. Este valor deverá ser sempre e exatamente .

Casos recorrentes que NÃO funcionam:

- Inserção de uma barra ao final do endereço:

- Uso do protocolo HTTP ao invés de HTTPS:

exp

iat

exp = iat + 3600

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

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
  "iat": 1626293376 // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
}

1.4 - Calculando a assinatura

{Cabeçalho em Base64url}.{Payload em Base64url}

{Cabeçalho em Base64url}.{Payload em Base64url}.{Assinatura em Base64url}

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

{"alg":"RS256","typ":"JWT"}.
{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
  "iat": 1626293376 // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
}.
[byte array da assinatura]

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

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

Também é possível utilizar bibliotecas previamente estabelecidas para realizar a criação do JWT. Como referência, é possível encontrar uma lista de bibliotecas no site jwt.io.

2 - Fazendo a requisição de um token de acesso

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

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

Nome

Descrição

grant_type

Utilize o seguinte texto, URL-encoded se necessário: urn:ietf:params:oauth:grant-type:jwt-bearer

assertion

O JWT, incluindo a assinatura.

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 - Tratando a resposta da plataforma de autenticação

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

4 - Duração do token de acesso

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:

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

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

Por padrão, o token enviado para a empresa tem duração de 1h, mas pode ser alterado. A sugestão é sempre usar o expires_in como base e subtrair 600s dele para pedir um novo token.

Exemplos:

Cenário padrão:
expires_in: 3600 (1h) - Geração do token as 14h42

Solicitar um novo token somente as 15h32 ou seja, 14:42 + (3600 - 600)

Cenário com a duração alterada:
expires_in: 7200 (2h) - Geração do token as 14h42

Solicitar um novo token somente as 16h32 ou seja, 14:42 + (7200 - 600)

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.
² JSON Web Signature: https://tools.ietf.org/html/rfc7515.

Unico Identity

Introdução

Visão Geral

Leia mais

Integração entre Aplicação e Produto

Introdução

Criando uma Conta de Serviço

Preparando para fazer uma requisição autenticada à API

1 - Criando o JWT

1.1 - Formando o cabeçalho JWT

1.2 - Formando o payload JWT

1.3 - Campos Obrigatórios

1.4 - Calculando a assinatura

2 - Fazendo a requisição de um token de acesso​

3 - Tratando a resposta da plataforma de autenticação​

4 - Duração do token de acesso​

Recursos adicionais

Exemplo em Javascript

Erros de autenticação

Postman Collection

SSO com SAML

Introdução

Usando SSO para autenticar usuários nos produtos da Unico

Entendendo os Componentes do SAML

Passos para Integração com SAML

Registrar o Provedor de Serviço (SP) no IdP

Mapear Atributos de Usuários

Primeiro Acesso

Configuração por Provedor de Identidade

Microsoft Entra

Crie um Aplicativo Enterprise

Configure o Aplicativo Criado​

SCIM - Provisionamento de Usuários

Introdução

Compatibilidade

Configuração por Provedor de Identidade

Microsoft Entra

Criar um novo aplicativo

Configuração do single sign-on (SSO) no aplicativo

Configurar o provisionamento no aplicativo

Mapear atributos dos usuários

Conclusão

Exemplo em Javascript

Criando uma Conta de Serviço

Introdução

Visão Geral

Leia mais

Entendendo os Componentes do SAML

Introdução

Preparando para fazer uma requisição autenticada à API

1 - Criando o JWT

1.1 - Formando o cabeçalho JWT

1.2 - Formando o payload JWT

1.3 - Campos Obrigatórios

1.4 - Calculando a assinatura

2 - Fazendo a requisição de um token de acesso​

3 - Tratando a resposta da plataforma de autenticação​

4 - Duração do token de acesso​

Postman Collection

Introdução

Usando SSO para autenticar usuários nos produtos da Unico

Compatibilidade

Microsoft Entra

Crie um Aplicativo Enterprise

Configure o Aplicativo Criado​

Microsoft Entra

Criar um novo aplicativo

Configuração do single sign-on (SSO) no aplicativo

Configurar o provisionamento no aplicativo

Mapear atributos dos usuários

Conclusão

Primeiro Acesso

Erros de autenticação

Introdução

Passos para Integração com SAML

Registrar o Provedor de Serviço (SP) no IdP

Mapear Atributos de Usuários

Obter o Metadata do IdP

Exemplo de Metadados SAML

Obter o Metadata do IdP

2 - Fazendo a requisição de um token de acesso

3 - Tratando a resposta da plataforma de autenticação

4 - Duração do token de acesso

Configure o Aplicativo Criado

2 - Fazendo a requisição de um token de acesso

3 - Tratando a resposta da plataforma de autenticação

4 - Duração do token de acesso

Configure o Aplicativo Criado