Criar uma aplicação OpenID Connect (OAuth 2.0) no XFA

Uma aplicação OpenID Connect (OIDC) no XFA acrescenta a verificação do dispositivo a um início de sessão OpenID Connect. O OpenID Connect é a camada de identidade sobre o OAuth 2.0: nos seus termos, a sua aplicação é a Relying Party e o seu identity provider é o OpenID Provider. O XFA fica entre os dois, 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 esta página 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 o Authorization Code Flow do OpenID Connect:

Aplicação → OpenID Provider: a aplicação envia o utilizador para o Authorization Endpoint do seu OpenID 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 OpenID Provider devolve o utilizador ao XFA depois da autenticação.
OpenID Provider → XFA: depois da autenticação, o OpenID Provider encaminha o utilizador para o Redirect URI 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.
Token Request, aplicação → XFA → OpenID Provider: se o dispositivo passar, o XFA encaminha o utilizador de volta para a aplicação com o authorization code. A aplicação envia depois o seu Token Request para o Token Endpoint do XFA, que o reencaminha de forma transparente para o Token Endpoint do seu OpenID Provider. O XFA lê a claim email do ID Token na Token Response para ligar o utilizador autenticado ao seu dispositivo. Os tokens devolvidos à aplicação não são alterados: o XFA não lhes mexe.

O que configurar e onde

Onde	O que configurar
Aplicação (definições OpenID Connect)	Substitua o `redirect_uri` pelo XFA Redirect URI
XFA	Integration Name, o Redirect URI original da sua aplicação e o Token Endpoint do OpenID 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 > Integração OpenID Connect (OAuth 2.0)

Criar uma nova aplicação

3. Preencha as definições OpenID Connect

Definições no XFA

Integration Name: um nome descritivo para esta integração
Redirect URI: o Redirect URI (redirect_uri) original da sua aplicação, para onde o XFA encaminha o utilizador depois da verificação do dispositivo
Token Endpoint: o Token Endpoint do seu OpenID Provider, que o XFA usa para trocar o authorization code pelo ID Token e pelo 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 OpenID Connect

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

Depois de guardar, copie o XFA Redirect URI que aparece nos detalhes da integração. Na configuração OpenID Connect da sua aplicação, substitua o redirect_uri existente por esse XFA Redirect URI. Assim, depois da autenticação, o OpenID 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 OpenID 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 OpenID Provider devolver o authorization code, mesmo antes do Token Request ao Token Endpoint (ver Como funciona acima). Alguns OpenID 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, o Token Request 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 enviar o Authentication Request ao OpenID 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 OpenID Connect 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 OpenID Connect no painel XFA, defina o campo Endpoint de autorização do OpenID Provider com o Authorization Endpoint do seu OpenID Provider. É o mesmo URL de autorização para onde a sua aplicação aponta hoje, por exemplo https://<your-domain>/oauth2/v1/authorize.
Na configuração OpenID Connect da sua aplicação, altere o Authorization Endpoint (AuthUrl) para que aponte para o ponto de entrada authorize do XFA em vez de apontar diretamente para o OpenID Provider:
```
https://device-api.xfa.tech/<applicationId>/oauth2/authorize
```
Substitua <applicationId> pelo ID da sua aplicação XFA.
Na configuração OpenID Connect da sua aplicação, volte a definir o redirect_uri com o Redirect URI próprio da sua aplicação. Tem de corresponder exatamente ao Redirect URI que introduziu no XFA.
No seu OpenID Provider, mantenha o XFA Redirect URI nos redirect URIs permitidos do seu cliente. O XFA envia-o ao OpenID Provider em vez do Redirect URI próprio da sua aplicação.

O ID e o segredo do seu cliente e o Token Endpoint no XFA ficam inalterados.

Se a sua aplicação já envia o XFA Redirect URI como redirect_uri neste fluxo, continua a funcionar. Recomendamos que mude para o Redirect URI próprio da sua aplicação.

O que muda

XFA: defina Endpoint de autorização do OpenID Provider com o Authorization Endpoint do provider
Aplicação: faça o AuthUrl apontar para https://device-api.xfa.tech/<applicationId>/oauth2/authorize e envie o Redirect URI próprio da sua aplicação como redirect_uri
OpenID Provider: permita o XFA Redirect URI como redirect URI
Inalterado: o ID do cliente, o segredo do cliente e o Token Endpoint

Reverter

Para voltar ao comportamento predefinido, faça o AuthUrl da sua aplicação apontar de novo para o Authorization Endpoint do OpenID Provider. Volte também a definir o redirect_uri da sua aplicação com o XFA Redirect URI, como no fluxo predefinido. Se deixar o campo Endpoint de autorização do OpenID 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