Single Sign-On (SSO)

Configuração e uso do SSO

---

Perigo

Este guia é destinado a administradores de sistema. Se você não tiver a experiência técnica necessária, entre em contato com o seu departamento de TI para obter assistência.

A Prevu3D Cloud Platform suporta o Single Sign-On (SSO) seguro por meio de protocolos padrão do setor:

• SAML 2.0 – para autenticação e login de usuários.

• SCIM 2.0 – para provisionamento automático de usuários e grupos.

Provedores de identidade suportados

Qualquer provedor de identidade que suporte totalmente os protocolos SAML 2.0 e/ou SCIM 2.0 deve ser compatível com o Prevu3D, incluindo Okta, Google Workspace, OneLogin, Ping Identity e outros. A implementação do Prevu3D segue as especificações oficiais SAML 2.0 e SCIM 2.0, garantindo ampla compatibilidade com sistemas de identidade modernos.

Testamos minuciosamente a integração com:

• Microsoft Entra ID (anteriormente Azure Active Directory)

• JumpCloud (English)

Nota

• Cada organização Prevu3D suporta apenas uma conexão com um provedor de identidade por vez.

• O recurso de SSO está incluído na assinatura Enterprise. Entre em contato com sales@prevu3d.com para habilitá-lo para a sua organização.

SAML 2.0 – Configuração de autenticação

Pré-requisitos

Para configurar o SSO baseado em SAML com o Prevu3D, você precisará de:

• Acesso de administrador à sua organização Prevu3D.

• Acesso ao seu IdP com permissão para configurar aplicativos.

Etapas

1. Faça login na sua conta Prevu3D (usando seu endereço de e-mail e senha)

2. Vá para a aba Settings

3. Selecione a aba SSO no menu à esquerda

Não consegue acessar a aba “SSO”?

1. Se ela estiver faltando, você não é um administrador da organização.

2. Se ela estiver esmaecida, sua organização não assinou o recurso de SSO.

4. Copie os seguintes valores da aba SSO e cole-os na configuração do seu IdP:

   • Service Provider Endpoint – a URL para a qual o seu IdP envia a asserção SAML. Seu IdP pode chamá-la de ACS URL, Reply URL ou Assertion Consumer Service URL.

   • Service Provider Entity ID – o identificador exclusivo do Prevu3D na troca SAML. Seu IdP pode chamá-lo de Audience, Identifier ou SP Entity ID.

Cuidado

