Configurando Okta para EK SSO

Este guia orienta a configuração do Okta 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 Okta, como recuperar seus metadados do Okta e como registrar o domínio no EK para completar a integração.

Nota

O fluxo genérico SAML do EK funciona com o Okta 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 à sua organização Okta.
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 Okta

Criar uma Nova Aplicação SAML no Okta

Criar uma nova integração de aplicação
No seu console de administração do Okta, navegue até Applications → Applications e clique em Create App Integration. Selecione SAML 2.0 como o método de login.

Inserir as configurações SAML

No passo Configure SAML, insira os seguintes valores:

Campo	Valor
Single Sign-On URL	`https://<your-FQDN>/backend/user/generic/sso/saml/acs/admin`
Recipient URL	`https://<your-FQDN>/backend/user/generic/sso/saml/acs/admin`
Destination URL	`https://<your-FQDN>/backend/user/generic/sso/saml/acs/admin`
Audience Restriction (Entity ID)	`https://<your-FQDN>/backend/user/generic/sso/saml/acs/admin`
Default Relay State	`default` ou defina para o nome do domínio

Adicionar declarações de atributos

Ainda no passo Configure SAML, role para baixo até Attribute Statements e adicione o seguinte:

Nome	Formato do Nome	Valor
`email`	Basic	`user.email`
`first_name`	Basic	`user.firstName`
`last_name`	Basic	`user.lastName`
`user_name`	Basic	`user.login`
`DisplayName`	Basic	`user.displayName`
`objectIdentifier`	Unspecified	`user.getInternalProperty("id")`

Concluir a configuração
Finalize o assistente de criação da aplicação. Atribua a aplicação aos usuários ou grupos que devem ter acesso SSO ao EK.

Parte 2 — Recuperar os Metadados do Okta

Depois que a aplicação Okta for criada, recupere a URL de metadados do IdP:

Ir para a aba Sign On
Abra a aplicação no Okta e navegue até a aba Sign On.
Encontrar a URL de Metadados
Em Settings → SAML 2.0 → Metadata details, copie a Metadata URL.
O caminho é:
```
Sign On > Settings > SAML 2.0 > Metadata details > Metadata URL
```
Você precisará desta URL na Parte 3.

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": "okta",
    "metadata_url": "https://your-okta-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`	`"okta"`
`metadata_url`	A URL de Metadados 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.

Pré-requisitos​

Parte 1 — Configurar o Okta​

Criar uma Nova Aplicação SAML no Okta​

Parte 2 — Recuperar os Metadados do Okta​

Parte 3 — Registrar o Domínio no EK​

Campos Obrigatórios​

Autenticação​

Parte 4 — Configurar o Frontend​

Testar a Integração​