Configuração de SSO via Azure Active Directory

Modificado em Ter, 17 Mar na (o) 9:49 PM

Nesta página

Visão Geral
Configuração SAML 2.0 Recomendado
Configuração OAuth 2.0 / OIDC Alternativo
- Configurar Azure AD
- Configurar MavenDoc
Comparativo SAML vs OAuth
Solução de Problemas
Referência Rápida

1. Visão Geral

O MavenDoc suporta dois protocolos de SSO (Single Sign-On) com o Azure Active Directory: SAML 2.0 (recomendado) e OAuth 2.0 / OIDC (alternativo). Ambos permitem que os usuários da sua empresa entrem no MavenDoc usando as credenciais corporativas do Azure AD, sem necessidade de senha separada.

SAML 2.0 — Método recomendado

SAML é o padrão adotado pela maioria das integrações corporativas. Utiliza uma Enterprise Application no Azure AD, o que facilita a configuração e o controle de quais usuários têm acesso ao MavenDoc. Requer apenas um único campo de configuração no MavenDoc (a URL de metadados).

OAuth 2.0 / OIDC — Alternativo

Use OAuth quando a sua equipe já possui um App Registration configurado ou quando preferir o modelo de tokens OIDC. Veja as instruções na seção 3.

Como funciona o fluxo SAML

1. Usuário
digita e-mail

→

2. MavenDoc
detecta SAML

→

3. Azure AD
login corporativo

↓

Azure posta SAMLResponse → /resources/auth/saml-acs

4. Validação
assinatura XML

→

5. Código
one-time 2 min

→

6. JWT
emitido

→

7. Acesso
autorizado

2. Configuração SAML 2.0 Recomendado

Pré-requisitos

Acesso de Administrador Global ou Administrador de Aplicativo no Azure AD.
O MavenDoc deve estar acessível via HTTPS público. O Azure posta o SAMLResponse diretamente no servidor.
Permissão de administrador no MavenDoc para editar a configuração da empresa.
Os usuários que farão SSO devem estar pré-cadastrados no MavenDoc com o mesmo e-mail corporativo.

URL HTTPS obrigatória

O Azure AD exige que a URL do ACS use HTTPS. Para testes locais sem certificado SSL, use um tunnel HTTPS (ex.: ngrok) e registre a URL pública no Azure.

URL do ACS (Assertion Consumer Service)

Esta é a URL onde o Azure enviará o SAMLResponse após autenticação:

{URL_DO_MAVENDOC}/resources/auth/saml-acs

Exemplo: https://mavendoc.maven.com.br/mavendoc/resources/auth/saml-acs

Configuração no Azure AD

Criar uma Enterprise Application

Acesse portal.azure.com com conta de administrador.
Navegue para Azure Active Directory → Enterprise applications.
Clique em + New application.
Clique em + Create your own application.
Dê um nome (ex.: MavenDoc SSO) e selecione:
"Integrate any other application you don't find in the gallery (Non-gallery)"
Clique em Create.

Ativar o SAML SSO e configurar as URLs

Na Enterprise Application criada, clique em Single sign-on no menu esquerdo.
Selecione o método SAML.
Na seção "Basic SAML Configuration", clique em Edit (ícone de lápis) e preencha:

Campo	Valor	Exemplo
Identifier (Entity ID)	`{URL_DO_MAVENDOC}`	https://mavendoc.maven.com.br/mavendoc
Reply URL (ACS URL)	`{URL_DO_MAVENDOC}/resources/auth/saml-acs`	https://mavendoc.maven.com.br/mavendoc/resources/auth/saml-acs
Sign on URL	Deixar em branco
Relay State	Deixar em branco
Logout URL	Opcional — deixar em branco

Clique em Save.

Configurar o NameID (e-mail do usuário)

Na seção "Attributes & Claims", clique em Edit. Configure o NameID para enviar o endereço de e-mail:

Campo	Valor recomendado
Name identifier format	Email address
Source attribute	user.mail (e-mail real) ou user.userprincipalname (UPN)

O e-mail deve ser idêntico ao cadastro no MavenDoc

O endereço retornado pelo Azure no NameID deve ser exatamente igual ao e-mail cadastrado para o usuário no MavenDoc (comparação case-insensitive). Se os usuários têm UPN diferente do e-mail real, use user.mail.

Claims adicionais aceitos pelo MavenDoc (por prioridade)

NameID (quando contém "@")
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
http://schemas.microsoft.com/identity/claims/userprincipalname

