# Como configurar o SAML no Suricato

## Visão Geral

A implementação do padrão SAML (*Security Assertion Markup Language*) no SURICATO permite a troca de dados de autenticação e autorização entre o sistema e um provedor de identidade externo. 

Este recurso habilita o *Web Browser Single-Sign-On* (SSO), garantindo que, uma vez autenticado no IdP, a sessão do navegador não requeira nova autenticação, mesmo que o acesso ocorra através de outro sistema integrado.

### Fluxo de Identificação e Autenticação

Abaixo são apresentados os fluxos de autenticação que ocorrem no SURICATO quando o SAML está definido:

#### Fluxo Inicial – Usuário não autenticado

<figure><img src="/files/yQ7fEtcmCqCCjRaDINA7" alt=""><figcaption><p><em>Usuário não autenticado</em></p></figcaption></figure>

{% stepper %}
{% step %}
Usuário acessa a página Suricato de login;
{% endstep %}

{% step %}
A requisição de login é redirecionada para o módulo SAML e encaminhada para o IdP. O IdP mostra a tela de login;
{% endstep %}

{% step %}
Depois que o usuário informar a usuário e senha, o IdP faz a validação da identificação/autorização em base de usuário (essa fonte de dados é determinada pelo IdP, por exemplo AD);
{% endstep %}

{% step %}
Identificado e autenticado, o IdP redireciona o usuário para aplicação Suricato com o SAML Assertion.
{% endstep %}

{% step %}
Neste cenário, o Login foi realizado com sucesso.
{% endstep %}
{% endstepper %}

#### Fluxo Inicial – Usuário já autenticado (SSO)

<figure><img src="/files/oAmu9pw7nnudxxDhagmt" alt=""><figcaption><p><em>Usuário autenticado</em></p></figcaption></figure>

{% stepper %}
{% step %}
Usuário acessa a página Suricato de login;
{% endstep %}

{% step %}
A requisição de login é redirecionada para o módulo SAML e encaminhada para o IdP. Como o usuário já está autenticado, o acesso é garantido;
{% endstep %}

{% step %}
Identificado e autenticado, o IdP redireciona o usuário para aplicação Suricato com o SAML Assertion.
{% endstep %}

{% step %}
Neste cenário, o Login foi realizado com sucesso.
{% endstep %}
{% endstepper %}

#### Onde encontrar esta tela no Suricato?

Caminho: Configuração ➜ SAML

* **Versão 3.1 (Nova Interface):** Clique no ícone de menu à esquerda para expandir ou reduzir o menu.

{% hint style="info" icon="lightbulb-on" %}
**Dica Ágil:** Pressione a lupa no topo e digite "SAML" para localizar a opção diretamente na versão v3.1.0.0.
{% endhint %}

## Regras de Negócio

* **Papéis da Arquitetura:** O sistema SURICATO atua como Provedor de Serviço (SP) e o software terceiro como Provedor de Identidade (IdP).
* **Requisitos de Instalação:** É necessário utilizar a versão 3.1.x do SURICATO e PHP 8.1.x ou superior.
* **Identificação do Usuário:** No processo de autenticação, o sistema espera que o login do usuário seja retornado obrigatoriamente na tag `saml:sp:NameID` do *response* SAML.
* **Comportamento do Login:** Com o SAML ativo, a tela de login padrão do SURICATO é substituída pela interface do IdP. Caso o usuário já esteja autenticado, o sistema redirecionará diretamente para o menu principal.

## Procedimento de Instalação e Configuração

O pacote SAML já acompanha as versões atualizadas do sistema. Para realizar a configuração, siga as etapas abaixo:

1. **Acesso Administrativo:** Acesse a tela de login como ADMIN através da URL: `https://IP_SERVIDOR/scriptcase/app/suricato/ctrloginadmin/ctrloginadmin.php` Autentique-se utilizando a senha de ADMIN.

<figure><img src="/files/pKZ7CgSGLJVkjFAffAQ4" alt=""><figcaption></figcaption></figure>

2. **Método de Autenticação:** Acesse o menu Configuração ➜ Sistema e defina o método de autenticação como SAML.

<figure><img src="/files/tMnC0I2UvCtc7NGgqisp" alt=""><figcaption></figcaption></figure>

3. **Configuração SAML:** Acesse o menu Configuração ➜ SAML para parametrizar os detalhes da integração.

<figure><img src="/files/VtAx4DziSPev81pDTcWR" alt=""><figcaption></figcaption></figure>

4. **Configuração SP (Aba Configuração):** Nesta aba, o SURICATO é parametrizado como *Service Provider*.
   * Importe o certificado e a chave privada do servidor localizados em `SURICATO_HOME\apache\cert`.

<figure><img src="/files/O2zS3eoArj5Y1X5OWBWq" alt=""><figcaption><p><em>Certificado</em></p></figcaption></figure>

<figure><img src="/files/UPX50FAuXbtjIWVOTZEQ" alt=""><figcaption><p><em>Chave Privada</em></p></figcaption></figure>

* **Botão Baixar Metadata:** Clique para baixar o arquivo `suricato_serviceprovider.xml`. Este documento deve ser fornecido obrigatoriamente ao software IdP.

<figure><img src="/files/fynfJEJPbZcB8sYlFYP2" alt=""><figcaption></figcaption></figure>

* **Configuração Manual:** É possível configurar manualmente o Certificado e a Chave Privada copiando e colando os códigos nos campos correspondentes:
  * Copie e cole o Certificado: \
    `-----BEGIN CERTIFICATE-----` `[Conteúdo do Certificado]` `-----END CERTIFICATE-----`
  * Copie e cole a Chave Privada: \
    `-----BEGIN PRIVATE KEY-----` `[Conteúdo da Chave]` `-----END PRIVATE KEY-----`

5. **Configuração IdP (Aba IDP):** Parametrizar o software terceiro que fará a autenticação.
   * A configuração pode ser realizada via importação do arquivo Metadata fornecido pelo IdP ou preenchimento manual.

<figure><img src="/files/RPlgenizDbyU1a9gJ0C9" alt=""><figcaption></figcaption></figure>

* Utilize o bloco Metadata para salvar as definições e verifique o resultado no bloco IDP.

Caso ocorra falha no *upload*, realize a configuração manual. Para suporte no tráfego de dados, recomenda-se o uso do *SAML Chrome Panel* e ver o tráfego de request e response SAML.

{% hint style="warning" %}
No processo de autenticação, no response SAML, é esperado que o login do usuário seja retornado na tag: saml:sp:NameID
{% endhint %}

6. Validação (Aba Testar):

<figure><img src="/files/dfUk2j1pUBInKYtCVVoN" alt=""><figcaption></figcaption></figure>

* Clique em Executar para testar a comunicação. O módulo redirecionará a requisição para o IdP.

<figure><img src="/files/jSIljgBhG3qPDfOU17s8" alt=""><figcaption></figcaption></figure>

* Após inserir o *username* e *password* corretamente, o sistema validará a integração e retornará a página de sucesso SAML.

<figure><img src="/files/HbGdQf3xgFhB9R0CzzQs" alt=""><figcaption></figcaption></figure>

7. **Acesso ao Sistema:** Concluída a configuração, acesse o SURICATO normalmente pela URL:

```
https://IP_SERVIDOR/telematica/suricato.exe 
```

A partir deste momento, a tela de login padrão será substituída pela do IdP.

## Guia de Edição Rápida

1. Acesse o menu Configuração ➜ SAML.
2. Navegue entre as abas Configuração (para ajustes do SP) ou IDP (para ajustes do provedor externo).
3. Atualize os certificados, chaves ou metadados conforme necessário.
4. Clique em **Salvar** para efetivar as alterações.

## FAQ - Perguntas Frequentes

<details>

<summary>O que fazer se ocorrer falha no Upload do Metadata do IdP?</summary>

O sistema permite que a parametrização seja realizada de forma manual diretamente na Aba IDP.

</details>

<details>

<summary>Como posso monitorar o tráfego de autenticação para suporte?</summary>

É recomendada a instalação do *SAML Chrome Panel* para visualizar o tráfego de *request* e *response* SAML durante os testes.

</details>

<details>

<summary>Onde encontro os certificados padrão no servidor?</summary>

Os arquivos de certificado e chave privada ficam armazenados no diretório `SURICATO_HOME\apache\cert`.

</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/como-configurar-o-saml-no-suricato.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.