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:
Abaixo é listado os principais serviços ligados ao fluxo OAuth:
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âmetro | Valor |
|---|---|
| grant_type | OBRIGATÓRIO. Este parâmetro aceita um dos seguintes valores: password ou refresh_token. Password é utilizado no fluxo de geração do token, enquanto refresh token é utilizado para renovar um token já existente. |
| username | OBRIGATÓRIO. O usuário que está no processo de autenticação. |
| password | OBRIGATÓRIO. A senha do usuário no fluxo de autenticação. |
| refresh_token | OPCIONAL. Obrigatório apenas quando grant_type for refresh_token. Este parâmetro espera o código refresh_token para gerar um novo token. |
| subdomain | OBRIGATÓ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. |
| orgSubdomain | OBRIGATÓ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. |
| connectorId | OBRIGATÓ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âmetro | Valor |
|---|---|
| access_token | OBRIGATÓ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" }
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):
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.
Ao término destes passos a tela abaixo será apresentada. Você deverá guardar as seguintes informações (exemplo) para utilizar nas requests à plataforma:
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:
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
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:
Revoke Manual: Na lista de conectores, note que é exibido um conector (referente ao token válido) juntamente com a opçãoRevoke. Clicando nesta opção pode-se revogar o token atual.
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.
- 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).
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 processo para login na plataforma Carol inicia-se com:
- um convite enviado ao usuário por e-mail pelo administrador da organização ou Tenant através da própria plataforma Carol;
- o aceite do convite enviado por e-mail pelo usuário;
- o recebimento de um e-mail confirmando o sucesso no registro do usuário dentro da plataforma Carol na organização ou Tenant indicada;
- a execução do login na organização ou Tenant dentro da plataforma Carol.
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.
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.
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.
Habilitando a integração do login pelo TOTVS Identity
Após realizado o fluxo de login pela plataforma Carol, é possível alterá-lo, de modo que o método de autenticação utilizado seja por meio do TOTVS Identity ou de um provedor de identidade terceiro.
A configuração de identidade é realizada a nível de organização, ou seja, todas as tenants dentro da organização terão esta configuração.
Para isto basta acessar as configurações da organização e ativar o login usando um provedor de identidade.
Depois de ativado, selecione a opção TOTVS Identity ativando ela e faça logout da plataforma.
Ao realizar novo login a plataforma irá redirecionar o usuário para o novo provedor de identidade.
Você precisa ter seu usuário antes cadastrado neste provedor de identidade e tê-lo atribuído para o aplicativo TOTVS Identity respectivo à sua organização. Procure o seu gestor e peça a ele para habilitar este acesso dentro do TOTVS Identity. A TOTVS Labs não é responsável por esse papel, pois trata-se de um tema de Governança.
Caso já tenha o usuário cadastrado e atribuido ao aplicativo TOTVS Identity da sua organização, será apresentada a seguinte interface ao usuário.
Caso o usuário já tenha se logado em uma sessão do identity, ele será redirecionado para a página inicial da Carol por meio da autenticação de login única (SSO).
Caso contrário deverá informar suas credenciais de acesso para depois ser direcionado a página inicial da Carol.
Caso o usuário seja direcionado ao Fluig Identity, isso significa que ele não foi atribuído ao aplicativo TOTVS Identity da sua organização. Desta forma siga o procedimento indicado anteriormente para habilitar o acesso com o seu gestor.
Uma vez habilitado o TOTVS Identity a funcionalidade de convites por meio da Carol estão desativadas, portanto, toda a gestão de usuários na Carol (inclusão, exclusão e manutenção) passa a ser responsabilidade da TOTVS, pois trata-se de um tema de Governança Corporativa. Procure o seu gestor e peça a ele para direcionar sua necessidade dentro do TOTVS Identity.