Skip to main content

Autenticação e Login

A Carol possui autenticação OAuth, podendo ser explorado a autenticação API Key (também conhecido como API Token ou Connector Token).

→ Veja mais informações sobre OAuth na RFC 6749.

Visão Geral​

Abaixo um fluxo demonstrando o processo de autenticação OAuth:

Overview

Abaixo é listado os principais serviços ligados ao fluxo OAuth:

Oauth2

Esses serviços permitem efetuar a autenticação na Carol e efetuar a validação de um token já existente. Vamos ver os detalhes desses serviços

/api/v1/oauth2/token​

Este endpoint permite efetuar a autenticação na Carol, validando se o usuário e a senha possuem acesso à plataforma. Abaixo é detalhado os parâmetros necessários:

ParâmetroValor
grant_typeOBRIGATÓRIO. Este parâmetro aceita um dos seguintes valores: password ou refresh_token. Enquanto password é utilizado no fluxo de geração do access token, refresh token é utilizado para renovar tokens já existentes mantendo a sessão ativa, fornecendo tanto um novo access token quanto um novo refresh token. Atenção: Por definição padrão o tempo para expiração de um access token é de uma (01) hora, enquanto de um refresh token é de 72 horas.
usernameOBRIGATÓRIO. O usuário que está no processo de autenticação.
passwordOBRIGATÓRIO. A senha do usuário no fluxo de autenticação.
refresh_tokenOPCIONAL. Obrigatório apenas quando grant_type for refresh_token. Este parâmetro espera o código refresh_token para gerar um novo access token e refresh token. Atenção: Os demais parâmetros devem permanecer vazios.
subdomainOBRIGATÓRIO. Este parâmetro é o nome da Tenant (antes chamado de ambiente). O nome da Tenant é parte da URL, e pode ser obtido da seguinte forma no exemplo a seguir: "totvs.carol.ai/production", o nome da Tenant é production.
orgSubdomainOBRIGATÓRIO. Nome da organização. Este parâmetro espera o mesmo nome definido como subdominio da URL da Carol. Por exemplo, "totvs.carol.ai/production", o nome da organização é totvs.
connectorIdOBRIGATÓRIO. Este parâmetro recebe o código do conector ou o nome do conector (visualizado na URL ou nos detalhes do conector).

Abaixo é um exemplo da request usando o comando ~~curl~~:

curl -X POST "https://clockin.carol.ai/api/v1/oauth2/token" -H "accept: application/json" -H "content-type: application/x-www-form-urlencoded" -d "grant_type=password&connectorId=clockinmobile&username=robson.poffo%40totvs.com&password=SENHA_AQUI&subdomain=clockin&orgSubdomain=global"

O resultado da request é semelhante ao abaixo:

{ "access_token": "1e2fe288fa3a4ca38257294008081317", "client_id": "4c2c9090e7c611e893bf0e900682978b_33dd1190ff2c11e8858be609736e2a59_c1367ca0e86311e8b979aedbc4a09666_mdmConnector", "expires_in": 3495, "refresh_token": "1fd8bc5763734ad0b8e18e2cd328f2f8", "state": "", "timeIssuedInMillis": 1591855130722, "token_type": "bearer" }

/api/v1/oauth2/token/{access_token}/userAccessDetails​

Este endpoint permite resgatar detalhes referente ao token, inclusive verificar se o token ainda está válido:

ParâmetroValor
access_tokenOBRIGATÓRIO. Access token gerado pelo endpoint "token".

Abaixo é um exemplo da request usando o comando curl:

 curl -X GET "https://clockin.carol.ai/api/v1/oauth2/token/1e2fe288fa3a4ca38257294008081317/userAccessDetails" -H "accept: application/json" 

O resultado da request é semelhante ao abaixo:

{ "envUserId": "c1367ca0e86311e8b979aedbc4a09666", "externalAppId": "33dd1190ff2c11e8858be609736e2a59", "loginLevel": "mdmTenant", "orgId": "856e0510729e11e99928acde48001122", "refreshToken": "1fd8bc5763734ad0b8e18e2cd328f2f8", "system": false, "tenantId": "4c2c9090e7c611e893bf0e900682978b", "userId": "fe115382754247d883d9a11b88b3d96e" }

Autenticação via API Token com 2FA​

Quando o 2FA está habilitado, o login por API ocorre em duas etapas: a primeira etapa recebe login e senha e retorna um mfa_token; a segunda etapa utiliza esse mfa_token + código 2FA e retorna access_token e refresh_token. Vamos detalhar as etapas abaixo.

Pré-requisitos:

  1. 2FA ativo na sua conta e app autenticador configurado.
  2. Subdomínio e connectorId válidos para o seu tenant.

Etapa 1: obter o token MFA​

Abaixo é um exemplo da primeira request usando o comando curl:

curl --location 'https://api.carol.ai/api/v5/oauth2/token' \
--header 'accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=<seu_login>' \
--data-urlencode 'password=<sua_senha>' \
--data-urlencode 'connectorId=<seu_connectorId>' \
--data-urlencode 'subdomain=<subdominio_tenant>'

O resultado da request é semelhante ao abaixo:

{"access_token":"","client_id":"<client_id>","expires_in":0,"mfa_enabled":true,"mfa_token":"<seu_token_mfa>","refresh_token":"","timeIssuedInMillis":0,"token_type":"bearer"}

Etapa 2: validar o código do autenticador​

Após obter o seu mfa_token, utilize o endpoint https://api.carol.ai/api/v5/oauth2/token/mfa/authenticate e o código de 6 dígitos obtido no app autenticador para receber o access_token e refresh_token.

curl --location 'https://api.carol.ai/api/v5/oauth2/token/mfa/authenticate' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: <seu_token_mfa>' \
--data-raw 'mfaCode=<codigo_6digitos>'

O resultado da request é semelhante ao abaixo, contendo access_token e refresh_token.

{"access_token":"<access_token>","client_id":"<client_id>","expires_in":3599,"mfa_enabled":true,"mfa_token":"","refresh_token":"<refresh_token>","state":"","timeIssuedInMillis":1758052178848,"token_type":"bearer"}

Connector Token (API Key)​

Além do processo convencional de autenticação do processo OAuth, é possível fazer a geracão de um token persistente. Este token é chamado de Connector Token, e o mesmo é utilizado principalmente em integração de processos sendo que é utilizado uma chave pública e uma chave privada, conforme detalhado a seguir:

Sendo que já efetuamos o login na plataforma, vamos acessar item Tenant Admin no menu lateral (primeiro ícone no cabeçalho, da direita para a esquerda):

Connector Token

Importante

O token do tipo Google Service Account gera uma Service Account com permissão para acessar recursos da Google como o BigQuery. Essa Service Account também atribui permissão para fazer a criação de modelos de machine learning (create model). Maiores detalhes na seção Carol App desta documentação.

A criação de novos tokens ocorre pelo botão Create token (na tela acima). Na tela que será aberta, deverá ser selecionado o conector que será utilizado para criar o token, também é possível adicionar uma descrição para revisão futura deste token.

newtoken

Ao término destes passos a tela abaixo será apresentada. Você deverá guardar as seguintes informações (exemplo) para utilizar nas requests à plataforma:

newtoken2

ConnectorID: 90d7bcd37c424d85a733a42117528792

Connector Token: d0d7dc1612394edcb4d961dc80393cb6

O acesso pelo conector permite visualizar que ele possui tokens gerados, e é possível navegar para o fluxo acima apresentado (Tenant Admin), podendo assim efetuar a manutenção dos tokens:

New token 3

Regras de Token​

Um item importante a se considerar referente ao Connector é que, em cada Tenant, só é possível criar um Token por connector.

Caso o usuário queira efetuar uma consulta para validar se o token ainda é valido, deve-se utilizar o endpoint abaixo, preenchendo o apiKey juntamente com o connectorID:

/api/v1/apikey/details​

Regras

Revogação​

O Connector Token uma vez criado, não expira. Para que o mesmo seja revogado ou invalidado, deve-se por conta das regras abaixo:

  1. Revoke Manual: Na lista de conectores, note que é exibido um conector (referente ao token válido) juntamente com a opção Revoke. Clicando nesta opção pode-se revogar o token atual.

Revogation

Revogation2

  1. Novo token gerado para o mesmo usuario e conector: Uma vez que um connector já obtém um token criado, caso o usuário crie um novo, o Token anterior será invalidado. Há situações em que outro app pode criar um outro token para o mesmo connector, invalidando o atual. Nesses casos, é recomendado alinhar com o time para que ambos usem o mesmo, evitando impactos de validação.

Revogation3

  1. Usuário removido da plataforma.

Próximos Passos​

Uma vez que a autenticação ocorreu, teremos o access_token disponível. Este valor deve ser inserido no Swagger no atributo Access Token (parte superior central).

Access Token

As subsequentes requests são autenticadas conforme a request a seguir:

 curl -X GET "https://clockin.carol.ai/api/v1/users?pageSize=10&sortOrder=ASC" -H "accept: application/json" -H "Authorization: 1e2fe288fa3a4ca38257294008081317" 

Se a autenticação ocorreu através do Connector Token (conforme descrito acima) a request (comando curl) acima ficará da seguinte forma:

curl -X GET "https://clockin.carol.ai/api/v1/users?pageSize=10&sortOrder=ASC" -H "accept: application/json" -H "X-Auth-ConnectorId: 90d7bcd37c424d85a733a42117528792" -H "X-Auth-Key: d0d7dc1612394edcb4d961dc80393cb6"

Fluxo de Login​

O fluxo abaixo descreve o cadastro por convite, quando disponível na organização. Para adicionar pessoas em organizações integradas ao TOTVS Identity, siga o passo a passo de Add User.

No fluxo de convite, o processo para login na plataforma Carol inicia-se com:

  1. um convite enviado ao usuário por e-mail pelo administrador da organização ou Tenant através da própria plataforma Carol;

Invite

  1. o aceite do convite enviado por e-mail pelo usuário;

Email Accept

  1. o recebimento de um e-mail confirmando o sucesso no registro do usuário dentro da plataforma Carol na organização ou Tenant indicada;

Register

  1. a execução do login na organização ou Tenant dentro da plataforma Carol.

Login

Após entrar na plataforma, acesse Minha conta pelo menu do usuário para gerenciar os dados e as configurações da sua conta.

Um fluxo alternativo se dá pela marcação da opção de login por SMS nas configurações da Tenant ou organização. Neste fluxo o usuário precisa de um número de telefone cadastrado para receber o convite enviado pelo Administrador da Tenant ou organização.

SMS

Parâmetros

  • Use SMS: indica que a Tenant pode utilizar SMS.
  • Login by SMS: indica que a Tenant pode efetuar login por SMS.
  • Receipt of the code by email: indica que o usuário receberá uma cópia do token por e-mail.
Importante

Para que o administrador da Tenant possa convidar usuários é necessário que opção Allow Tenant users to invite new users to the Tenant esteja marcada dentro das configurações da Organização.

Settings

Habilitando a integração do login pelo TOTVS Identity​

Configuração da organização​

Nas configurações da organização, ative o login por provedor de identidade e selecione TOTVS Identity. Essa configuração vale para todas as Tenants da organização.

IDP

TOTVS Identity

Depois de salvar, faça logout para usar o novo método de login.

Acesso da pessoa à Carol​

Acesse o endereço da organização na Carol. O login será direcionado ao Identity: se já houver uma sessão corporativa ativa, a entrada será automática; caso contrário, informe suas credenciais.

IDP Signin

IDP Credentials

Se a Carol abrir normalmente, o acesso já está configurado. Se abrir o Launchpad do Fluig Identity, siga os passos abaixo.

Adicionar o aplicativo ao seu Identity​

A própria pessoa realiza esta etapa, com uma conta Identity existente:

  1. No Launchpad, clique em Add App e busque o aplicativo da organização e do ambiente que vai acessar.
No Launchpad, clique em Add AppBusque o aplicativo e clique em + Add
Botão Add App no Launchpad do Fluig IdentityCatálogo do Identity com os aplicativos TOTVS Techfin Dev, Produção e Staging e seus botões + Add
Destino na CarolNome do aplicativo no Identity
Organização totvsTOTVS Carol Plataforma
Organização totvstechfindev (Dev)TOTVS Techfin Dev
Techfin — StagingTOTVS Techfin Staging
Techfin — ProduçãoTOTVS Techfin Produção
  1. Clique em + Add no aplicativo escolhido. Quando aparecer Added, volte ao Launchpad e abra o aplicativo pelo novo ícone.

Se você ainda não tem conta ou o aplicativo não aparece na busca, procure o responsável pelo Identity na organização.

A permissão na Tenant é definida pelo Tenant Admin em Users → Add User. Use o mesmo e-mail no Identity e na Carol.