Criar uma aplicação OAuth2 no XFA

Uma aplicação OAuth2 no XFA acrescenta a verificação do dispositivo a um fluxo de início de sessão OAuth2. O XFA fica entre a sua aplicação e o identity provider, verifica o dispositivo durante o início de sessão e só encaminha o utilizador quando a decisão da sua política permite o acesso. Use-o para introduzir os valores certos e testar o fluxo de início de sessão.

Como funciona

Depois de configurado, quando um utilizador inicia sessão numa aplicação com OAuth2:

Aplicação → identity provider: a aplicação encaminha o utilizador para o seu identity provider (por exemplo, o Google Workspace ou o Okta) para se autenticar. Como o redirect_uri foi definido para o endpoint do XFA (ver o passo 4 abaixo), o identity provider devolve o utilizador ao XFA depois da autenticação.
Identity provider → XFA: depois da autenticação, o identity provider encaminha o utilizador de volta para o redirect URL do XFA, juntamente com o authorization code.
O XFA verifica o dispositivo: o XFA compara o estado de segurança do dispositivo com a sua política. Se o dispositivo não cumprir a política, o acesso é negado.
Troca do token, aplicação → XFA → identity provider: se o dispositivo passar, o XFA encaminha o utilizador de volta para a aplicação com o authorization code. A aplicação troca depois esse código por um access token através do token endpoint do XFA, que reencaminha o pedido de forma transparente para o token endpoint do seu identity provider. O XFA usa essa troca para ligar o utilizador autenticado ao seu dispositivo. O token devolvido à aplicação não é alterado: o XFA não lhe mexe.

O que configurar e onde

Onde	O que configurar
Aplicação (definições OAuth2)	Substitua o `redirect_uri` pelo XFA Redirect URL
XFA	Integration Name, o Redirect URL original da sua aplicação e o Token Endpoint do identity provider

Nota: este artigo parte do princípio de que a sua organização tem uma conta XFA e de que é administrador dessa organização. Se não tiver conta, pode criar uma em https://dashboard.xfa.tech/signup.

2. Crie uma nova aplicação em Enforcement > Novo > OAuth2 Integration

Criar uma nova aplicação

3. Preencha as definições OAuth2

Definições no XFA

Integration Name: um nome descritivo para esta integração
Redirect URL: o redirect URL original da sua aplicação, para onde o XFA encaminha o utilizador depois da verificação do dispositivo
Token Endpoint: o token endpoint OAuth2 do seu identity provider, que o XFA usa para trocar o authorization code por um access token (por exemplo, https://accounts.google.com/o/oauth2/token para o Google Workspace, ou https://<your-domain>/oauth2/v1/token para o Okta)

Clique em Guardar para guardar a sua integração.

Preencher as definições OAuth2

4. Atualize as definições OAuth2 da sua aplicação

Depois de guardar, copie o XFA Redirect URL que aparece nos detalhes da integração. Na configuração OAuth2 da sua aplicação, substitua o redirect_uri existente por esse XFA Redirect URL. Assim, depois da autenticação, o identity provider devolve o utilizador ao XFA para a verificação do dispositivo, em vez de o devolver diretamente à aplicação.

5. Teste a ligação

Teste o fluxo de início de sessão entrando através da aplicação. O navegador deve ser encaminhado para o seu identity provider para autenticação, depois para o XFA para a verificação do dispositivo, e só então de volta para a aplicação.

Executar a verificação do dispositivo antes do authorize (para authorization codes de vida curta)

Por predefinição, o XFA executa a sua verificação do dispositivo depois de o identity provider devolver o authorization code, mesmo antes de trocar esse código no Token Endpoint (ver Como funciona acima). Alguns identity providers emitem authorization codes que expiram muito depressa. Se a verificação do dispositivo demorar mais tempo do que o código se mantém válido, por exemplo quando o utilizador ainda tem de instalar o agente XFA, a troca do token pode falhar com um erro invalid_grant e o utilizador vê uma falha de autenticação. Com o handler OpenID Connect da Microsoft, a mesma situação pode surgir como um erro IDX21106, "Failed to parse token response body as JSON".

Nesses providers, o XFA pode em alternativa executar a verificação do dispositivo antes de encaminhar o utilizador para o identity provider. O authorization code do provider só é então emitido depois de a verificação passar, pelo que é trocado em poucos segundos e fica bem dentro do seu tempo de vida.

Esta opção é opcional e aplica-se apenas à integração de proxy OAuth2 descrita nesta página. Se deixar o novo campo vazio, o XFA mantém o comportamento predefinido (verificação do dispositivo depois de o código ser devolvido).

Ativar a verificação do dispositivo antes do authorize

Na sua integração OAuth2 no painel XFA, defina o novo campo Authorize Endpoint of Provider com o endpoint de autorização OAuth2/OIDC do seu identity provider. É o mesmo authorize URL para onde a sua aplicação aponta hoje, por exemplo https://<your-domain>/oauth2/v1/authorize.
Na configuração OAuth2 da sua aplicação, altere o URL de autorização (AuthUrl) para que aponte para o ponto de entrada authorize do XFA em vez de apontar diretamente para o identity provider:
```
https://device-api.xfa.tech/<applicationId>/oauth2/authorize
```
Substitua <applicationId> pelo ID da sua aplicação XFA.

Todo o resto se mantém igual. O redirect URI da sua aplicação, o registo do cliente junto do identity provider e o Token Endpoint no XFA ficam todos inalterados.

O que muda

XFA: defina Authorize Endpoint of Provider com o authorize URL do provider
Aplicação: faça o AuthUrl apontar para https://device-api.xfa.tech/<applicationId>/oauth2/authorize
Inalterado: o redirect URI, o registo do cliente junto do provider e o Token Endpoint

Reverter

Para voltar ao comportamento predefinido, faça o AuthUrl da sua aplicação apontar de novo para o endpoint de autorização do identity provider. Se deixar o campo Authorize Endpoint of Provider vazio no XFA, volta o fluxo em que a verificação do dispositivo acontece depois do authorize.

1. Inicie sessão no painel XFA