O objetivo deste guia é apresentar a API REST para desenvolvedores.
A documentação a seguir fornece uma introdução às APIs REST V2 do fluig Identity.
Para quem é voltada esta documentação?
Desenvolvedores de uma empresa que seja cliente do fluig 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 fluig Identity.
O que eu devo saber?
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 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.
A plataforma REST do fluig Identity é baseada nos padrões OAuth 2.0 com JWT (JSON Web Token) para estabelecer a comunicação servidor-a-servidor entre aplicativos.
Mais informações sobre JWT e OAuth 2.0 podem ser achadas em:
O fluig 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 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.
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. O administrador corporativo possui acesso a esses recursos no menu de Configuração do fluig Identity.
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.
O JSON Web Token deverá se parecer com o seguinte:
{ “iss”: “INSIRA_O_CLIENT_ID_AQUI”}
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.
Em condições ideais, recomendamos fortemente que 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 JWT:
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 se encarrega de toda a criptografia base e assina o jwtClaim com a chave privada fornecida 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 exemplo abaixo (3 partes, cada uma separada por um . [ponto]):
eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJmZmYwZGUzOS1hNGI1LTQzOWYtODgwOC01MjIxM2ZjZTc2YjgifQ.aneQAKQ0aO60bUN5WaeG5ZFTb6L4OA_rbO0x5XEV_6pi0bk8B2oW1gegOYtp3TKIRcN1dYr550sX1BnJJgr5WhVQhyiHbGCDDIN_cj2e6uMftqEpc7df900YVm5V-jSQXJLVUJbZb0GlFcuE3Jn3Un6vBoCnziVIcnyG-u-JJ88 |
A assertion gerada no passo acima precisa ser publicada na URL de autenticação 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
O servidor do fluig Identity irá verificar o JWT e sua assinatura e então irá responder com um JSON, onde:
{
"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, os mesmos passos acima podem ser seguidos para obter um refresh_token novo.
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 fluig Identity irá responder com um novo access_token.
A URL para publicar o refresh_token é: http://{hostname}/rest/v2/oauth2/token
O servidor irá responder com o seguinte JSON:
{
"access_token": "45c1500f1d0c449d80013adceba9946e",
"client_id": "fff0de39-a4b5-439f-8808-52213fce76b8",
"timeIssuedInMillis": 1389657257807,
"expires_in": 3599
} |
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:
|
{
"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"
} |
