Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

Índice
maxLevel4
outlinetrue
exclude.*ndice
stylenone


Visão Geral

...

O objetivo deste guia é apresentar a API REST para desenvolvedores. A documentação a seguir fornece uma introdução às APIs REST V2 do TOTVS Identity.

Para quem é voltada esta documentação?

Desenvolvedores de uma empresa que seja cliente do Identity. Desenvolvedores podem consumir APIs REST básicas para criar seus próprios clientes ou para fazer uma melhor integração entre seus softwares aplicativos e o Identity.

Informações
titleAtenção

Esta documentação é voltada à API REST específica do TOTVS Identity. Para consultar a documentação da API do TOTVS Fluig Plataforma, acesse Fluig API.

O que eu devo saber?

O esquema de autenticação e autorização das APIs REST V2 do Identity são baseadas no padrão de autenticação servidor a servidor OAuth 2.0 utilizando JWT (JSON Web Token). 

...


Plataforma

...

A plataforma REST do Identity é baseada nos padrões OAuth 2.0 com JWT (JSON Web Token) para estabelecer a comunicação servidor-a-servidor entre aplicativos.

Dica

Mais informações sobre JWT e OAuth 2.0 podem ser encontradas nos links a seguir:


Escopo do Identity para APIs REST

...

O Identity foi desenvolvido ao redor do conceito de "empresas". Cada empresa possui seu próprio subdomínio, por exemplo, https://totvs.fluigidentity.com, e seu próprio conjunto de dados (Ex: aplicativos, grupos). Cada software aplicativo integrado ao Identity terá acesso somente aos dados da empresa em que a integração foi configurada.

Cada empresa possui um Client ID e uma chave privada, que irá permitir o acesso aos dados específicos de sua empresa utilizando nossas REST APIs.


Começando

...