Insira o Entity ID no seu IdP exatamente como mostrado na aba SSO, incluindo o sufixo completo (por exemplo, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-production-############-Prevu3DCloudPlatform). Copie e cole o valor em vez de digitá-lo novamente.

Se o seu IdP enviar um valor de audience abreviado ou um nome amigável (por exemplo, Prevu3D), a autenticação é rejeitada por incompatibilidade de audience, mesmo que o restante da sua configuração esteja correto. Este é o erro de configuração mais comum — consulte Solução de problemas.

5. Recupere o seguinte do seu IdP e insira-o na aba SSO:

   • SAML Certificate (formato PEM)

   • SAML Endpoint URL

6. Se o SCIM não estiver habilitado, defina os mapeamentos de atributos SAML – consulte Mapeamentos de atributos SAML abaixo.

   

Cuidado

Esses atributos são opcionais quando o provisionamento SCIM está habilitado e configurado. O SCIM gerencia automaticamente os detalhes dos usuários.

7. Clique em Save na parte inferior da página.

8. Verifique a configuração antes de implantá-la – consulte Validação da sua configuração abaixo.

Mapeamentos de atributos SAML

Cada campo indica ao Prevu3D qual atributo (claim) ler na asserção SAML enviada pelo seu provedor de identidade. O valor inserido deve corresponder exatamente ao nome do atributo configurado no seu IdP, incluindo o uso de maiúsculas e minúsculas.

Campo	O que inserir	Valores de exemplo
First Name SAML Attribute Key	O nome do atributo do IdP que contém o nome do usuário	givenName, firstName, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last Name SAML Attribute Key	O nome do atributo do IdP que contém o sobrenome do usuário	familyName, surname, lastName

Não tem certeza de quais nomes de atributos o seu IdP envia? Capture um rastreamento SAML usando uma extensão de navegador como o SAML-tracer e verifique os nomes listados no AttributeStatement, ou consulte a configuração do aplicativo no seu IdP.

Atribuição de funções via SSO

Esta seção trazia anteriormente um campo Role SAML Attribute Key e um seletor Default Organization Role, que atribuíam uma única função para toda a organização a partir de um atributo SAML. Ambos foram removidos: uma única função para toda a organização não é granular o suficiente, e as funções oferecidas não correspondiam mais às funções personalizáveis da sua organização.

Atribua funções pelo Mapeamento de grupos: mapeie os grupos do seu IdP para grupos do Prevu3D e conceda a cada grupo o acesso necessário. Se o SCIM estiver habilitado, faça a atribuição de funções pelo SCIM.

Implantação do SSO para seus usuários

Depois que a configuração for salva e validada, dois fatores determinam se os seus usuários conseguem efetivamente fazer login.

Configuração de domínio e novos usuários

Seu domínio de e-mail precisa estar associado à sua organização Prevu3D. A configuração de domínio habilita:

• Redirecionamento na página de login – os usuários que clicam em Entrar com SSO e inserem um e-mail do seu domínio são redirecionados para o seu IdP.

• Criação de conta just-in-time – quando um usuário do seu domínio que nunca usou o Prevu3D se autentica com sucesso por meio do seu IdP, uma conta Prevu3D é criada automaticamente, com os nomes preenchidos a partir dos seus mapeamentos de atributos SAML. Nenhum convite ou criação manual de conta é necessário. A nova conta começa sem acesso a projetos até que você o conceda, pelo Mapeamento de grupos ou adicionando o usuário diretamente aos projetos.

Nota

A configuração de domínio é realizada pela Prevu3D como parte da sua integração do Enterprise SSO. Entre em contato com support@prevu3d.com para reivindicar seus domínios de e-mail.

Até que o domínio esteja configurado, os usuários do seu domínio não são redirecionados para o seu IdP e podem receber um erro invalid_user_email_domain ao se autenticar.

Cuidado

Os usuários criados via SSO começam sem acesso a projetos. Conceda acesso a projetos por meio de Grupos (com o mapeamento de grupos) ou adicionando os usuários diretamente aos projetos.

Os usuários de um domínio configurado para SSO devem entrar com SSO em vez de criar uma conta baseada em senha a partir de um link de convite por e-mail.

Usuários existentes e vinculação de contas

As contas criadas antes de o SSO ser habilitado precisam ser vinculadas ao seu provedor de identidade uma vez antes de poderem ser usadas com SSO. Os usuários são orientados nesse processo na primeira vez que entram com SSO, e seus projetos e dados são preservados. As etapas que eles veem estão documentadas em Cadastro e login.

Cuidado

A vinculação exige a senha Prevu3D existente de cada usuário, portanto quem não se lembra da sua precisa redefini-la antes de poder vincular a conta.

Para evitar isso completamente, entre em contato com support@prevu3d.com para vincular todas as contas do seu domínio de e-mail em uma única operação. Assim, os usuários nunca veem o fluxo de vinculação.

Validação da sua configuração

Antes de implantar o SSO de forma ampla, teste com um pequeno grupo de usuários e confirme que:

• O login é concluído com sucesso tanto na página de login do Prevu3D (Entrar com SSO) quanto no painel do seu IdP.

• Os nomes e sobrenomes são preenchidos corretamente nas novas contas.

• Nenhum usuário recebe permissões mais amplas do que o esperado.

• As associações de grupo são aplicadas conforme o esperado, caso você use o mapeamento de grupos.

Nota

Um rastreamento SAML capturado com uma extensão de navegador como o SAML-tracer é a maneira mais rápida de verificar exatamente quais atributos e qual valor de audience o seu IdP está enviando.

Mapeamento de grupos (opcional)

Também é possível mapear grupos do seu sistema IdP para os grupos do Prevu3D a fim de simplificar o gerenciamento de acesso das pessoas da sua organização. As etapas a seguir orientam você no mapeamento dos seus grupos.

• Configure seu IdP para passar as associações de grupo por meio de um atributo SAML.

• Insira esse atributo na aba SSO.

• Na seção “Groups” do Prevu3D, clique em “Edit group” e especifique o valor de grupo SAML esperado pelo seu IdP.

• Esse mapeamento é aplicado aos usuários quando eles fazem login no Prevu3D Cloud. Se o usuário já estiver conectado, ele deve sair e entrar novamente para que as alterações de acesso tenham efeito.

Nota

• O mapeamento de grupos é aplicado no login. Os usuários devem sair e entrar novamente para aplicar o acesso atualizado.

• Certifique-se de que o grupo tenha algum acesso concedido; para mais informações, consulte a seção grupos.

Cuidado

• Se o SCIM estiver habilitado, a criação de grupos e a atribuição de associação devem ser tratadas via SCIM.

SCIM 2.0 – Configuração de provisionamento

O Prevu3D suporta o provisionamento de usuários e grupos por meio do protocolo SCIM 2.0 (System for Cross-Domain Identity Management).

Pré-requisitos

• Sua organização deve estar no plano Enterprise.

• Seu IdP deve suportar SCIM (por exemplo, Azure AD/Entra, Okta, JumpCloud).

O que o SCIM habilita

• Provisionamento de usuários – Novos usuários são criados automaticamente no Prevu3D

• Desprovisionamento de usuários – Os usuários são desabilitados ou removidos quando são desabilitados no seu IdP

• Atribuição de grupos – Grupos e funções podem ser gerenciados centralmente a partir do seu IdP

Guia de configuração

1. Faça login na sua conta Prevu3D como administrador da organização.

2. Vá para a aba Settings

3. Selecione a aba SSO no menu à esquerda

4. Role até a seção SCIM Provisioning e habilite-a.

   

5. Você encontrará:

   • SCIM Base URL (usuários do Entra ID, veja o aviso abaixo)

   • Bearer Token

Nota

Você também pode rotacionar o bearer token quando necessário para segurança ou rotação de credenciais.

Cuidado

Ao configurar o SCIM com o Entra ID (Azure AD), você deve anexar ?aadOptscim062020 ao final da SCIM Base URL fornecida pelo Prevu3D.

6. No seu provedor de identidade (por exemplo, Microsoft Entra ID):

   • Abra o aplicativo empresarial do Prevu3D.

   • Habilite o provisionamento SCIM.

   • Insira a SCIM Base URL e o Bearer Token obtidos na aba SSO.

7. Configure os mapeamentos de atributos para:

   • userName, givenName, familyName, email

   • Opcional: groups, roles, active

8. Salve sua configuração

   Seu IdP agora sincronizará automaticamente usuários e grupos com o Prevu3D com base no cronograma de provisionamento.

Solução de problemas

Sintoma	Causa provável	O que fazer
O login não é concluído depois que o IdP redireciona de volta para o Prevu3D	O valor de audience na asserção SAML não corresponde exatamente ao Service Provider Entity ID. Seu IdP pode estar enviando um valor abreviado ou um nome amigável.	No seu IdP, defina o campo Audience / Identifier / Entity ID com o valor exato mostrado na aba SSO, incluindo o sufixo completo.
O usuário insere seu e-mail e sua senha na página de login e nunca é encaminhado ao IdP	O formulário de login principal serve apenas para contas baseadas em senha.	Peça ao usuário que clique em Entrar com SSO, abaixo do botão Login, e depois insira seu e-mail corporativo.
Nenhum redirecionamento após inserir um e-mail corporativo na tela Entrar com SSO	O domínio de e-mail não está associado à sua organização Prevu3D.	Entre em contato com support@prevu3d.com para configurar seu domínio de e-mail.
{"statusCode":401,"message":"invalid_user_email_domain"} após a autenticação no IdP	Mesma causa: o domínio de e-mail do usuário não está associado à sua organização.	Entre em contato com support@prevu3d.com para configurar seu domínio de e-mail.
O usuário vê “sessão expirada” e é solicitado a inserir novamente o e-mail	Parte normal do fluxo único de vinculação de conta para contas criadas antes de o SSO ser habilitado.	Peça ao usuário que continue; isso não é um erro. Consulte Usuários existentes e vinculação de contas.
Um usuário existente não consegue concluir a vinculação da conta	A vinculação exige a senha Prevu3D existente do usuário, da qual ele pode não se lembrar.	Peça que ele a redefina com Esqueceu a senha ou solicite a vinculação em massa do seu domínio a support@prevu3d.com.
Os nomes aparecem em branco ou incorretos nas novas contas	As SAML Attribute Keys inseridas na aba SSO não correspondem aos nomes de atributos enviados pelo seu IdP. Esses valores diferenciam maiúsculas de minúsculas.	Capture um rastreamento SAML, verifique os nomes de atributos no AttributeStatement e atualize os mapeamentos para que correspondam exatamente.
As alterações de acesso a grupos não estão sendo aplicadas	O mapeamento de grupos é aplicado somente no login.	Peça ao usuário que saia e entre novamente.
Abrir a URL do Service Provider Endpoint diretamente em um navegador retorna {"statusCode":500,"message":"Internal server error"}	Comportamento esperado. Esse endpoint aceita apenas requisições SAML POST e não pode ser aberto diretamente em um navegador.	Isso não indica um problema de configuração. Em vez disso, teste fazendo login pela página de login ou pelo seu IdP.

Nota

Se ainda assim você não conseguir avançar, capture um rastreamento SAML de uma tentativa de login malsucedida, oculte quaisquer valores sensíveis e envie-o para support@prevu3d.com. Inclua o valor de audience e os nomes de atributos exibidos na asserção — isso permite que nossa equipe diagnostique a maioria dos casos de uma só vez.

Solução de problemas de erros de login

Quando alguém não consegue entrar via SSO devido a um problema de configuração, o Prevu3D exibe uma página de erro com um código de erro curto. Como administrador, localize o código correspondente abaixo e siga a correção indicada — cada uma é resolvida na aplicação SAML do seu IdP ou na aba SSO do Prevu3D.

Nota

Alguns erros são exibidos ao usuário por um problema de elegibilidade, e não de configuração — por exemplo, um domínio de e-mail não associado à sua organização, uma conta que não é membro, ou uma conta que ainda precisa ser vinculada (consulte Usuários existentes e vinculação de contas). Esses casos não exigem nenhuma alteração no seu IdP ou na aba SSO.

Configuração não encontrada

Código: ConfigNotFound

Não existe nenhuma configuração SAML para a sua organização — o SSO nunca foi configurado, ou a configuração foi removida.

Como corrigir: Configure o SSO na aba SSO (Settings → SSO) com os metadados do seu IdP — veja Etapas acima — e confirme que a aplicação do seu IdP está direcionada à organização correta do Prevu3D.

Falta a asserção de e-mail

Código: MissingEmailAssertion

A resposta SAML do seu IdP não incluía um endereço de e-mail (nem um NameID).

Como corrigir: Na aplicação SAML do seu IdP, mapeie o atributo de e-mail (ou NameID) para que ele seja incluído na asserção.

Assinatura de resposta inválida

Código: InvalidResponseSignature

A assinatura da resposta SAML falhou na validação. Isso geralmente significa que o certificado armazenado na aba SSO não corresponde mais ao certificado de assinatura atual do seu IdP, ou que a resposta não está assinada.

Como corrigir: Copie o certificado de assinatura x509 atual do seu IdP para a aba SSO, e certifique-se de que o seu IdP esteja configurado para assinar a resposta SAML.

Erro de certificado

Código: CertificateError

O certificado armazenado na aba SSO está malformado, expirado, ou não pôde ser interpretado.

Como corrigir: Cole um certificado x509 válido no formato PEM do seu IdP. Se o atual estiver expirado, faça a rotação dele.

Incompatibilidade de audience

Código: AudienceMismatch

O audience configurado no seu IdP não corresponde ao Service Provider Entity ID que o Prevu3D espera para a sua organização.

Como corrigir: Defina o campo Audience / Identifier / Entity ID no seu IdP com o Service Provider Entity ID exato exibido na aba SSO, incluindo o sufixo completo.

Mapeamento de função inválido

Código: InvalidRoleMapping

Um valor de função enviado pelo seu IdP não corresponde a nenhuma função válida da organização no Prevu3D.

Como corrigir: A atribuição de funções a partir de um atributo SAML foi removida, portanto este código afeta apenas organizações que ainda mantêm um atributo de função de uma configuração anterior. Atribua funções pelo Mapeamento de grupos e entre em contato com support@prevu3d.com se o erro persistir.

Definições

• IdP, Identity Provider (provedor de identidade): refere-se ao sistema que registra todos os usuários e habilita a conexão com vários outros serviços. Esta é a sua fonte de verdade para a sua organização, usuários e grupos. Ex.: Azure AD, JumpCloud…

• SP, Service Provider (provedor de serviço): refere-se ao aplicativo de serviço que consome as informações de SSO, neste caso o Prevu3D Cloud.

• SSO, Single Sign-On: refere-se a um mecanismo que permite aos usuários obter suas credenciais a partir de um único portal e distribuir a configuração de gerenciamento de usuários entre vários aplicativos.

• SAML, Security Assertion Markup Language: um protocolo de todo o setor que permite o uso do SSO em várias plataformas baseadas em nuvem.

• SCIM, System for Cross-Domain Identity Management: protocolo para o provisionamento de usuários e grupos.