Adicionar usuários ao aplicativo

Na Enterprise Application, clique em Users and groups.
Clique em + Add user/group.
Selecione os usuários ou grupos do Azure AD que podem usar o MavenDoc via SSO.
Clique em Assign.

Somente usuários atribuídos poderão autenticar

Quando "Assignment required" está ativo na Enterprise Application, apenas os usuários adicionados nesta tela conseguem fazer login via SSO. Isso garante controle de acesso centralizado.

Copiar a URL de metadados do Azure AD

Na seção "SAML Certificates", copie o valor do campo App Federation Metadata Url.

? SAML Certificates → App Federation Metadata Url

Exemplo:
https://login.microsoftonline.com/{tenant-id}/federationmetadata/2007-06/federationmetadata.xml?appid={app-id}

Guarde este URL — é o único campo que você precisará no MavenDoc

Esta URL aponta para o XML de metadados do Azure AD, que contém o certificado de assinatura e o endpoint SSO. O MavenDoc a busca automaticamente e a armazena em cache.

Configuração no MavenDoc

Ativar SAML na empresa

Entre no MavenDoc como administrador.
Acesse Configurações → Empresa.
Localize a seção Autenticação SSO e preencha:

Campo	Valor
Tipo de autenticação	SAML
URL de metadados SAML	Cole a App Federation Metadata Url copiada no Passo 5

Clique em Salvar.
Certifique-se de que todos os usuários SSO estão cadastrados no MavenDoc com o mesmo e-mail do Azure AD.

Pré-cadastro obrigatório

O MavenDoc não cria usuários automaticamente via SAML. O usuário deve existir previamente. Use o módulo Usuários para cadastrá-los.

Passo 7: Testar o login SAML

Abra o MavenDoc em uma aba anônima (para garantir que não há sessão ativa).
Na tela de login, digite o e-mail corporativo de um usuário atribuído ao app no Azure.
Clique em Entrar.
O MavenDoc detecta authType=SAML e redireciona para o Azure AD.
O usuário faz login com as credenciais corporativas (se não estiver já logado).
O Azure valida e posta o SAMLResponse de volta ao MavenDoc.
O MavenDoc valida a assinatura, extrai o e-mail e redireciona para os documentos.

O usuário deve entrar diretamente no MavenDoc sem digitar senha. Se ocorrer algum erro, consulte a Seção 5 — Solução de Problemas.

3. Configuração OAuth 2.0 / OIDC Alternativo - DEPRECATED

Quando usar OAuth em vez de SAML?

Quando já existe um App Registration no Azure e a equipe prefere não criar uma Enterprise Application.
Quando o ambiente técnico já é baseado em OIDC.

Configuração no Azure AD

Criar um App Registration

Acesse Azure Active Directory → App registrations → + New registration.
Preencha:
- Name: MavenDoc OAuth (ou similar)
- Supported account types: Accounts in this organizational directory only
- Redirect URI: Web → {URL_DO_MAVENDOC}/auth/oauth-callback
Clique em Register.

Criar um Client Secret

Acesse Certificates & secrets → + New client secret.
Defina descrição e prazo de validade e clique em Add.
Copie o valor imediatamente — ele não será exibido novamente.

Copiar os valores necessários

Valor	Onde encontrar no Azure
Tenant ID	Azure Active Directory → Overview → "Directory (tenant) ID"
Client ID	App registrations → seu app → Overview → "Application (client) ID"
Client Secret	App registrations → seu app → Certificates & secrets → coluna "Value"

Configuração no MavenDoc (OAuth)

Campo	Valor
Tipo de autenticação	OAUTH
OAuth Issuer	`https://login.microsoftonline.com/{Tenant ID}/v2.0`
OAuth Client ID	Application (client) ID copiado do Azure
OAuth Client Secret	Valor do secret copiado do Azure

4. Comparativo SAML vs OAuth

Critério	SAML 2.0	OAuth 2.0 / OIDC
Tipo de app no Azure	Enterprise Application	App Registration
Campos no MavenDoc	1 (Metadata URL)	3 (Issuer, Client ID, Client Secret)
Rotação de certificado	Automática via metadata	Manual (renovar client secret)
Controle de usuários	Users & Groups na Enterprise App	Azure AD diretamente
Callback recebido por	Backend (POST direto do Azure)	Frontend (redirect com code)
Recomendação	✓ Recomendado	Alternativo

5. Solução de Problemas

SAML

❌ "SAML não está configurado para esta empresa"

