Índice

Objetivo

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

...

O esquema de autenticação e autorização das APIs REST V2 do fluig Identity são baseadas no padrão de autenticação servidor a servidor OAuth2OAuth 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 OAuth2OAuth 2.0 e JWT.

• fluig Identity API REST: https://app.fluigidentity.com/rest/swagger-ui/index.html#!/companies
• Biblioteca Java:   rest-client-1.5.7.1.jar

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. Mais informações sobre JWT e OAuth2OAuth 2.0 podem ser achadas em:

• JWT Draft: http://tools.ietf.org/html/draft-jones-oauth-jwt-bearer-04
• OAuth2OAuth 2.0 Draft: http://tools.ietf.org/html/draft-ietf-oauth-v2-31
• Google’s JWT usage with OAuth2.0: https://developers.google.com/accounts/docs/OAuth2ServiceAccount

Escopo do fluig Identity para APIs REST

O fluig Identity foi desenvolvido ao redor do conceito de "empresas". Cada empresa possui seu próprio subdomínio (Ex: 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 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 dados da empresa: identificador do cliente, identificador da empresa e uma chave privada. Um O administrador corporativo possui acesso a esses recursos no console do administrador corporativo no menu de Configuração do fluig Identity.

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 fornecida pelo desenvolvedor.

que você forneceu. 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 partes, cada uma separada por um " . "[ponto]).:

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

Enviando/publicando o JWT para o fluig 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 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 CCabeç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
{ "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 do fluig 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"
}

...