Faça login da sua equipe com SSO

O que você vai construir

Ao final deste tutorial, você terá:

• uma conexão SAML entre o seu servidor do Control Center e um provedor de identidade (usamos o Okta como exemplo),
• um usuário provisionado automaticamente no primeiro login e
• uma política de associação ao espaço de trabalho que você escolheu de forma deliberada.

Você vai precisar de um servidor que você administre (o proprietário do servidor — o operador da instalação) e de uma aplicação IdP que você possa configurar. Reserve 20 minutos.

1. Abra as configurações de início de sessão único

Entre no Control Center e acesse Configurações → Servidor → Início de sessão único. A tela alterna entre SAML e OpenID Connect, além de um cartão Provisionamento de utilizadores (SCIM). Permaneça em SAML.

Tudo nesta tela vale para todo o servidor: um único IdP autentica as pessoas de todos os espaços de trabalho, então só o proprietário do servidor pode editar isso.

2. Cole os metadados do IdP

No Okta, abra a aba Sign On da sua aplicação e copie o XML de metadados (ou baixe-o e cole o conteúdo do arquivo). De volta ao Control Center, cole-o em XML de metadados do IdP e pressione Testar ligação.

O toast informa o endpoint de login do IdP — prova de que os metadados foram interpretados, o certificado foi lido e o servidor consegue montar uma requisição de login com base neles (o teste exercita tudo, exceto a ida e volta pelo navegador). Se falhar, o XML não era um EntityDescriptor completo (a aba SAML do Okta o chama de “Metadata URL”; abra a URL e copie o que ela retorna). O mesmo botão em OpenID Connect verifica, em vez disso, o documento de descoberta do seu emissor. Para também detectar um certificado perto de expirar e ver se o IdP reconhece o Control Center, use o verificador da etapa 6.

3. Registre o Control Center no IdP

Pressione Copiar metadados SP e entregue-os a quem configura o lado do Okta (ou leia os dois valores que essa pessoa pedir):

• URL do ACS: https://<your-server>/saml/acs
• ID de entidade: https://<your-server>/saml

As URLs derivam da origem que os navegadores dos seus usuários alcançam. Se o servidor roda atrás de um túnel ou proxy reverso, garanta que a origem seja estável (Configurações → Servidor → Conexão e status → Compartilhar este servidor mostra a URL pública) — ou fixe o ID de entidade explicitamente no campo ID de entidade do SP.

Atrás de NAT?

O login SAML não precisa de IP público nem de domínio: o IdP nunca se conecta ao seu servidor — é o navegador do usuário que faz a ida e volta, então localhost, LAN, VPN, Tailscale ou um túnel funcionam. Dois pontos para não confundir:

• a origem usada pelo navegador deve corresponder à URL do ACS / ao ID de entidade registrados no IdP (fixe o ID de entidade se os usuários alcançarem o servidor por mais de uma origem),
• o provisionamento por SCIM é a exceção — o IdP chama o seu servidor diretamente, então precisa de um túnel ou de uma URL pública (provisionar usuários com SCIM).

4. Escolha o que um login concede

Duas políticas determinam o que o primeiro login faz:

• Adicionar utilizadores a todos os espaços na primeira sessão — deixe ativado em uma implantação de uma só equipe, em que o SSO equivale a confiança. Desative quando várias equipes ou clientes compartilham o servidor: aí cada recém-chegado precisa de um convite explícito para um espaço de trabalho, que é o padrão mais seguro.
• Provisionar utilizadores desconhecidos na primeira sessão — ativado por padrão; desative para recusar quem não tem uma conta existente.

Opcionalmente, mapeie um atributo que carrega nomes de grupos (no Okta, costuma ser groups) e traduza grupos em papéis com o mapeamento — por exemplo {"platform-leads": "admin"}. O SSO nunca consegue conceder o papel de proprietário.

5. Ative e faça um login

Ative Usar SAML para entrar, pressione Salvar conexão e abra uma janela privada do navegador em https://<your-server>/saml/login. Faça login no Okta e você volta para o cliente web — conectado, com a sua conta criada e a associação concedida conforme a política que você escolheu.

O mesmo ponto de entrada aparece na tela de conexão web (Entrar com SAML) no momento em que você digita o endereço do servidor — o formulário se adapta ao que o servidor oferece (o OpenID Connect mostra Entrar com OpenID Connect). O botão abre o login em uma nova aba; quando a ida e volta termina, a aba que estava esperando assume a sessão automaticamente. A tela de configuração do servidor no app de desktop faz o mesmo: digite a URL do servidor, aparece um botão Entrar com SAML que abre o seu navegador e o app faz o login quando a ida e volta termina.

6. Verifique a partir desta página

Antes de colocar o SSO em produção, ou quando um login falhar, verifique as peças aqui. O verificador roda inteiramente no seu navegador: ele lê os metadados que você cola nesta aba e aplica as mesmas regras do servidor. Se você informar o endereço do servidor, ele também pergunta a esse servidor se o login SAML está ativado.

Ele detecta o que o Testar ligação do app não consegue ver: um certificado de assinatura perto de expirar, um IdP que exige requisições assinadas e, com o login de teste, se o IdP reconhece o Control Center.

Runs in your browserYour metadata is read in this tab and never uploaded. Add a server address and your browser also asks that server which sign-in methods it offers.

IdP metadata XMLLoad a file

Server address (optional)

The address your users open. Adds a reachability check and a test sign-in.

SP entity ID (optional)

Only if you pinned one in the app.

Check metadata

Próximos passos

• Dê ao seu IdP o controle do ciclo de vida também: provisionar e desprovisionar usuários com SCIM.
• O seu IdP fala OpenID Connect em vez de SAML? Conectar um provedor OpenID Connect.
• Quer saber o que a ida e volta pelo navegador realmente verifica? Como funciona o logon único.