Causa: O campo Tipo de autenticação não está como SAML ou a URL de metadados SAML está vazia no MavenDoc.
Solução: Acesse Configurações → Empresa e preencha os dois campos corretamente.

❌ "Failed to fetch SAML metadata" — erro ao buscar metadados

Causa: O servidor MavenDoc não consegue acessar a URL de metadados do Azure.
Soluções:

Abra a URL de metadados no navegador — deve retornar um XML. Se não abrir, a URL está errada.
Verifique se o servidor MavenDoc tem acesso à internet (firewall/proxy).

❌ "SAML authentication failed" — assinatura inválida

Causa: O certificado de assinatura do Azure mudou (rotação) e está em cache desatualizado.
Solução: Reinicie a aplicação MavenDoc para limpar o cache de metadados. O certificado será buscado novamente automaticamente.

❌ "The response was received at X instead of Y" — URL do ACS incorreta

Causa: A Reply URL (ACS URL) no Azure não bate com a URL pública do servidor.
Soluções:

Corrija a Reply URL no Azure: {URL_PUBLICA_MAVENDOC}/resources/auth/saml-acs
Se o servidor está atrás de proxy reverso, configure-o para passar os cabeçalhos X-Forwarded-Proto e X-Forwarded-Host.
Verifique se a propriedade path.maven no environment.properties aponta para a URL pública correta.

❌ "Incompatibilidade de identidade" — e-mail não coincide

Causa: O e-mail no SAMLResponse do Azure difere do e-mail digitado no login.
Soluções:

Verifique o NameID: no Azure, defina Source attribute = user.mail.
Certifique-se que o usuário está cadastrado no MavenDoc com o mesmo e-mail que o Azure envia.

❌ "Usuário não encontrado" no MavenDoc

Causa: O usuário não está cadastrado no MavenDoc.
Solução: Cadastre o usuário em Usuários com o mesmo e-mail corporativo, antes de ativar o SSO para ele.

❌ "Sessão SAML inválida ou expirada"

Causa: O fluxo SAML demorou mais de 10 minutos ou o usuário acessou um link de callback já usado.
Solução: Tente fazer login novamente. Se persistir, verifique a sincronização de horário (NTP) no servidor.

OAuth

❌ AADSTS50011 — The redirect URI doesn't match

Causa: A Redirect URI no Azure não corresponde à URL do MavenDoc.
Solução: App Registration → Authentication → Redirect URIs → confirme que o valor é exatamente {URL_DO_MAVENDOC}/auth/oauth-callback.

❌ AADSTS7000215 — Invalid client secret

Causa: O Client Secret expirou ou está incorreto.
Solução: Gere um novo Client Secret no Azure e atualize nas configurações da empresa no MavenDoc.

❌ "Email not found in Azure ID token"

Causa: O ID token não contém claims de e-mail.
Solução: No App Registration → Token configuration, adicione o optional claim email para ID tokens.

6. Referência Rápida

Valores a cadastrar no Azure (SAML)

Campo Azure	Valor
Identifier (Entity ID)	`{URL_DO_MAVENDOC}` — ex.: https://app.empresa.com.br/mavendoc/
Reply URL (ACS URL)	`{URL_DO_MAVENDOC}/resources/auth/saml-acs`
NameID format	Email address
NameID source attribute	user.mail

Campos no MavenDoc por protocolo

Protocolo	Campo	Valor
SAML	Tipo de autenticação	SAML
SAML	URL de metadados SAML	App Federation Metadata Url do Azure
OAuth	Tipo de autenticação	OAUTH
	OAuth Issuer	`https://login.microsoftonline.com/{TenantID}/v2.0`
	OAuth Client ID	Application (client) ID
	OAuth Client Secret	Valor do client secret

Endpoints do MavenDoc

Protocolo	Endpoint	Descrição
SAML	`GET /resources/auth/saml-init?email=xxx`	Inicia fluxo SAML, retorna `ssoUrl`
SAML	`POST /resources/auth/saml-acs`	ACS — recebe SAMLResponse do Azure, redireciona ao SPA
SAML	`POST /resources/auth/saml-exchange`	Troca samlCode por JWT
OAuth	`GET /resources/auth/oauth-init?email=xxx&redirectUri=xxx`	Inicia fluxo OAuth, retorna `authorizationUrl`
OAuth	`POST /resources/auth/oauth-callback`	Troca code+state por JWT
Ambos	`GET /resources/auth/check-auth-type?email=xxx`	Retorna `authType` da empresa do usuário