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

# Requisitos de deploy do SSO (BYOC)

> Configure o callback do Console, a rota do Auth acessível pelo navegador, a rota do Identity e a resolução do tenant para SSO no BYOC.

Esta página diz a um operador BYOC o que configurar antes que um administrador habilite o [login único](https://docs.lerian.studio/pt/platform/access-manager/features/sso/overview).

> [!NOTE]
>
> Esta página vale apenas para deploys BYOC. Na Lerian Cloud, a Lerian opera essa configuração para você.

## Definir uma URL de callback

***

Defina `PLUGIN_AUTH_SSO_CALLBACK_URL` nos serviços Auth e Identity. Use a URL pública exata de callback do Console:

```text theme={null}
https://console.example.com/signin/sso/callback
```

O Auth envia essa URL ao provedor de identidade. O Identity a inclui na configuração dos redirecionamentos permitidos.

> [!WARNING]
>
> Use a mesma URL absoluta no Auth, no Identity, no Console e na aplicação do provedor de identidade. Uma diferença no esquema, no host ou no caminho faz a troca do código de autorização falhar.

## Configurar as rotas do Console

***

O Console precisa destas rotas:

| Variável | Finalidade |
| - | - |
| `PLUGIN_AUTH_BASE_PATH` | URL base da API do Auth para chamadas entre servidores, incluindo `/v1`. |
| `PLUGIN_AUTH_PUBLIC_BASE_PATH` | URL base da API do Auth acessível pelo navegador, incluindo `/v1`. |
| `PLUGIN_IDENTITY_BASE_PATH` | URL base da API do Identity para chamadas entre servidores, incluindo `/v1`. |

Defina `PLUGIN_AUTH_PUBLIC_BASE_PATH` como um endereço HTTPS que o navegador do usuário consiga acessar. O navegador segue diretamente o redirecionamento da operação de início do SSO.

Para definir essas variáveis com o chart do Product Console, consulte o [README do chart do Product Console](https://github.com/LerianStudio/helm/tree/main/charts/product-console).

As URLs pública e entre servidores do Auth podem apontar para o mesmo endereço. Use um endereço interno para chamadas entre servidores e o endereço público para redirecionamentos do navegador.

## Configurar a resolução do tenant

***

Antes de o SSO começar, o Auth precisa saber a qual organização do Caradhras o usuário pertence. Cada tenant é uma organização. Escolha uma das duas configurações abaixo.

### Organização fixa (recomendado)

Defina `PLUGIN_AUTH_SSO_STATIC_ORGANIZATION` no Auth com o nome da organização do Caradhras à qual seus usuários pertencem. Normalmente, esse é o valor de `AUTHORIZER_ORGANIZATION_NAME`, cujo padrão é `lerian`.

O Auth então usa essa organização em cada requisição de SSO e não compara o domínio do email com a organização. Esta configuração não exige mudança nos dados do Caradhras e funciona para usuários de qualquer domínio de email.

### Sem organização fixa

Se você não definir `PLUGIN_AUTH_SSO_STATIC_ORGANIZATION`, o SSO usa os campos da organização:

* Defina `domain` na organização com o domínio de email dos seus usuários, como `example.com`. Sem ele, o Auth recusa cada entrada por SSO.
* Defina `domainHome` como `true` se pessoas sem conta precisarem entrar por SSO pela primeira vez. Sem ele, o Console oferece a essas pessoas apenas a entrada com senha. O provedor também precisa confirmar o email de cada pessoa. Leia [Primeiro login](https://docs.lerian.studio/pt/platform/access-manager/features/sso/overview#first-sign-in).

Uma organização guarda um único `domain`, então apenas usuários desse domínio de email podem entrar por SSO. Se seus usuários têm mais de um domínio de email, use a organização fixa em vez disso.

### Definir os campos da organização

Você pode definir `domain` e `domainHome` na página de edição da organização na interface web do Caradhras, ou com a operação `POST /api/update-organization` da API do Caradhras. O Console não tem campo de edição para eles.

Para usar a API, envie a requisição de um host que alcance o Caradhras no endereço de `AUTHORIZER_ADDRESS`, o mesmo endereço que o Auth e o Identity usam. Autentique com HTTP Basic e com o ID e o segredo do cliente que o Access Manager usa no Caradhras, `AUTHORIZER_CLIENT_ID` e `AUTHORIZER_CLIENT_SECRET`. Um administrador global do Caradhras também pode fazer a chamada. Por padrão, um administrador de tenant não pode.

Este exemplo torna a organização `acme` a principal do domínio `example.com`:

```bash theme={null}
AUTHORIZER_ADDRESS="paste-the-AUTHORIZER_ADDRESS-value-here"
AUTHORIZER_CLIENT_ID="paste-the-AUTHORIZER_CLIENT_ID-value-here"
AUTHORIZER_CLIENT_SECRET="paste-the-AUTHORIZER_CLIENT_SECRET-value-here"

curl -X POST "$AUTHORIZER_ADDRESS/api/update-organization?id=admin/acme" \
  -u "$AUTHORIZER_CLIENT_ID:$AUTHORIZER_CLIENT_SECRET" \
  --json '{"owner":"admin","name":"acme","domain":"example.com","domainHome":true}'
```

As chaves que você deixa fora do corpo mantêm os valores salvos. Uma chave que você envia substitui o valor salvo, mesmo quando está vazia ou é `false`. Envie `owner` e `name` com os valores atuais da organização, O Caradhras recusa um `name` diferente. Deixe `domainHome` fora do corpo para uma organização que não é a principal do seu domínio.

Para conferir o resultado, liste as organizações de um domínio:

```bash theme={null}
curl "$AUTHORIZER_ADDRESS/api/get-organizations?owner=admin&field=domain&value=example.com" \
  -u "$AUTHORIZER_CLIENT_ID:$AUTHORIZER_CLIENT_SECRET"
```

### Recusar usuários de outros domínios (opcional)

O Caradhras também pode comparar o domínio do email com o `domain` da organização quando cria um usuário, inclusive um usuário que entra por SSO pela primeira vez, e quando um administrador muda o email de um usuário. A configuração `emailDomainPolicy` controla essa verificação:

| Valor | Efeito |
| - | - |
| `off` | O Caradhras não verifica o domínio do email. |
| `warn` | Padrão. O Caradhras registra a divergência no log e salva o usuário. |
| `enforce` | O Caradhras recusa o usuário com `CRDH-2009`. |

A verificação vale apenas para organizações que têm `domain`. Para defini-la com o chart do Access Manager, consulte o [README do chart do Access Manager](https://github.com/LerianStudio/helm/tree/main/charts/plugin-access-manager).

## Expor o Auth ao navegador

***

O navegador precisa acessar a rota de início do SSO no Auth por HTTPS. Exponha o Auth em um endereço público e permita a origem do Console conforme a política de origem cruzada do seu deploy.

O Identity pode permanecer em uma rota entre servidores quando os administradores o gerenciam apenas pelo Console.

## Configurar o provedor de identidade

***

Na aplicação do provedor:

1. Cadastre a URL de callback exata do Console.
2. Permita os escopos do OpenID Connect necessários para retornar a identidade e o email do usuário.
3. Emita um ID e um segredo do cliente para o tenant.
4. Torne o issuer e os endpoints acessíveis pelos serviços do Access Manager.

Para um provedor OpenID Connect personalizado, use um issuer que publique metadados de descoberta válidos. Em vez disso, as integrações pela API podem fornecer o conjunto completo de endpoints de autorização, token e informações do usuário.

## Validar o deploy

***

**1. Abra a aba Single Sign-On**

Confirme que o Console consegue ler do Identity o estado atual do provedor.

**2. Rode o preflight do provedor**

Teste a configuração candidata sem salvá-la. Corrija todas as falhas obrigatórias.

**3. Cadastre a URL de callback**

Compare o cadastro no provedor com `PLUGIN_AUTH_SSO_CALLBACK_URL` caractere por caractere.

**4. Salve o provedor**

Mantenha a entrada com senha disponível durante o primeiro teste.

**5. Teste em uma sessão privada do navegador**

Digite um email do tenant, conclua a entrada no provedor e confirme que o navegador volta ao Console.

**6. Teste o isolamento do tenant**

Tente usar um email que não pertença ao tenant. Confirme que o Auth não conclui a entrada nem revela detalhes do tenant.

**7. Teste a continuação para a MFA**

Entre com um usuário que tenha a MFA habilitada e confirme que o Console abre a etapa de verificação da MFA depois do SSO.

## Páginas relacionadas

***

> [card] [Configure o SSO no Console](https://docs.lerian.studio/pt/platform/access-manager/features/sso/console.md)
>
> Teste e salve a configuração do provedor.


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