OAuth 2.0

OAuth 2.0 é um protocolo de autorização de padrão aberto que permite a terceiros (aplicações) acessarem dados de um usuário sem a obrigatoriedade de informar suas credênciais. Portanto, APPs usam essa método para obter acesso a conta e dados de um determinado usuário através de um Client ID ou Secret (chaves de autenticação do OAuth). Caso queira saber mais, visite o site: http://oauth.net/2/.

Tipos de Clientes

No OAuth temos dois tipos de clientes:

  • Cliente confidencial: São clientes que conseguem garantir que nenhum usuário mal intencionado irá obter um Secret ou Client ID para tentar se passar por uma aplicação válida.

  • Cliente não confidencial - são clientes que não conseguem garantir que um usuário mal intencionado irá obter seu Secret ou Client ID para tentar se passar por uma aplicação válida. Nesses casos é passado uma URL de callback para garantir que as informações só retornem ao verdadeiro APP, ou, também, pode ser diminuído o tempo de vida útil do Client ID com a utilização de um Refresh Token.

Formas de obter um Access Token

OAuth 2.0 Authorization Code

Primeiramente, é necessário ter uma APP criada. Com esta APP, nós temos acesso ao Client ID, que será o primeiro item a ser passado no endpoint a seguir, via POST:

Endpoint => <url do gateway>/oauth/grant-code

O cabeçalho deve conter a seguinte informação:

Header => Content-Type : application/json

No corpo, devemos enviar os seguintes itens:

{
"client_id": "f9212173-e705-373b-a698-61923e378359",
"extraInfo": {},
"redirect_uri": "string",
"state": "string"
}

OBS.: O clientId a ser passado deve ser o mesmo da APP criada.

Feito isso, espera-se uma resposta com um “authorization code”, conforme exibido abaixo:

{
"redirect_uri": "string?state=string&code=8748d39f-1d4f-311f-92c6-4b279db1b317"
}

Em seguida, deve-se realizar um novo POST no seguinte endpoint:

Endpoint => <url do gateway>/oauth/access-token

O cabeçalho deve conter as seguites informações:

Header => Authorization : Basic client_id:client_secret

OBS.: Este client_id:client_secret deve ser uma string convertida em Base64, usando os dados da APP criada.

O exemplo do cabeçalho com o client_id e secret convertidos para base64, seria:

Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==

No corpo, devemos passar o “authorization code” gerado pelo endpoint anterior, com mais alguns itens, no formato x-www-form-urlencoded:

"grant_type": "authorization_code"
"code" : "8748d39f-1d4f-311f-92c6-4b279db1b317"

Por fim, o Access Token será gerado e retornará o seguinte código abaixo:

{
"access_token": "57f10f0e-3d2e-311f-a797-4011f66e1cbf",
"refresh_token": "ca81cb16-43e4-3e96-aaea-4861e7791dc7",
"token_type": "access_token",
"expires_in": 3600
}

OAuth 2.0 Refresh Token

O Refresh Token será utilizado para criar um novo access_token que foi expirado.

Para isso, basta seguir os passos abaixo:

Faça um POST no seguinte endpoint:

Endpoint => <url do gateway>/oauth/access-token

O cabeçalho deve conter as seguites informações:

Header => Authorization : Basic client_id:client_secret

OBS.: Este client_id:client_secret deve ser uma string convertida em Base64, usando os dados da APP criada.

O exemplo do cabeçalho com o client_id e secret convertidos para base64, seria:

Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==

No corpo, devemos passar o “refresh_token” gerado pelo endpoint anterior, com mais alguns itens, no formato x-www-form-urlencoded:

"grant_type": "refresh_token"
"refresh_token" : "ca81cb16-43e4-3e96-aaea-4861e7791dc7"

Por fim, o Access Token será gerado novamente e retornará o seguinte código abaixo:

{
"access_token": "ca81cb16-43e4-3e96-aaea-4861e7791dc7",
"refresh_token": "677b881a-d0b6-3b29-b9a8-f0cdb50ce035",
"token_type": "access_token",
"expires_in": 3600
}

OAuth 2.0 Implicit

O fluxo Implicit é usado para obter tokens de accesso de forma otimizada para clientes públicos, ele pode operar por uma URI de redirecionamento particular, acompanhado do Access Token. Esses clientes são normalmente implementados em um navegador usando uma linguagem de script, como JavaScript.

Da mesma forma que em “OAuth 2.0 Authorization Code”, é necessário que a APP esteja criada para que possamos ter acesso ao Client ID. Feito isso, é necessário fazer um POST no seguinte endpoint:

Endpoint => <url do gateway>/oauth/access-token

O cabeçalho deve conter a seguinte informação:

Header => Content-Type : application/json

E no corpo, devemos enviar os seguintes itens:

{
"client_id": "f9212173-e705-373b-a698-61923e378359",
"redirect_uri": "http://www.url.com",
"grant_type": "implicit"
}

OBS.: O clientId a ser passado deve ser o mesmo da APP criada.

Acabado o processo, espera-se uma resposta com a URI e o Access Token, conforme exibido abaixo:

{
"redirect_uri": "www.url.com?access_token=57f10f0e-3d2e-311f-a797-4011f66e1cbf",
"expires_in": 3600
}

OAuth: Client Credentials

Assim como no Implicit, o Client Credentials também NÃO gera o "refresh_token", portanto, não é possível criar um novo Access Token quando ele expirar.

Quando utilizado, ao criar um novo access token, o nome da APP e seu Client ID são inseridos no campo "Extra Info" do Access Token, bem como todos os "Extra Infos" que estiverem cadastrados na APP.

