Índice

...

Visão Geral

...

O objetivo deste guia é apresentar a API REST para desenvolvedores.

Visão Geral

A documentação a seguir fornece uma introdução às APIs REST V2 do fluig 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.

...

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

Dependendo do caso de uso, o cliente (empresas ou parceiros) terá suas chaves privadas dedicadas para assinar/criptografar seu token JWT e enviá-lo para autorização para conseguir um access_token e um refresh_token.

Para mais detalhes, sinta-se à vontade para pesquisar sobre

...

OAuth 2.0 e JWT.

...

• Identity API REST

...

• Biblioteca Java

...

• (rest-client-1.5.7.1.jar

...

• )
• Nova API REST TOTVS Identity (core)
• Nova API REST TOTVS Identity (auth)

...

Plataforma

...

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

...

...

...

...

...

Escopo do

...

Identity para APIs REST

...

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

Cada empresa possui um client-id 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 as aos dados da empresa: identificador  identificador do cliente (ID do Cliente/client Id), identificador da empresa e uma chave privada. Um administrador corporativo possui acesso a esses recursos no console do administrador corporativo no fluig Identity.

Image Removed

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

Image Added 

Crie/Assine o JWT

...

Criando JWT

Um JWT (JSON web tokenWeb 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 (definição de "iss"). O . O campo "iss" deve receber o valor do client - id da empresa.

Então, o seu JSON web token deverá ser parecido O JSON Web Token deverá se parecer com o seguinte:

{ “iss”: “INSIRA_O_CLIENT_ID_AQUI”}

...

Assinando o JWT

A assinatura do token JWT necessita de 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.

Em condições ideais, nós recomendamos fortemente que você utilize sejam utilizadas bibliotecas open source que já estejam disponíveis para fazer a assinatura do token JWT. Uma destas bibliotecas é a spring-security-jwt (que o fluig Identity utiliza em seu servidor).

Aqui está um exemplo de código de como criar e assinar um jwtJWT:

private PrivateKey getPrivateKeyFromPk8File(String pkcs8FilePath) throws fluigIdentityException
{
    try
    {
          FileInputStream fis = new FileInputStream(pkcs8FilePath);
          byte[] buf = IOUtils.toByteArray(fis);
          fis.read(buf);
          fis.close();
          PKCS8EncodedKeySpec kspec = new PKCS8EncodedKeySpec(buf);
          KeyFactory kf = KeyFactory.getInstance("RSA");
          return kf.generatePrivate(kspec);
    }
    catch (IOException | NoSuchAlgorithmException | InvalidKeySpecException ex)
    {
        throw new fluigIdentityException(Response.Status.INTERNAL_SERVER_ERROR.getStatusCode(),
              ex.getMessage(), "generateAssertion clientId: " + clientId);
     }
}
String jwtClaim = "{\"iss\": \"INSIRA_O_CLIENTE_ID_AQUI\"}";
Jwt encoded = JwtHelper.encode(jwtClaim, new RsaSigner((RSAPrivateKey)
getPrivateKeyFromPk8File("CAMINHO_PARA_O_ARQUIVO_PKCS8_CONTENDO_A_CHAVE_PRIVADA"));
String assertion = encoded.getEncoded();

...

O JwtHelper é (utilizado no código acima) é uma classe de ajuda da biblioteca spring-security-jwt que toma conta de todas as criptografias se encarrega de toda a criptografia base e assina o seu jwtClaim com a chave privada que você forneceufornecida pelo desenvolvedor. O uso desta biblioteca ajuda o desenvolvedor a não se preocupar com questões de segurança e se concentrar apenas em fazer as chamadas REST.

A string assertion deve se parecer com o seguinte exemplo abaixo (3 três partes, cada uma separada por um "ponto [."]).:

eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJmZmYwZGUzOS1hNGI1LTQzOWYtODgwOC01MjIxM2ZjZTc2YjgifQ.aneQAKQ0aO60bUN5WaeG5ZFTb6L4OA_
rbO0x5XEV_6pi0bk8B2oW1gegOYtp3TKIRcN1dYr550sX1BnJJgr5WhVQhyiHbGCDDIN_cj2e6uMftqEpc7df900YVm5V-
jSQXJLVUJbZb0GlFcuE3Jn3Un6vBoCnziVIcnyG-u-JJ88

...

Enviando/publicando o JWT para o

...

Identity

...

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

A URL para publicar estes dados é: http://{hostname}/rest/v2/oauth2/auth

O {hostname} para o servidor de produção do fluig Identity será https://app.fluigidentity.com

 

Image Modified

 

O servidor do fluig Identity irá verificar o JWT e sua assinatura e então irá responder com o seguinte JSON:

...

language	js

...

um JSON, onde:

• refresh_token:   token utilizado para conseguir obter um access_token novotoken novo, quando o antigo access_token expirar

• access_token:   token utilizando para fazer todas as chamadas API REST. O access_token faz parte do Cabeçalho de Autenticação em todas as requisições API REST

• client_id: REST client-id do Cliente

• timeIssuedInMillis: Quando  Quando o access_token/refresh_token foi requisitado, em milissegundos.

• expires_in: Quando  Quando o access_token expira. Atualmente, o access_token expira em 3600 segundos = 1 horasegundos (1 hora)

Bloco de código
language js title Resposta
{ "refresh_token": "f6b54eb7dbd549868790bd94c50ba486", "access_token": "21552c08d0ee48b2a3c6312e49283b36", "client_id": "fff0de39-a4b5-439f-8808-52213fce76b8", "timeIssuedInMillis": 1389656667980, "expires_in": 3600 }

Se em algum momento o cliente perder o refresh_token, eles podem seguir os mesmos passos acima podem ser seguidos para conseguir 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 conseguir obter um novo access_token. Simplesmente faça uma chamada POST do refresh_token, como exemplificado abaixo, e o servidor fluig do Identity irá responder a chamada com um novo access_token.

A URL para publicar o refresh_token é: http://{hostname}/rest/v2/oauth2/token 

Image Modified 

O servidor irá responder com o seguinte JSON:

{
  "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 Cabeçalho de " Autenticação". Aqui está um exemplo utilizando o plugin Poster no Firefox:

Com o

...

cabeçalho de

...

autenticação (access_token)

 {
   "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)

{
   "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;

Acesse o endpoint https://app.fluigidentity.com/api/auth/doc/#!/IDM_Auth_Api_-_V1/token e preencha os campos username, password e domain (subdomínio do seu Identity):

Image Added

Após clicar em Try it out, o response será semelhante ao valor abaixo:

{
  "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:

{
  "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:

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

Este token terá validade de 10 minutos, para renová-lo, altere o grant_type do endpoint para refresh_token e preencha o campo refresh_token com o valor gerado anteriormente.

<!-- 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:1280165,hjsv:6};
        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>