OpenID Connect

O Semaphore oferece suporte à autenticação via OpenID Connect (OIDC).

Links:

• Configuração do GitHub
• Configuração do Google
• Configuração do GitLab
• Configuração do Authelia
• Configuração do Authentik
• Configuração do Keycloak
• Configuração do Okta
• Configuração do PingFederate
• Configuração do Azure
• Configuração do Zitadel
• Configuração do Pocket-ID

Exemplo de configuração de provedor SSO:

{
  "oidc_providers": {
    "mysso": {
      "display_name": "Sign in with MySSO",
      "color": "orange",
      "icon": "login",
      "provider_url": "https://mysso-provider.com",
      "client_id": "***",
      "client_secret": "***",
      "redirect_url": "https://your-domain.com/api/auth/oidc/mysso/redirect"
    }
  }
}

Configurar via variável de ambiente

Ao executar em contêineres, pode ser conveniente configurar os provedores usando uma única variável de ambiente:

SEMAPHORE_OIDC_PROVIDERS='{
  "github": {
    "client_id": "***",
    "client_secret": "***"
  }
}'

Esse valor deve ser uma string JSON válida que corresponda à estrutura de oidc_providers mostrada acima.

Todas as opções de provedor SSO:

Parâmetro	Descrição
display_name	Nome do provedor exibido na tela de login.
icon	Ícone MDI exibido antes do nome do provedor na tela de login.
color	Cor do provedor exibida na tela de login.
client_id	ID de cliente do provedor.
client_id_file	Caminho do arquivo onde o ID de cliente do provedor está armazenado. Tem prioridade menor que client_id.
client_secret	Segredo de cliente do provedor.
client_secret_file	Caminho do arquivo onde o segredo de cliente do provedor está armazenado. Tem prioridade menor que client_secret.
redirect_url
provider_url
scopes
username_claim	Expressão de claim do nome de usuário*.
email_claim	Expressão de claim do e-mail*.
name_claim	Expressão de claim do nome do perfil*.
order	Posição do botão do provedor na tela de login.
allow_idp_initiated	Habilita o login iniciado pelo IdP para este provedor. Padrão: false.
return_via_state	Passa o caminho de retorno pós-login pelo parâmetro OAuth state em vez da URL de redirecionamento. Padrão: true.
endpoint.issuer
endpoint.auth
endpoint.token
endpoint.userinfo
endpoint.jwks
endpoint.algorithms

*Expressão de claim

Exemplo de expressão de claim:

email | {{ .username }}@your-domain.com

O Semaphore tenta primeiro obter o campo email. Se ele estiver vazio, a expressão seguinte é executada.

A expressão "username_claim": "|" gera um username aleatório para cada usuário que faz login por meio do provedor.

Login iniciado pelo IdP

Por padrão, o Semaphore oferece suporte apenas ao login iniciado pelo SP: o usuário abre o Semaphore, clica no botão do provedor e é redirecionado para o provedor de identidade (IdP).

Com o login iniciado pelo IdP, a jornada pode começar no provedor de identidade — por exemplo, clicando no bloco do Semaphore no painel do Okta, no My Apps do Azure ou em um lançador de aplicações do Keycloak / Authentik.

O Semaphore implementa isso usando o mecanismo padrão Third-Party Initiated Login (OpenID Connect Core 1.0 §4). O IdP redireciona o navegador para uma Initiate Login URI dedicada, e o Semaphore então inicia um fluxo Authorization Code normal. A autenticação em si continua sendo uma troca de código completa e segura — o Semaphore nunca aceita um token não solicitado.

Habilitando

Defina allow_idp_initiated como true para o provedor:

{
  "oidc_providers": {
    "mysso": {
      "display_name": "Sign in with MySSO",
      "provider_url": "https://mysso-provider.com",
      "client_id": "***",
      "client_secret": "***",
      "redirect_url": "https://your-domain.com/api/auth/oidc/mysso/redirect",
      "allow_idp_initiated": true
    }
  }
}

Configurando o provedor de identidade

No seu IdP, defina a Initiate Login URI da aplicação como:

https://your-domain.com/api/auth/oidc/<provider-id>/initiate

onde <provider-id> é a chave em oidc_providers (por exemplo, mysso).

O IdP deve enviar o parâmetro iss (issuer) para esse endpoint; o Semaphore rejeita requisições cujo iss não corresponda ao provedor configurado. O parâmetro opcional login_hint é encaminhado ao IdP, e um target_link_uri opcional define a página a ser aberta após o login (ele deve apontar de volta para o Semaphore; caso contrário, é ignorado).

Observações específicas por provedor:

• Okta — defina Login initiated by como Either Okta or App (ou App Only) e preencha a Initiate login URI. O Okta envia tanto iss quanto target_link_uri.
• Keycloak / Authentik / Ping / OneLogin — defina a URL de lançamento / página inicial da aplicação como a Initiate Login URI.
• Azure AD / Entra — o My Apps usa uma URL inicial iniciada pelo SP e nem sempre envia iss; aponte a URL inicial para https://your-domain.com/api/auth/oidc/<provider-id>/login em vez disso.

Segurança

• O login iniciado pelo IdP fica desativado por padrão e deve ser habilitado por provedor.
• O parâmetro iss é validado em relação ao issuer configurado para evitar confusão de provedores.
• target_link_uri é aceito somente quando aponta de volta para o Semaphore (sem redirecionamentos abertos).
• O fluxo passa pela troca completa de Authorization Code com state CSRF e um nonce, portanto um token capturado ou reproduzido não pode ser usado para fazer login.

Tela de login

Para cada um dos provedores configurados, um botão de login adicional é adicionado à página de login: