SAML 2.0 SSO

O cside permite que você conecte qualquer provedor de identidade (IdP) SAML 2.0 e o use para autenticar usuários na sua organização cside. Uma única configuração genérica cobre todos os provedores compatíveis com SAML, então os passos são os mesmos se você usa Okta, Microsoft Entra ID, OneLogin, JumpCloud, Ping, Keycloak ou um IdP próprio.

Quando você habilita o SAML SSO, qualquer pessoa com o domínio de e-mail da sua empresa será redirecionada para autenticar com o seu IdP. Isso significa que você pode usar o seu IdP para controlar quem pode acessar o cside, e quando você permitir alguém, essa pessoa será automaticamente adicionada à sua organização cside sem permissões.

Requisitos:

• Plano cside Enterprise
• Função de Administrador da Organização no cside
• SAML 2.0 SSO habilitado para a sua organização pelo cside
• Uma organização cside já configurada - o administrador inicial (você) será o primeiro usuário e será convertido para SSO após a migração
• Acesso de administrador a um provedor de identidade SAML 2.0 que possa assinar asserções e publicar seus metadados

Se você preferir OIDC, consulte os guias de Okta, Duo ou Microsoft Entra ID. Uma organização pode manter uma configuração OIDC e uma SAML ao mesmo tempo, desde que cada domínio de e-mail seja reivindicado por apenas uma delas.

Navegando até as Configurações de SSO

Você pode abrir as configurações da organização diretamente, ou navegar manualmente:

1. Clique na sua conta no canto inferior esquerdo do painel
2. Selecione View organization

3. Selecione Settings

4. Navegue até a aba SSO
5. Clique em Select Provider (ou Change Provider se você já tiver SSO configurado) e selecione SAML 2.0

Adicionar o cside ao seu provedor de identidade

O topo da seção SAML 2.0 mostra os dois valores que o seu IdP precisa. Copie-os do painel para o aplicativo SAML que você criar no seu IdP:

Valor mostrado no cside	Onde inserir no seu IdP	Valor atual
Assertion Consumer Service (ACS) URL	ACS URL, Reply URL ou Single sign-on URL	https://gql.cside.com/v1/auth/saml/acs
Service provider entity ID (Audience)	Entity ID, Audience URI ou Identifier	https://cside.dev/saml/sp

Se o seu IdP preferir importar um documento de metadados do provedor de serviços, aponte-o para https://gql.cside.com/v1/auth/saml/metadata.

Em seguida, configure o aplicativo da seguinte forma. Os nomes exatos dos campos variam por IdP, mas todo provedor SAML 2.0 expõe estas configurações:

1. Name ID: Defina o formato como emailAddress (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress) e mapeie-o para o endereço de e-mail principal do usuário. O cside usa esse valor para identificar o usuário.
2. Atributos (opcional): Adicione um atributo de nome de exibição. O cside reconhece displayName, name, urn:oid:2.16.840.1.113730.3.1.241, urn:oid:2.5.4.3 e a claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name. Sem esse atributo, o endereço de e-mail do usuário é usado como nome.
3. Assinatura: Assine a asserção. Assinar também a resposta inteira é aceitável, mas uma asserção não assinada dentro de uma resposta assinada é rejeitada. Use SHA-256.
4. Criptografia: Deixe a criptografia de asserções desativada. O cside não publica um certificado de criptografia, então asserções criptografadas não podem ser lidas.
5. Solicitações assinadas: Não exija solicitações de autenticação assinadas. O cside envia solicitações SAML não assinadas.
6. Binding: O endpoint de logon único do seu IdP deve suportar o binding HTTP-Redirect. O cside envia o usuário para lá e recebe a resposta na ACS URL via HTTP-POST.
7. Atribuições: Atribua os usuários ou grupos que devem poder acessar o cside. Pense com cuidado: qualquer pessoa que o seu IdP deixar passar é adicionada à sua organização.

Se o Name ID não puder ser um endereço de e-mail no seu IdP, o cside recorre a um atributo de e-mail chamado email, mail, emailAddress, urn:oid:0.9.2342.19200300.100.1.3 ou à claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.

Obter os Dados Necessários

Você precisará dos metadados SAML do seu IdP. Todo IdP os oferece em uma de duas formas:

1. Metadata URL: Um link público https:// para o XML de metadados (preferido)
2. Metadata XML: Um documento de metadados para download

O cside lê três coisas dos metadados: o entity ID do IdP, a URL de logon único HTTP-Redirect e os certificados de assinatura. Você não os digita manualmente.

Configurar o SSO no cside

1. Acesse o painel do cside e abra a seção SAML 2.0 conforme descrito em Navegando até as Configurações de SSO.
2. Preencha os campos obrigatórios:
   • Email domain: O domínio de e-mail da sua empresa (ex.: example.com). Separe vários domínios com vírgulas. Um domínio só pode ser reivindicado por uma configuração de SSO, em todas as organizações cside.
   • Metadata URL ou Paste metadata XML: Escolha a fonte que corresponde ao que o seu IdP forneceu e cole a URL em Identity provider metadata URL ou o documento em Identity provider metadata XML.
3. Clique em Save SAML configuration.

O cside busca ou analisa os metadados, verifica-os e armazena a configuração. A URL de metadados deve usar https://, ser acessível publicamente, retornar o documento diretamente sem redirecionamentos e ter menos de 512 KB.

Depois de salvar, a seção mostra o entity ID do Identity provider, a Sign-on URL e o número de Active signing certificates, além de dois botões extras:

• Refresh certificates: Relê a URL de metadados e substitui os certificados de assinatura armazenados. Exibido apenas para configurações criadas a partir de uma URL de metadados.
• Remove SAML: Exclui a configuração. Os usuários dos domínios configurados voltam ao login com senha.

Testando sua Configuração

Não há uma janela de verificação separada para SAML: salvar a configuração a ativa imediatamente. Teste antes de avisar sua equipe:

1. Abrindo uma nova janela anônima/privada do navegador
2. Navegando até dash.cside.com
3. Inserindo um endereço de e-mail com o domínio configurado
4. Você deve ser redirecionado para o seu provedor de identidade para autenticação e voltar ao painel do cside já conectado

Iniciar o login a partir do bloco do aplicativo no seu IdP também funciona. O cside não aceita a asserção não solicitada diretamente. Ele redireciona o usuário por meio de uma solicitação iniciada pelo cside ao mesmo IdP, o que normalmente se completa sem que o usuário perceba.

Rotacionar certificados de assinatura

O cside aceita todos os certificados de assinatura listados nos seus metadados, então você pode publicar o novo certificado ao lado do antigo, alternar o seu IdP e retirar o antigo sem interrupção:

• Metadata URL: Clique em Refresh certificates na seção SAML 2.0 após cada alteração no seu IdP.
• XML colado: Baixe os metadados atualizados, cole-os em Identity provider metadata XML e clique em Save SAML configuration.

Solução de Problemas

Erros ao salvar

Mensagem	O que significa
SAML SSO is not enabled for this organization.	O cside ainda não habilitou o SAML 2.0 para a sua organização. Entre em contato com seu representante cside.
The email domain ”…” is already used by an OIDC integration.	O domínio está reivindicado por outra configuração de SSO, na sua organização ou em outra. Remova-o lá primeiro. O mesmo vale quando a mensagem menciona uma integração SAML.
This identity provider is already configured by another organization.	O entity ID dos metadados pertence a um IdP que outra organização cside já usa. Verifique se você colou os seus próprios metadados.
This metadata has no entityID.	O documento não é um arquivo de metadados de IdP completo. Copie o EntityDescriptor inteiro.
This metadata has no HTTP-Redirect single sign-on URL.	O seu IdP anuncia apenas um endpoint HTTP-POST. Habilite o binding HTTP-Redirect para o aplicativo.
This metadata has no signing certificate.	Os metadados não têm um KeyDescriptor de assinatura. Habilite a assinatura de asserções e baixe os metadados novamente.
The single sign-on URL must use https.	O endpoint de login do seu IdP é servido por HTTP sem criptografia.
The metadata URL redirects.	Aponte o campo para o documento de metadados final, não para um link que redireciona.
The metadata URL returned 404.	O link está errado ou os metadados exigem autenticação. Qualquer status diferente de 200 é reportado desta forma.
Could not reach the metadata URL. / The metadata URL timed out.	Os servidores do cside não conseguem alcançar a URL em 10 segundos. Verifique se ela é pública.
The metadata URL must resolve to a public address.	O nome do host aponta para um IP privado ou interno. Use a opção de XML colado para um IdP interno.
The metadata document is too large.	O documento excede 512 KB. Remova descritores não relacionados ou use a opção de XML colado.
This SAML integration was configured with pasted metadata, so there is no URL to refresh from.	Refresh certificates só funciona para configurações baseadas em URL. Cole o XML atualizado em vez disso.

Erros ao fazer login

Mensagem	O que significa
Unknown SAML identity provider	O emissor da resposta SAML não corresponde a nenhuma integração configurada, ou o SAML SSO foi desabilitado para a organização. Confirme que os metadados do IdP no cside estão atualizados.
This sign-in request could not be verified.	O cside rejeitou a asserção. O motivo exato fica nos logs do cside, então verifique as causas abaixo.
Signing in with SAML is not yet available for accounts whose only two-factor method is a security key.	A conta tem apenas uma chave de segurança registrada para MFA. Faça login pela página de login do cside ou adicione um aplicativo autenticador.
This email is not enrolled for cside SAML SSO	O domínio de e-mail não está em uma configuração SAML, ou o SAML SSO está desabilitado para a organização.

Causas comuns de This sign-in request could not be verified:

• A asserção não está assinada, ou apenas o envelope da resposta está assinado
• A asserção está criptografada
• O Audience da asserção não é https://cside.dev/saml/sp
• O Destination não é a ACS URL mostrada no cside
• O IdP assinou com um certificado que não está nos metadados armazenados (rotacione com Refresh certificates ou cole o novo XML)
• O endereço de e-mail do usuário está ausente tanto no Name ID quanto nos atributos de e-mail
• O domínio de e-mail do usuário não é um dos domínios configurados
• O relógio do IdP está desajustado em mais de cinco minutos
• A mesma resposta foi enviada duas vezes (asserções são de uso único)