# Implementação e Configuração: Keycloak para Suricato (SAML)

## Visão Geral

Este procedimento descreve a configuração do **Keycloak (via Docker)** como Provedor de Identidade (IdP), utilizando o protocolo **SAML** para autenticação Single Sign-On (SSO) no sistema Suricato.

O fluxo consiste em:

* Subir o Keycloak com HTTPS
* Criar e configurar um Realm
* Configurar um Cliente SAML
* Definir atributos de autenticação (Assertion)
* Validar acesso com usuário de teste

## Regras de Negócio

* O protocolo SAML exige HTTPS para funcionamento adequado
* O Suricato depende de um identificador único e estático do usuário
* O Keycloak deve estar acessível ao sistema Suricato (rede/liberação de IP)
* As URLs configuradas devem corresponder exatamente ao ambiente do Suricato

**REGRA CRUCIAL DE CONFIGURAÇÃO**

Na etapa de mapeamento de atributos (Assertion), é obrigatório configurar o provedor de identidade para devolver o **Identificador Único do Usuário** (ex: login, CPF ou e-mail) e **NUNCA o Token de Sessão**.

**Por que isso é importante?**

O Token muda a cada autenticação. Se o sistema receber o Token em vez do usuário:

* O Suricato interpretará cada login como um novo usuário
* Ocorrerá duplicidade de registros
* O histórico de acessos será comprometido

✔ O identificador do usuário deve ser **fixo e imutável**

### 1. Preparação do Ambiente (Docker)

**Pré-requisitos:**

* Docker instalado
* Certificados SSL (server.crt.pem e server.key.pem)

**Gerar certificado:**

```
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
-keyout server.key.pem -out server.crt.pem \
-subj "/CN=127.0.0.1" \
-addext "subjectAltName=DNS:127.0.0.1,IP:127.0.0.1"
```

**Subir o container:**

```
docker run -p 8080:8080 -p 8443:8443 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
-e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
-v $(pwd)/server.crt.pem:/etc/x509/https/tls.crt \
-v $(pwd)/server.key.pem:/etc/x509/https/tls.key \
quay.io/keycloak/keycloak:26.5.1 \
start-dev --https-certificate-file=/etc/x509/https/tls.crt \
--https-certificate-key-file=/etc/x509/https/tls.key
```

### 2. Acesso e Criação do Realm

1. Acesse: <https://localhost:8443/admin>
2. Login: admin / admin
3. Create Realm
4. Nome: **suricato\_serviceprovider**

### 3. Configuração de Segurança

* Acesse: **Realm settings > Security defenses > Headers**
* Adicione no Content-Security-Policy:

```
frame-src 'self'; frame-ancestors 'self' https://172.16.14.239:913; object-src 'none';
```

### 4. Criação do Cliente SAML

* Clients > Create client
* Tipo: SAML
* Client ID: **suricato**

### 5. Configuração de URLs

* Root URL:\
  `https://172.16.14.239:913/suricato/saml/public/`
* Home URL:\
  `https://172.16.14.239:913/telematica/suricato.exe`
* Valid Redirect URIs:\
  `https://172.16.14.239:913/*`
* Master SAML Processing URL:\
  `https://172.16.14.239:913/suricato/saml/public/module.php/saml/sp/saml2-acs.php/suricato_serviceprovider`

### 6. Configurações de Assinatura

* Name ID Format: **username**
* Force Name ID Format: On
* Force POST Binding: On
* Sign documents: On
* Sign assertions: On
* Client signature required: On

### 7. Configuração de Logout

* Definir URLs de logout (POST e Redirect)
* Salvar alterações

### 8. Mapeamento de Atributos (Assertion)

{% hint style="danger" %}
**Aqui ocorre o retorno do identificador do usuário para o Suricato**
{% endhint %}

1. Acesse:\
   Client scopes > suricato-dedicated > Add mapper
2. Selecione:\
   **User Attribute Mapper for NameID**
3. Configure:

* Name: Forcar Username no NameID
* User Attribute: **username**
* Name ID Format:\
  `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`

**IMPORTANTE** (Aplicação da Regra)

Neste ponto, o Keycloak está definindo **qual informação será enviada ao Suricato na autenticação**.

✔ Deve retornar:

* Usuário

❌ Nunca retornar:

* Session Token
* ID dinâmico de sessão

### 9. Criação de Usuário de Teste

* Username: admin
* Definir senha permanente

### 10. Obtenção do Metadata

* Realm settings > Endpoints
* Baixar: **SAML 2.0 Identity Provider Metadata**

## FAQ - Perguntas Frequentes

<details>

<summary>Por que o Suricato está criando usuários duplicados?</summary>

Provavelmente o IdP está enviando um **token dinâmico** em vez de um identificador fixo.\
Revise o passo **3.8 (Mappers)**.

</details>

<details>

<summary>Posso usar e-mail em vez de username?</summary>

Sim, desde que seja:

* Único
* Imutável

</details>

<details>

<summary>O SAML funciona sem HTTPS?</summary>

Não. O protocolo exige conexão segura.

</details>

<details>

<summary>O erro de login pode ser causado por URL incorreta?</summary>

Sim. URLs de redirect e ACS precisam estar **exatamente iguais** no Keycloak e no Suricato.

</details>

<details>

<summary>Preciso usar modo “start-dev” em produção?</summary>

Não. Esse modo é apenas para testes. Em produção, use configuração segura.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://software-telematica-com.gitbook.io/suricato-docs/manual-de-operacao/manual-do-suricato/processos-configuracoes-e-relatorios/configuracoes/saml/implementacao-e-configuracao-keycloak-para-suricato-saml.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.