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;

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:

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

Nome

Descrição

1.0.1

Verifique se o ID informado na formação do "iss" é o ID do tenant correto, fornecido na geração da chave privada¹.

1.0.14

Verifique com o responsável pelo projeto se a aplicação utilizada está ativa.

1.1.1

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 .

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.

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.

Ambiente

Valores

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:

Atributo

Valor

Obrigatoriedade

Obter o Metadata do IdP

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.

Exemplo de Metadados SAML

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

Dúvidas?

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

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:

Ambiente de Produção: https://identity.acesso.io.
Ambiente de Homologação: https://identityhomolog.acesso.io.

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

Dúvidas?

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

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

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.

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

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 .

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 .

Unico Identity

Introdução

hashtagVisão Geral

hashtagLeia mais

Integração entre Aplicação e Produto

Introdução

Criando uma Conta de Serviço

Preparando para fazer uma requisição autenticada à API

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

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

hashtagMapear Atributos de Usuários

hashtagObter o Metadata do IdP

hashtagExemplo de Metadados SAML

Primeiro Acesso

Configuração por Provedor de Identidade

Microsoft Entra

hashtagCrie um Aplicativo Enterprise

hashtagConfigure o Aplicativo Criado

SCIM - Provisionamento de Usuários

Introdução

Compatibilidade

Configuração por Provedor de Identidade

Microsoft Entra

hashtagCriar um novo aplicativo

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

hashtagConfigurar o provisionamento no aplicativo

hashtagMapear atributos dos usuários

hashtagConclusão

Integração entre Aplicação e Produto

Introdução

hashtagVisão Geral

hashtagLeia mais

Introdução

Criando uma Conta de Serviço

Introdução

Microsoft Entra

hashtagCriar um novo aplicativo

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

hashtagConfigurar o provisionamento no aplicativo

hashtagMapear atributos dos usuários

hashtagConclusão

Recursos adicionais

Usando SSO para autenticar usuários nos produtos da Unico

SSO com SAML

SCIM - Provisionamento de Usuários

Configuração por Provedor de Identidade

Primeiro Acesso

Compatibilidade

Entendendo os Componentes do SAML

Postman Collection

Configuração por Provedor de Identidade

Microsoft Entra

hashtagCrie um Aplicativo Enterprise

hashtagConfigure o Aplicativo Criado

Exemplo em Javascript

Erros de autenticação

Introdução

Preparando para fazer uma requisição autenticada à API

hashtag1 - Criando o JWT

hashtag1.1 - Formando o cabeçalho JWT

hashtag1.2 - Formando o payload JWT

hashtag1.3 - Campos Obrigatórios

hashtag1.4 - Calculando a assinatura

hashtag2 - Fazendo a requisição de um token de acesso​arrow-up-right

hashtag3 - Tratando a resposta da plataforma de autenticação​arrow-up-right

hashtag4 - Duração do token de acesso​arrow-up-right

Passos para Integração com SAML

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

hashtagMapear Atributos de Usuários

hashtagObter o Metadata do IdP

hashtagExemplo de Metadados SAML

Visão Geral

Leia mais

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

Mapear Atributos de Usuários