Para cada empresa são atribuídos recursos que garantem a segurança de acesso aos dados da empresa: identificador do cliente (ID do Cliente/client Id), identificador da empresa (ID da Empresa (ID da Empresa/company Id) e uma chave privada (private key). O administrador corporativo pode consultar esses dados através da aba Segurança no menu Configuração do Identity.


Crie/Assine o JWT

...

Criando JWT

Um JWT (JSON Web Token) possui vários campos (como definidos no padrão) para identificar o cliente que está fazendo a chamada. O único campo obrigatório é o campo "issuer" representado pelo atributo "iss" no JWT. O campo "iss" deve receber o valor do client id da empresa.

...

Bloco de código
{ “iss”: “INSIRA_O_CLIENT_ID_AQUI”}


Assinando o JWT

A assinatura do token JWT demanda vários passos para criptografar e assinar partes específicas do JWT, a fim de gerar o assertion. Estes passos são fornecidos como parte do padrão mencionado acima.

...

Bloco de código
titleExemplo de assertion
eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJmZmYwZGUzOS1hNGI1LTQzOWYtODgwOC01MjIxM2ZjZTc2YjgifQ.aneQAKQ0aO60bUN5WaeG5ZFTb6L4OA_rbO0x5XEV_6pi0bk8B2oW1gegOYtp3TKIRcN1dYr550sX1BnJJgr5WhVQhyiHbGCDDIN_cj2e6uMftqEpc7df900YVm5V-jSQXJLVUJbZb0GlFcuE3Jn3Un6vBoCnziVIcnyG-u-JJ88


Enviando/publicando o JWT para o Identity

assertion gerada no passo acima precisa ser publicada na URL de autenticação OAuth do Identity juntamente com o grant_type, que é definido como urn:ietf:params:oauth:grant-type:jwt-bearer pelos padrões JWT.

...

Se em algum momento o cliente perder o refresh_token, os mesmos passos acima podem ser seguidos para obter um refresh_token novo.


Obtendo um novo Access Token com o Refresh Token fornecido

...

Assim que o access_token expirar após uma hora, o refresh_token gerado na chamada mencionada acima pode ser utilizado para obter um novo access_token. Simplesmente faça uma chamada POST do refresh_token, como exemplificado abaixo, e o servidor do Identity irá responder com um novo access_token.

...

Bloco de código
languagejs
titleResposta
{
  "access_token": "45c1500f1d0c449d80013adceba9946e",
  "client_id": "fff0de39-a4b5-439f-8808-52213fce76b8",
  "timeIssuedInMillis": 1389657257807,
  "expires_in": 3599
}


Fazendo as chamadas com o Access Token

...

Uma vez que o access_token for recebido pelo cliente, todas as chamadas subsequentes que precisam ser feitas para acessar os dados da empresa irão exigir o access_token como parte do Cabeçalho de Autenticação. Aqui está um exemplo utilizando o plugin Poster no Firefox:

Com o cabeçalho de autenticação (access_token)

Deck of Cards
idChamadas com Access Token
Card
labelChamada

Cabeçalho

Card
labelResposta

Resposta

Bloco de código
languagejs
titleResposta com o cabeçalho de autenticação
collapsetrue
 {
   "id":"zyfmj7h41ntp556t",
   "itemName":"TOTVS LABS",
   "faxNumber":"650-666-6766",
   "emailAddress":"[email protected]",
   "address":"1161 Castro Street",
   "city":"Mountain View",
   "country":"USA",
   "state":"CA",
   "zip":"95067",
   "phoneNumber":"650-666-6766",
   "dateCreated":"Jan 13, 2014 2:42:17 PM",
   "createdBy":"7blpjw648d7ocjzo",
   "createdByName":"TOTVS Administrator",
   "subDomainName":"totvslabs.fluigidentity.com",
   "tokenRequired":false,
   "companyStatus":"CREATED",
   "emailDomains":[
   ],
   "customLogo":false,
   "selfSignUp":false,
   "adLoginEnabled":false,
   "adUserActivation":"ACTIVATION_BY_EMAIL",
   "adPasswordChangeEnabled":false,
   "userActivation":"EMAIL",
   "displayAdPwdReqEnabled":false,
   "adPwdRequirements":"",
   "oauthClientId":"fff0de39-a4b5-439f-8808-52213fce76b8",
   "companyId":"zyfmj7h41ntp556t"
}


Sem o cabeçalho de autenticação (access_token)

Bloco de código
languagejs
titleResposta sem o cabeçalho de autenticação
collapsetrue
{
   "errorCode":401,
   "errorMessage":"Provided access token is either null or empty or does
not have permissions to access this resource. Only PARTNERS can access this
api",
   "possibleResponsibleField":"accessToken: null"
}


Autenticação para as novas APIs REST

...

Para consultar as novas APIs do TOTVS Identity, não é mais usado o Client ID da empresa no Identity, mas sim usuário e senha de login no Identity;

...

Bloco de código
languagejs
titleResposta
{
  "token_type": "Bearer",
  "access_token": "146d5dcc023546c58932c3ee6bba735f",
  "expires_in": 600,
  "refresh_token": "18da38039b344fc6ac0b1e269ec89f8f"
}


Geração do token com usuário com MFA

Quando o usuário escolhido possui MFA a geração de token é feita em 2 etapas, a primeira é como passo anterior porém ao clicar em Try it out, o response será semelhante ao valor abaixo:

Bloco de código
languagejs
titleResposta
{
  "code": "IDM_MFA_0002",
  "message": "Multifactor authentication required - TOTP",
  "detailedMessage": "",
  "helpUrl": "http://tdn.totvs.com/display/fluig/MFAException#MFAException-IDM_MFA_0002",
  "mfa_token": "8fdb4e9cdc2b465988bad06e5d85f48a",
  "company_id": "zf0y84vo717g8hjx"
}


Para o segundo passo é usado o mesmo endpoint https://app.fluigidentity.com/api/auth/doc/#!/IDM_Auth_Api_-_V1/token, porém deve se alterar o grant_type para "http://fluigidentity.com/api/mfa/totp"

Image Added

O campo MFA_TOKEN é o token gerado na requisição anterior e o TOTP_TOKEN é o token do aplicativo ao clicar em Try it out, o response será semelhante ao valor abaixo:

Bloco de código
languagejs
titleResposta
{
  "token_type": "Bearer",
  "access_token": "146d5dcc023546c58932c3ee6bba735f",
  "expires_in": 600,
  "refresh_token": "18da38039b344fc6ac0b1e269ec89f8f"
}


Utilize o valor do access_token para realizar consultas nos endpoints da Nova API (core e auth). O valor do access_token precisa ser enviado no cabeçalho da requisição, da mesma forma que a requisição para a API antiga (descrito acima), no entanto, deve utilizar o scheme Bearer.

...

HTML
<!-- Hotjar Tracking Code for http://tdn.totvs.com/display/fb -->
<script>
    (function(h,o,t,j,a,r){
        h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
        h._hjSettings={hjid:5776551280165,hjsv:56};
        a=o.getElementsByTagName('head')[0];
        r=o.createElement('script');r.async=1;
        r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
        a.appendChild(r);
    })(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv=');
</script>