Configuração de SSO

A NexBasira suporta tanto OpenID Connect (OIDC) como SAML 2.0 Web Browser SSO. Os utilizadores nos domínios de email configurados iniciam sessão via o seu fornecedor de identidade; os primeiros inícios de sessão são aprovisionados just-in-time com o papel por defeito que escolher.

Antes de começar

• Precisa de um papel org_admin do lado da NexBasira.
• Precisa de acesso ao administrador do seu IdP para registar uma aplicação + configurar o mapeamento de atributos.
• O SSO está disponível no escalão Pro e acima (ver preços).

Walkthrough OIDC

1. Encontre o seu URL de callback

Na SPA da NexBasira: Admin → SSO → Protocolo: OpenID Connect. O URL de callback é apresentado no topo do formulário:

https://app.nexbasira.com/api/v1/auth/sso/callback

Os clientes com domínio personalizado (Pro+) veem aqui o seu próprio domínio. Copie isto — o seu IdP precisa dele.

2. Registe uma aplicação no seu IdP

Cada IdP tem a sua própria interface, mas a forma é a mesma:

• Tipo de aplicação: Web (do lado do servidor, cliente confidencial)
• Redirect URI: o URL de callback do passo 1
• Tipos de grant permitidos: Authorization Code (com PKCE)
• Scopes: openid + email + profile

O IdP devolve-lhe um Client ID, um Client Secret e o Issuer URL (o URL base para descoberta — normalmente https://your-idp.example.com/realms/yourrealm ou https://accounts.google.com).

3. Preencha a configuração de SSO

De volta a Admin → SSO, preencha o formulário:

• Nome de apresentação: mostrado no botão "Continuar com SSO". Ex.: "Acme SSO".
• Issuer URL: do seu IdP.
• Client ID + Client Secret do seu IdP.
• Domínios de email: lista separada por vírgulas (acme.com, acme-eu.com). Os utilizadores com emails nestes domínios são encaminhados via SSO.
• Papel por defeito para novos utilizadores: normalmente inspector. Os administradores da organização devem receber o papel org_admin manualmente após o primeiro início de sessão.
• Aprovisionar automaticamente novos utilizadores no primeiro início de sessão: tipicamente ativado.
• Ativado: desligado até ter testado.

4. Teste a descoberta

Clique em Testar descoberta. Vai buscar a configuração OpenID do seu IdP ({issuer_url}/.well-known/openid-configuration) + faz o parse do JWKS. Erros comuns:

• OK — N chaves JWKS: está concluído.
• Ligação recusada / falha de DNS: erro de escrita no issuer URL; verifique se resolve no seu navegador.
• Erro de parse JSON: o issuer URL aponta para algo que não é um fornecedor OIDC.
• Sem chaves JWKS: o probe teve êxito mas o endpoint JWKS devolveu um conjunto vazio; verifique a rotação de chaves do lado do IdP.

5. Ative + teste de fumo

Ative Ativado, guarde. Termine a sessão e depois inicie sessão com um email num dos domínios permitidos. Deverá ser redirecionado para o ecrã de login do seu IdP e depois de volta ao dashboard da SPA.

Walkthrough SAML 2.0

1. Encontre o seu URL de ACS

Em Admin → SSO → Protocolo: SAML 2.0, copie o URL do Assertion Consumer Service:

https://app.nexbasira.com/api/v1/auth/saml/acs

2. Registe uma aplicação SAML no seu IdP

• ACS URL / Reply URL: o URL do passo 1.
• Entity ID (audience): https://app.nexbasira.com/saml/sp (ou o seu domínio personalizado).
• Formato de NameID: emailAddress.
• Mapeamento de atributos: pelo menos email; idealmente também givenName + surname.
• Assinar assertions: obrigatório.

O IdP devolve-lhe um Entity ID, um SSO Service URL e um certificado de assinatura (PEM).

3. Preencha a configuração SAML

• IdP Entity ID — do seu IdP.
• IdP SSO Service URL — do seu IdP.
• Certificado de assinatura do IdP (PEM) — cole o bloco -----BEGIN CERTIFICATE----- completo.
• Domínios de email — mesma forma que no OIDC.
• Papel por defeito + aprovisionamento automático — igual ao OIDC.

A secção Avançado — mapeamento de atributos permite sobrepor as URNs que procuramos; os valores por defeito correspondem à convenção WS-Federation da Microsoft, que a maioria dos IdPs respeita de imediato.

4. Ative + teste de fumo

Mesmo fluxo do OIDC: ative Ativado, termine a sessão, inicie sessão com um email de domínio permitido, espere uma ida e volta pelo seu IdP.

IdPs testados

O suporte de OIDC + SAML da NexBasira é genérico; qualquer IdP conforme à especificação funciona. Fizemos testes de fumo com:

• Microsoft Entra ID (Azure AD) — OIDC + SAML
• Google Workspace — OIDC + SAML
• Okta — OIDC + SAML
• Keycloak — OIDC + SAML
• OneLogin — SAML

Regras de aprovisionamento JIT

• Na primeira vez que um utilizador com um domínio correspondente inicia sessão via SSO, é criada uma Membership com o papel por defeito configurado.
• O email é a chave única. Um utilizador que mude o email no IdP cria uma nova conta.
• As alterações de papel após o primeiro início de sessão são geridas na SPA (Admin → Membros), não no IdP. Para mapeamento grupo → papel conduzido pelo IdP, ver aprovisionamento SCIM.

Desativar o SSO

Ou desative Ativado (mantém a configuração; pode reativar mais tarde) ou clique em Remover SSO (elimina a configuração). Com o SSO desativado, todos os utilizadores recorrem à autenticação por palavra-passe; as memberships existentes são preservadas.

Resolução de problemas

O que vem a seguir

• Aprovisionamento SCIM — criação + desativação de utilizadores conduzida pelo IdP
• Autenticação da API — separada do SSO da SPA