O OAuth 2.0 é um padrão criado para permitir que um site ou aplicativo acesse recursos hospedados por outros aplicativos da Web em nome de um usuário. O OAuth 2.0 é amplamente reconhecido no campo de autenticação e autorização em aplicativos da Web e móveis e fornece uma maneira segura de obter autorização para acessar recursos protegidos em nome de um usuário.

A API FRACTTAL usa o OAuth 2.0 como protocolo de autenticação para garantir a segurança de todas as solicitações HTTP. Esse tipo de autenticação oferece dois tipos de autorização: Credenciais do cliente e Código de autorização. Ambos os tipos permitem que os clientes obtenham tokens de acesso para autenticar suas solicitações.

Configuração no Fracttal One

Para usar a autenticação OAuth 2.0 na API FRACTTAL, é necessário configurar os Consumidores OAuth no Fracttal One. Isso pode ser feito acessando a seção Configuration e, em seguida, selecionando API Connections no menu lateral e, finalmente, a guia OAuth Consumers. Encontre um exemplo aqui

É importante observar que cada consumidor OAuth configurado deve ser associado a um grupo de permissões, independentemente do tipo de autorização selecionado. Esses grupos de permissão fornecem controle granular sobre quais recursos podem ser acessados e quais ações podem ser executadas.

Além disso, cada consumidor deve ter um nome e, opcionalmente, uma descrição que permita sua identificação para uma melhor administração.

Além disso, há campos configuráveis que variam de acordo com o tipo de autorização selecionado.

Credenciais do cliente

Para configurar um consumidor usando Customer Credentials como tipo de autorização, os únicos campos obrigatórios são o Name e o Permission Group. Além disso, pode ser fornecida uma Description do consumidor.

Depois que esses campos forem preenchidos, uma Key e uma Secret serão geradas ao salvar a configuração, que será usada para obter o token de autenticação.

Código de autorização

Para configurar um consumidor usando Authorisation Code como tipo de autorização, além do Name e do Permission Group, será necessário indicar um URL de redirecionamento no campo Direct URL. Opcionalmente, uma Description do consumidor pode ser fornecida, além do URL, do Privacy Policy URL e do End User Licence Agreement URL.

Depois que esses campos forem preenchidos, uma Key e um Secret serão gerados ao salvar a configuração, que será usada para obter o token de autenticação.

Obtenção do token

O URL para obter o token é https://one.fracttal.com/oauth/token.

Credenciais do cliente

Ao usar esse tipo de autorização, o token é obtido da seguinte forma:

curl -X POST -u "clave:secreto" https://one.fracttal.com/oauth/token -d grant_type=client_credentials

{
	"access_token":"******",
	"token_type":"Bearer",
	"expires_in":7200,
	"refresh_token":"***",
	"state":"client_credentials"
}

Ao executar o comando, substitua key e secret pelos valores obtidos ao configurar o consumidor OAuth.

Código de autorização

Ao usar esse tipo de autorização, primeiro solicite a autorização do usuário final enviando o navegador dele para https://one.fracttal.com/oauth/authorize.

O retorno de chamada incluirá o parâmetro de consulta ?code={authorisation_code}, que será necessário para obter o token, da seguinte forma:

curl -X POST -u "clave:secreto" https://one.fracttal.com/oauth/token -d grant_type=authorization_code -d code=código_de_autorización

{
  "access_token":"*****",
  "token_type":"Bearer",
  "expires_in":7200,
  "refresh_token":"***",
  "state":"authorization_code"
}

Ao executar o comando, substitua key e secret pelos valores obtidos ao configurar o consumidor OAuth no Fracttal One, e authorisation_code pelo código obtido no retorno de chamada da etapa anterior.

Envio de solicitações

Depois de obter um token de acesso, a maneira recomendada e conveniente de incluí-lo em suas solicitações é enviá-lo no cabeçalho da solicitação, adicionando o seguinte:

Campo	Valor	Descrição
`Authorization`	Bearer {access_token}	Token de autorização ao usar o OAuth2

Substitua {access_token} pelo valor real do token de acesso.

Ao incluir o token no cabeçalho da solicitação, é importante certificar-se de usar o esquema de autenticação "Bearer" para indicar que um token de acesso está sendo enviado. Isso permitirá que o servidor identifique e autentique corretamente a solicitação.

Atualização do token

Ao usar a API FRACTTAL, é importante observar que os tokens de acesso têm uma vida útil de duas horas e expirarão após esse período. Quando um token de acesso expirar, você receberá uma resposta com o código de status 401 (Não autorizado).

Para facilitar a renovação dos tokens de acesso sem exigir a intervenção do usuário final, as respostas de concessão de token de acesso incluem um token de atualização, no campo "refresh_token". Esse token de atualização pode ser usado para solicitar um novo token de acesso, da seguinte forma:

curl -X POST -u "clave:secreto" https://one.fracttal.com/oauth/token -d grant_type=refresh_token -d refresh_token=token_de_actualización

O update_token deve ser substituído pelo valor real do token de atualização.

É importante usar o token de atualização de forma segura e garantir que ele esteja protegido contra acesso não autorizado, pois seu comprometimento poderia permitir que terceiros obtivessem acesso a recursos protegidos.