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.

Leia mais

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:

{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.

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

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:

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

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".

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.

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

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.

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.

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.

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:

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

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:

<EntityDescriptor entityID="https://your-sp.example.com/" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
    <SPSSODescriptor
        AuthnRequestsSigned="true"
        protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

        <KeyDescriptor use="signing">
            <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
                <X509Data>
                    <X509Certificate>YourSigningCertificate</X509Certificate>
                </X509Data>
            </KeyInfo>
        </KeyDescriptor>

        <AssertionConsumerService
            Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
            Location="https://your-sp.example.com/acs"
            index="1"/>
    </SPSSODescriptor>
</EntityDescriptor>

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.

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.

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

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

Criar um novo aplicativo

1. Na tela Azure Services, entre em Microsoft Entra ID.

2. Vá para Manage > Enterprise Applications e clique em New application.

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

1. 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

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

1. Na seleção Provisioning Mode, escolha a opção Automatic.

2. 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.

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

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

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.

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.

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.

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.

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

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: