> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SAML SSO

> Configure o logon único SAML 2.0 para sua organização.

Truthlocks suporta logon único nativo SAML 2.0 para que sua equipe possa se autenticar através de seu provedor de identidade (IdP) existente. Quando o SAML é configurado, os usuários são automaticamente roteados para seu IdP durante o login.

> [!NOTE]
>
> O SAML SSO está disponível no plano **Business** e superiores.

## Como funciona

**1. Configure seu IdP**

Registre o Truthlocks como um provedor de serviços (SP) em seu provedor de identidade.
Você precisa do ID da Entidade SP e da URL do Serviço de Consumidor de Asserção (ACS) do
tela de configuração.

**2. Adicionar conexão no Truthlocks**

Na Console, vá para **Configurações > SSO** e crie uma nova conexão SAML.
Insira o URL de metadados do seu IdP ou forneça manualmente o ID da entidade do IdP, o URL de SSO,
e certificado de assinatura.

**3. Usuários fazem login via IdP**

Uma vez ativo, os usuários que visitam a página de login da console são redirecionados para o seu
IdP. Após a autenticação, eles são retornados à Truthlocks com uma sessão.

## Detalhes do provedor de serviços

Forneça esses valores ao seu IdP ao registrar o Truthlocks:

| Campo | Valor |
| - | - |
| ID da Entidade SP | `urn:truthlocks:TENANT_ID` |
| URL ACS | `https://console.truthlocks.com/api/auth/saml/acs` |
| Formato NameID | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` |
| Vinculação | HTTP-POST |

## Campos de configuração do IdP

Ao criar uma conexão SAML no console, você pode configurar seu IdP de duas maneiras:

### Opção A: URL de metadados

Forneça sua URL de metadados do IdP e o Truthlocks buscará automaticamente o ID da entidade, a URL de SSO e o certificado de assinatura.

### Opção B: configuração manual

| Campo | Descrição |
| - | - |
| ID da Entidade IdP | Identificador exclusivo do seu provedor de identidade |
| URL SSO do IdP | O URL para onde a Truthlocks envia as solicitações de autenticação SAML |
| Certificado IdP | O certificado de assinatura X.509 do seu IdP (formato PEM) |

## Criando uma conexão via API

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/sso/connections \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "SAML",
    "idp_metadata_url": "https://idp.example.com/metadata",
    "role_mapping_mode": "GROUPS"
  }'
```

Se você preferir a configuração manual, omita `idp_metadata_url` e forneça `idp_entity_id`, `idp_sso_url` e `idp_certificate` em vez disso.

## Mapeamento de função

Truthlocks mapeia asserções de grupo IdP para funções internas durante o login. Dois modos estão disponíveis:

| Modo | Comportamento |
| - | - |
| `STATIC` | Todos os usuários SAML recebem uma função padrão fixa (por exemplo, `viewer`) |
| `GROUPS` | Nomes de grupos IdP são mapeados para funções Truthlocks (`admin`, `editor`, `auditor`) automaticamente |

Defina o modo ao criar ou atualizar a conexão SSO.

## Provisionamento de usuário

Quando um usuário se autentica via SAML pela primeira vez, o Truthlocks cria automaticamente sua conta usando atributos da asserção SAML (e-mail, primeiro nome, último nome). Isso é chamado de provisionamento just-in-time (JIT).

Para sincronização e desprovisionamento de utilizadores em massa, use [provisionamento SCIM](https://docs.truthlocks.com/pt/security/scim.md).

## Detalhes da sessão

* As sessões duram **12 horas** após o login SAML.
* Os cookies de sessão são `HttpOnly` e `SameSite=Lax`.
* Uma tolerância de desvio de relógio de 2 minutos é aplicada ao validar asserções SAML.

## Testando uma conexão

Após criar uma conexão SAML, teste-a antes de habilitar para todos os usuários:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/sso/connections/<connection_id>/test \
  -H "Authorization: Bearer <admin_token>"
```

Isso valida que o Truthlocks pode alcançar seu IdP e analisar os metadados corretamente.

## Desabilitando o SSO

Para reverter para a autenticação padrão de e-mail/senha:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/sso/connections/<connection_id>/disable \
  -H "Authorization: Bearer <admin_token>"
```

## Relacionado

* [Provisionamento SCIM](https://docs.truthlocks.com/pt/security/scim.md) — Automatize a sincronização de usuários e grupos do seu IdP.
* [RBAC e permissões](https://docs.truthlocks.com/pt/security/rbac.md) — Entenda as funções às quais os usuários SAML são mapeados.
* [Autenticação](https://docs.truthlocks.com/pt/security/auth.md) — Métodos de autenticação de chave de API e JWT.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.