Configurar o XFA como fator de autenticação no Keycloak

Configure o XFA no Keycloak para acrescentar a verificação do dispositivo depois de o utilizador se autenticar. O XFA corre como passo pós-início de sessão, verifica o dispositivo face à política configurada e deixa o início de sessão continuar quando a decisão sobre o dispositivo permite o acesso. Use-o para confirmar as definições necessárias e testar o fluxo de autenticação antes da implementação.

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

Criar uma integração no painel XFA

Depois de iniciar sessão no painel XFA, vá à página Enforcement, clique em Novo e escolha Keycloak como tipo de integração.

A página mostra vários valores de que vai precisar nos passos seguintes (Client ID, Client Secret e os endpoints OpenID Connect). Contém também um campo Redirect URI que vai preencher com um valor do Keycloak durante os passos abaixo.

Mantenha esta página aberta durante os passos seguintes.

Por predefinição, o Keycloak não passa a identidade do utilizador já autenticado a um Identity Provider externo. O XFA precisa dessa identidade (o e-mail do utilizador) para saber que dispositivo verificar. Um pequeno provider open source para o Keycloak trata disso: lê o utilizador autenticado da sessão e define o parâmetro login_hint no encaminhamento para o XFA. O provider está disponível em github.com/gl-ventures/xfa-keycloak-login-hint-mapper.

Clone o repositório do provider e compile-o (ou obtenha o jar já compilado):
```
mvn clean package
```
Copie o ficheiro login-hint-idp-<version>.jar resultante para a diretoria providers do seu Keycloak:
```
cp target/login-hint-idp-*.jar /opt/keycloak/providers/
```

Volte a compilar o Keycloak para que o provider fique registado e reinicie depois a instância em execução para que tenha efeito:

/opt/keycloak/bin/kc.sh build
# then restart Keycloak, e.g. restart the service or container running it,
# or start it again directly:
/opt/keycloak/bin/kc.sh start

Porque é isto necessário

O provider vai buscar o e-mail à sessão autenticada do Keycloak (getAuthenticatedUser()), e não a um parâmetro fornecido pelo cliente. Isso garante que o dispositivo verificado pelo XFA pertence ao utilizador que iniciou mesmo a sessão.

Criar o Identity Provider XFA no Keycloak

Na Keycloak Admin Console, escolha o seu realm e vá a Identity providers. Clique em Add provider e escolha OpenID Connect v1.0.

Preencha o seguinte, copiando os valores da página do painel XFA que deixou aberta.

Provider

Alias: XFA (é este alias exato que é referido no Post Login Flow abaixo)
Display name: XFA

Definições OpenID Connect

Desligue Use discovery endpoint, o que revela os campos onde introduz os endpoints manualmente.
Authorization URL
Token URL
User Info URL
Issuer
Ligue Validate Signatures para revelar o campo JWKS URL e preencha depois o JWKS URL.
Defina Client authentication como Client secret sent in the request body.
Client ID
Client Secret

Guarde o provider. O Keycloak mostra agora um Redirect URI para este Identity Provider (tem o aspeto de https://<keycloak-host>/realms/<realm>/broker/XFA/endpoint). Copie esse valor de volta para o campo Redirect URI na página do painel XFA e guarde a integração XFA.

Definições avançadas

Abra o provider que acabou de criar e expanda a secção Advanced (fechada por predefinição):

Defina Default Scopes como openid email profile.
Ligue Pass login_hint para que o Keycloak encaminhe para o XFA o e-mail do utilizador autenticado (definido pelo provider instalado acima).

Mapeamento de atributos

Deixe os mappers predefinidos como estão. O XFA devolve o email (e o sub) do utilizador no token assinado, que o Keycloak usa para associar o resultado da verificação ao utilizador já autenticado.

O XFA tem de correr depois de o utilizador se autenticar, por isso é configurado como Post Login Flow na sua autenticação principal.

1. Criar um fluxo de autenticação

Na Admin Console, vá a Authentication > Flows e crie um novo fluxo (por exemplo, XFA Device Verification) do tipo Basic flow.

Acrescente duas execuções, ambas definidas como Required, por esta ordem:

IdP Redirector (login_hint), fornecido pelo jar que instalou. Abra as respetivas Settings (o ícone da roda dentada) e defina Default Identity Provider como XFA.
Identity Provider Redirect, abra as respetivas Settings e defina Default Identity Provider como XFA.

Abra a autenticação principal que executa o primeiro passo de início de sessão (por exemplo, o seu Identity Provider Microsoft em Identity providers), vá às suas definições avançadas e defina Post login flow como o fluxo XFA Device Verification que acabou de criar.

A partir de agora, depois de um utilizador concluir o início de sessão normal, o Keycloak encaminha-o para o XFA para verificar o dispositivo antes de a sessão ser estabelecida.

Definições avançadas

Para definições mais avançadas, como limitar o fator a determinados utilizadores ou só acionar o XFA em certos casos, use os autenticadores condicionais do Keycloak dentro do fluxo XFA Device Verification e consulte a documentação do Keycloak.