Saltar al contenido principal

OpenID Connect

Semaphore admite la autenticación mediante OpenID Connect (OIDC).

Enlaces:

Ejemplo de configuración de un proveedor 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"
    }
  }
}

Configuración mediante variable de entorno​

Al ejecutar en contenedores puede resultar cómodo configurar los proveedores mediante una única variable de entorno:

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

Este valor debe ser una cadena JSON válida que coincida con la estructura de oidc_providers mostrada arriba.

Todas las opciones de un proveedor SSO:

ParámetroDescripción
display_nameNombre del proveedor que se muestra en la pantalla de inicio de sesión.
iconIcono MDI que se muestra delante del nombre del proveedor en la pantalla de inicio de sesión.
colorColor del botón del proveedor que se muestra en la pantalla de inicio de sesión.
client_idID de cliente del proveedor.
client_id_fileRuta al archivo donde se almacena el ID de cliente del proveedor. Tiene menos prioridad que client_id.
client_secretSecreto de cliente del proveedor.
client_secret_fileRuta al archivo donde se almacena el secreto de cliente del proveedor. Tiene menos prioridad que client_secret.
redirect_url
provider_url
scopes
username_claimExpresión de claim para el nombre de usuario*.
email_claimExpresión de claim para el correo electrónico*.
name_claimExpresión de claim para el nombre del perfil*.
orderPosición del botón del proveedor en la pantalla de inicio de sesión.
allow_idp_initiatedHabilita el inicio de sesión iniciado por el IdP para este proveedor. Predeterminado: false.
return_via_statePasa la ruta de retorno posterior al inicio de sesión mediante el parámetro state de OAuth en lugar de la URL de redirección. Predeterminado: true.
endpoint.issuer
endpoint.auth
endpoint.token
endpoint.userinfo
endpoint.jwks
endpoint.algorithms

*Expresión de claim​

Ejemplo de expresión de claim:

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

Semaphore intenta obtener primero el campo email. Si está vacío, se ejecuta la expresión que le sigue.

La expresión "username_claim": "|" genera un username aleatorio para cada usuario que inicia sesión a través del proveedor.

Inicio de sesión iniciado por el IdP​

De forma predeterminada, Semaphore solo admite el inicio de sesión iniciado por el SP: el usuario abre Semaphore, hace clic en el botón del proveedor y es redirigido al proveedor de identidad (IdP).

Con el inicio de sesión iniciado por el IdP, el recorrido puede comenzar en el proveedor de identidad; por ejemplo, haciendo clic en el mosaico de Semaphore en el panel de Okta, en My Apps de Azure o en un lanzador de aplicaciones de Keycloak / Authentik.

Semaphore lo implementa mediante el mecanismo estándar Third-Party Initiated Login (OpenID Connect Core 1.0 §4). El IdP redirige el navegador a una Initiate Login URI dedicada, y Semaphore inicia entonces un flujo Authorization Code normal. La autenticación real sigue siendo un intercambio de código completo y seguro: Semaphore nunca acepta un token no solicitado.

Habilitarlo​

Establezca allow_idp_initiated en true para el proveedor:

{
  "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
    }
  }
}

Configurar el proveedor de identidad​

En su IdP, establezca la Initiate Login URI de la aplicación en:

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

donde <provider-id> es la clave bajo oidc_providers (por ejemplo, mysso).

El IdP debe enviar el parámetro iss (issuer) a este endpoint; Semaphore rechaza las peticiones cuyo iss no coincida con el proveedor configurado. El parámetro opcional login_hint se reenvía al IdP, y un target_link_uri opcional establece la página que se abrirá tras el inicio de sesión (debe apuntar de vuelta a Semaphore; de lo contrario se ignora).

Notas específicas por proveedor:

  • Okta: establezca Login initiated by en Either Okta or App (o App Only) y rellene la Initiate login URI. Okta envía tanto iss como target_link_uri.
  • Keycloak / Authentik / Ping / OneLogin: establezca la URL de lanzamiento / de inicio de la aplicación en la Initiate Login URI.
  • Azure AD / Entra: My Apps utiliza una URL de inicio iniciada por el SP y no siempre envía iss; apunte la URL de inicio a https://your-domain.com/api/auth/oidc/<provider-id>/login en su lugar.

Seguridad​

  • El inicio de sesión iniciado por el IdP está desactivado de forma predeterminada y debe habilitarse por proveedor.
  • El parámetro iss se valida contra el issuer configurado para evitar confusiones entre proveedores.
  • target_link_uri solo se acepta cuando apunta de vuelta a Semaphore (sin redirecciones abiertas).
  • El flujo pasa por el intercambio Authorization Code completo con state CSRF y un nonce, por lo que un token capturado o reproducido no puede usarse para iniciar sesión.

Pantalla de inicio de sesión​

Por cada proveedor configurado se añade un botón de inicio de sesión adicional a la página de inicio de sesión:

Captura de pantalla de la página de inicio de sesión de Semaphore, con dos botones de inicio de sesión. Uno dice "Sign In", el otro dice "Sign in with MySSO"