Configurando Azure AD para EK SSO

Este guia orienta a configuração do Azure Active Directory (Entra ID) como o Identity Provider (IdP) para o SAML SSO na sua instância EK on-premise. Ele abrange as configurações SAML a serem inseridas no Azure AD, como recuperar seus metadados de federação e como registrar o domínio no EK para completar a integração.

O fluxo genérico SAML do EK funciona com o Azure AD / Entra ID nativamente. Se você ainda não leu, consulte a Visão Geral do SAML SSO para entender como a integração funciona antes de começar.

Pré-requisitos

Você tem acesso de administrador ao seu tenant Azure AD / Entra ID.
Você tem acesso de Super Admin à sua instância EK on-premise.
Você conhece o nome de domínio totalmente qualificado (FQDN) do host do backend do EK (por exemplo, ek-api.corp.acme.com).
Você conhece o domínio de e-mail para o qual deseja habilitar o SSO (por exemplo, acme.com).

Parte 1 — Configurar o Azure AD

Criar uma Nova Aplicação Empresarial no Azure AD

Criar uma nova aplicação empresarial

No portal do Azure, navegue até Azure Active Directory → Enterprise applications e clique em New application. Selecione Create your own application, dê um nome (por exemplo, EK SSO) e escolha Integrate any other application you don’t find in the gallery (Non-gallery).

Abrir a configuração de SSO

Depois que a aplicação for criada, navegue até Manage → Single sign-on e selecione SAML como o método de login.

Inserir a Configuração Básica de SAML

Na seção Basic SAML Configuration, insira os seguintes valores:

Campo	Valor
Identifier (Entity ID)	`https://<your-FQDN>/backend/user/generic/sso/saml/acs/admin`
Reply URL (ACS URL)	`https://<your-FQDN>/backend/user/generic/sso/saml/acs/admin`
Sign-on URL	Deixe vazio
Relay State	`default`
Logout URL	Deixe vazio

Configurar atributos e claims

Na seção Attributes & Claims, confirme ou adicione os seguintes mapeamentos:

Atributos	Valor
`givenname`	`user.givenname`
`surname`	`user.surname`
`emailaddress`	`user.mail`
`name`	`user.userprincipalname`
`DisplayName`	`user.displayname`
`email`	`user.mail`
Unique User Identifier (Name ID)	`user.userprincipalname`

Parte 2 — Recuperar os Metadados do Azure AD

Depois que a aplicação Azure AD estiver configurada, recupere a URL de metadados de federação:

Ir para a seção de Certificados SAML

Na sua aplicação, navegue até Manage → Single sign-on → SAML Certificates.

Copiar a URL de Metadados de Federação da Aplicação

Encontre e copie a App Federation Metadata URL.O caminho é:

Manage > Single sign-on > SAML Certificates > App Federation Metadata URL

Você precisará desta URL na Parte 3.
URL de Metadados do Azure AD

Parte 3 — Registrar o Domínio no EK

Envie uma requisição POST para o endpoint de registro de domínio:

curl -X POST "https://<your-backend-host>/backend/sso/add_new_configuration" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "enterprise_id": "acme.com",
    "provider": "azure",
    "metadata_url": "https://your-azure-federation-metadata-url",
    "backend_root_url": "<your-backend-host>/backend"
  }'

Campos Obrigatórios

Campo	Descrição
`enterprise_id`	O domínio de e-mail dos seus usuários (por exemplo, `acme.com`).
`provider`	`"azure"`
`metadata_url`	A URL de Metadados de Federação da Parte 2.
`backend_root_url`	(Opcional) Necessário apenas em configurações de proxy para garantir o roteamento correto.

Autenticação

O endpoint requer sua API Key e Secret do EK, passadas como cabeçalhos X-API-KEY e X-API-SECRET. Em caso de sucesso, um registro é criado na tabela sso_providers no backend.

Parte 4 — Configurar o Frontend

Depois que o domínio estiver registrado, defina a variável de ambiente do frontend e reinicie o serviço do frontend.

Abrir o arquivo de ambiente do frontend

No seu servidor de implantação on-premise, abra onprem-deployment/.env.web.

Adicionar a variável de ambiente

Adicione a seguinte linha, substituindo acme.com pelo seu domínio de e-mail real:

VITE_SSO_ENTERPRISE_ID=acme.com

Reiniciar os serviços do frontend

docker compose -f docker-compose down
docker compose -f docker-compose up -d

Testar a Integração

Faça login no EK com um usuário real @<domínio> para confirmar que o fluxo funciona de ponta a ponta. Se o usuário autenticar com sucesso, mas tiver o acesso negado, verifique sua configuração de Controles de Acesso SAML — consulte o guia Controles de Acesso SAML e Atribuição Automatizada de Equipe/Projeto do EK.

Get Started!

Offerings

Chat

Agents

Knowledge Base

Workflows

Public Chatbot

Project Settings

My Account

Platform Admin

SDK

General Information

Pré-requisitos

Parte 1 — Configurar o Azure AD

Criar uma Nova Aplicação Empresarial no Azure AD

Parte 2 — Recuperar os Metadados do Azure AD

Parte 3 — Registrar o Domínio no EK

Campos Obrigatórios

Autenticação

Parte 4 — Configurar o Frontend

Testar a Integração

​Pré-requisitos

​Parte 1 — Configurar o Azure AD

​Criar uma Nova Aplicação Empresarial no Azure AD

​Parte 2 — Recuperar os Metadados do Azure AD

​Parte 3 — Registrar o Domínio no EK

​Campos Obrigatórios

​Autenticação

​Parte 4 — Configurar o Frontend

​Testar a Integração

Pré-requisitos

Parte 1 — Configurar o Azure AD

Criar uma Nova Aplicação Empresarial no Azure AD

Parte 2 — Recuperar os Metadados do Azure AD

Parte 3 — Registrar o Domínio no EK

Campos Obrigatórios

Autenticação

Parte 4 — Configurar o Frontend

Testar a Integração