Da mesma forma que em “Authorization Code”, é necessário que a APP esteja criada para que possamos ter acesso ao Client ID e ao Secret. Em seguida, é necessário fazer um POST no seguinte endpoint:

Endpoint => <url do gateway>/oauth/access-token

O cabeçalho deve conter as seguites informações:

Header => Authorization : Basic client_id:client_secret

OBS.: Este client_id:client_secret deve ser uma string convertida em Base64, usando os dados da APP criada.

O exemplo do cabeçalho com o client_id e secret convertidos para base64, seria:

Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==

No corpo, devemos passar o “grant_type” no formato x-www-form-urlencoded:

"grant_type": "client_credentials"

Por fim, o seu Access Token será gerado e deverá aparecer como no exemplo abaixo:

{
"access_token": "6c164a82-84a6-3bc4-8122-f777121a4f62",
"token_type": "access_token",
"expires_in": 3600
}

É possível também criar novos extra fields na criação do Access Token. Para isso, é necessário adicionar ao cabeçalho o seguinte header:

Header => Content-Type : application/json

No corpo, devemos passar o “grant_type” e os extra fields:

{
"grant_type": "client_credentials",
"extraInfo": {"value": "32423", "value2": "874yhgt3"}
}

OAuth 2.0 Password

Da mesma forma que o “Authorization Code”, é necessário que a APP esteja criada para que possamos ter acesso ao Client ID e ao Secret. Depois disso, é necessário fazer um POST no seguinte endpoint:

Endpoint => <url do gateway>/oauth/access-token

O cabeçalho, igualmente ao método anterior, precisa ter o client_id e o client_secret em base64:

Header => Authorization : Basic client_id:client_secret

OBS.: Este client_id:client_secret deve ser uma string convertida em Base64, usando os dados da APP criada.

O corpo precisa, além do “grant_type", de mais duas informações que utilizam o userDirectory. Essas informações são, o login e a senha do usuário, que podem ser de um LDAP ou de um REST, e devem ser no formato x-www-form-urlencoded também:

"grant_type" : "password",
“username” : “USUARIO”,
“password” : “SENHA”

Se o usuário e senha forem válidos na LDAP ou no REST, o retorno do Access Token deve ser semelhante ao modelo a seguir:

{
"access_token": "6c164a82-84a6-3bc4-8122-f777121a4f62",
"token_type": "refresh_token",
"expires_in": 3600
}

IMPORTANTE: Para que as funcionalidades acima estejam presentes no seu APP, é necessário configurar o OAuth Directory. No caso de LDAP o usuario informado deve estar no formato User-Principal-Name. Ex:test@da.sa

A propriedade oauth.grantTypes.resourceOwnerPassword.userDirectory não é mais necessária.

JWT

"JSON Web Token (JWT) é um padrão aberto (RFC 7519) que define uma forma compacta e auto-suficiente para a transmissão segura de informações entre as partes como um objeto JSON. Esta informação pode ser verificada e confiável porque é assinado digitalmente. JWTs pode ser assinado usando um segredo (com o algoritmo HMAC) ou um par de chaves pública / privada usando RSA." https://jwt.io/

No JWT também é necessário que a APP esteja criada para que tenhamos acesso ao Client ID e ao Secret. Para isso, é necessário fazer um POST no seguinte endpoint:

Endpoint => <url do gateway>/oauth/access-token

O cabeçalho deve conter as seguites informações:

Header => Authorization : Basic client_id:client_secret

OBS.: Este client_id:client_secret deve ser uma string convertida em Base64, usando os dados da APP criada.

O exemplo do cabeçalho com o client_id e secret convertidos para base64, seria:

Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==

No corpo, devemos passar o “code” gerado pelo endpoint de grant-code, com mais alguns itens, no formato x-www-form-urlencoded:

"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer"
"code" : "8748d39f-1d4f-311f-92c6-4b279db1b317"

Por fim, o seu Access Token será gerado novamente e deverá aparecer conforme o exemplo abaixo:

{
"access_token": "ca81cb16-43e4-3e96-aaea-4861e7791dc7",
"refresh_token": "677b881a-d0b6-3b29-b9a8-f0cdb50ce035",
"token_type": "access_token",
"expires_in": 3600
}

Com código gerado, será necessário adicionar o interceptor de JWT no fluxo da API. Esse será reponsável para verificar se o JWT é valido.

OpenID

"OpenID permite que você use uma credencial existente para acessar diversos sites, sem a necessidade de criação de novas senhas. [...] Com o OpenID, sua senha é fornecida apenas a um provedor de identificação. Então, este provedor confirma sua identidade e concede acesso aos sites que você visitar. Além do seu provedor, nenhum website pode ver suas senhas, portanto você não precisa se preocupar com sistemas inseguros comprometendo sua identidade." http://openid.net/

Para utilizar o OpenID, é necessário algumas configurações que devem ser executadas pelo time de Suporte da SENSEDIA.

É necessário, também, ter uma APP criada. Com esta APP, nós temos acesso ao Client ID, que será o primeiro item a ser passado no endpoint a seguir, via POST:

Endpoint => <url do gateway>/oauth/google/openid/redirect

O cabeçalho deve conter a seguinte informação:

Header => Content-Type : application/json
Header => client_id : client_id

No corpo, devemos enviar o seguinte item:

{
"extraInfo": {}
}

OBS.: O clientId a ser passado deve ser o mesmo da APP criada.

Feito isso, espera-se uma resposta com um “authorization code” conforme exibido abaixo:

{
"redirect_uri": "string?queryParams"
}

Em seguida, deve-se acessar sua redirect_uri, ele da acesso a uma página de autênticação do seu provider. Ao realizar o login será redirecionado automaticamente com os valores do Access Token.

REFERÊNCIA GERAL: https://tools.ietf.org/html/rfc6749.