Configuração SAML - Keycloak e Fracttal
Guia completo para configurar autenticação SAML entre Keycloak e Fracttal, incluindo criação de cliente, configuração de parâmetros e validação da integração.
Pré-requisitos
- Acesso administrativo ao Keycloak (versão 16.1.1 ou superior).
- Acesso administrativo ao Fracttal.
- URL base do Fracttal: https://app.fracttal.com
- Nome chave de configuração SAML (por exemplo, neste documento uso: fracttalkeykloak). Este valor deve ser único e coincidir com o configurado no Keycloak.
Criação do Cliente no Keycloak
- Faça login no console de administração do Keycloak.
- No menu lateral, selecione: Configure → Clients.
- Clique no botão 'Create'.
- No campo 'Client ID', insira o identificador do cliente: fracttal-app. (é o valor que uso para o exemplo, mas fica a critério de quem configurar. O importante é que coincida com o issuer configurado no Fracttal).
- Selecione 'saml' como Client Protocol.
- Pressione 'Save' para continuar.
Configuração do Cliente SAML
Uma vez criado o cliente, configure os parâmetros na aba 'Settings' da seguinte forma
| Parâmetro | Valor | Descrição |
|---|---|---|
| Client ID | fracttal-app | Identificador único do cliente |
| Enabled | ON | Ativa o cliente |
| Client Protocol | saml | Define o protocolo SAML. |
| Sign Assertions | ON | Este parâmetro indica se o Keycloak deve assinar as asserções SAML |
| Signature Algorithm | RSA_SHA256 | Define o algoritmo criptográfico utilizado para gerar a assinatura digital nas mensagens SAML |
| SAML Signature Key Name | KEYID | Especifica como o Keycloak identifica a chave usada para assinar a mensagem SAML dentro do XML |
| Canonicalization Method | EXCLUSIVE | Define o método de canonicalização XML, que é a forma pela qual o documento é normalizado antes de aplicar a assinatura digital |
| Force POST Binding | ON | Força o método POST para respostas SAML. |
| Front Channel Logout | ON | Habilita o encerramento de sessão coordenado. |
| Name ID Format | Envia o identificador de usuário como e-mail. | |
| Valid Redirect URIs | https://app.fracttal.com/rpc/auth/samlcallback?codesaml=fracttalkeykloak&id_server=AMERICAN | URI de retorno para o Fracttal. |
| Base URL | https://app.fracttal.com | URL base do serviço SP. |
| Assertion Consumer Service POST Binding URL | https://app.fracttal.com/rpc/auth/samlcallback?codesaml=fracttalkeycloak | Endpoint onde o Fracttal recebe as respostas SAML. |
Também não é necessário realizar mapeamentos personalizados de campos, apenas indicando que o NameID Format é email já deve funcionar.
Configuração no Fracttal
Para registrar o Identity Provider (Keycloak) no Fracttal:
- Acesse o Fracttal com um usuário administrador.
- Vá para Configuração → Segurança → SAML 2.0.
- Complete os campos de acordo com a seguinte tabela.
| Campo | Valor |
|---|---|
| Conexão/Nickname | fracttalkeycloak |
| Issuer | fracttal-app |
| Single Sign-On URL | http://localhost:8080/auth/realms/master/protocol/saml |
| Single Logout URL | http://localhost:8080/auth/realms/master/protocol/saml |
| Certificate | (Certificado X.509 exportado do Keycloak) |
O campo 'Issuer' deve ter o mesmo valor que o Client ID do cliente configurado no Keycloak.
Os campos de URLs (SSO e Logout) são obtidos dos metadados do Identity Provider no Keycloak, acessíveis em 'Realm Settings → General → SAML 2.0 Identity Provider Metadata'.
Exportar Metadados do IdP
- Na visualização do Realm, abra a aba 'General'.
- Clique em 'SAML 2.0 Identity Provider Metadata'.
- Copie ou baixe o conteúdo XML.
- Extraia o certificado e as URLs (SingleSignOnService e SingleLogoutService) do XML.
- Estes valores devem coincidir com os configurados no Fracttal.
Testes e Validação
- Acesse o Fracttal e tente fazer login com o método SAML configurado.
- Verifique se é redirecionado para o login do Keycloak.
- Faça login com as credenciais do IdP.
- Se a autenticação for bem-sucedida, o usuário entrará automaticamente no Fracttal.
Updated 8 days ago