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ámetro	Descripción
`display_name`	Nombre del proveedor que se muestra en la pantalla de inicio de sesión.
`icon`	Icono MDI que se muestra delante del nombre del proveedor en la pantalla de inicio de sesión.
`color`	Color del botón del proveedor que se muestra en la pantalla de inicio de sesión.
`client_id`	ID de cliente del proveedor.
`client_id_file`	Ruta al archivo donde se almacena el ID de cliente del proveedor. Tiene menos prioridad que `client_id`.
`client_secret`	Secreto de cliente del proveedor.
`client_secret_file`	Ruta al archivo donde se almacena el secreto de cliente del proveedor. Tiene menos prioridad que `client_secret`.
`redirect_url`
`provider_url`
`scopes`
`username_claim`	Expresión de claim para el nombre de usuario*.
`email_claim`	Expresión de claim para el correo electrónico*.
`name_claim`	Expresión de claim para el nombre del perfil*.
`groups_claim`	Nombre del claim del token con los grupos del usuario. Lo usan las asignaciones de grupo.
`order`	Posición del botón del proveedor en la pantalla de inicio de sesión.
`allow_idp_initiated`	Habilita el inicio de sesión iniciado por el IdP para este proveedor. Predeterminado: `false`.
`return_via_state`	Pasa 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.

Roles de proyecto a partir de grupos Enterprise

info

Las asignaciones de grupo están disponibles en la edición Semaphore Enterprise.

Una asignación de grupo da un rol de proyecto a cada usuario de un grupo del proveedor de identidad. Por ejemplo, una asignación puede dar a los miembros del grupo devops el rol Gestor en el proyecto Infrastructure.

Enviar los grupos en el token

Establezca groups_claim con el nombre del claim que contiene los grupos del usuario. Sin este ajuste, los inicios de sesión a través del proveedor no cambian los roles de asignaciones de grupo.

Los grupos deben estar en el token de ID. Muchos proveedores de identidad, por ejemplo Dex, envían los grupos solo cuando Semaphore pide el scope groups:

{
  "oidc_providers": {
    "dex": {
      "display_name": "Sign in with Dex",
      "provider_url": "https://dex.your-domain.com",
      "client_id": "***",
      "client_secret": "***",
      "redirect_url": "https://your-domain.com/api/auth/oidc/dex/redirect",
      "scopes": ["openid", "email", "profile", "groups"],
      "groups_claim": "groups"
    }
  }
}

Crear una asignación de grupo

Abra el menú de administración de la parte inferior izquierda y seleccione Group mappings.
Seleccione New mapping.
Elija el proveedor, escriba el nombre del grupo y elija el proyecto y el rol.
Seleccione Guardar.

El nombre del grupo debe coincidir exactamente con el nombre del token, incluidas las mayúsculas y minúsculas. Para cambiar una asignación de grupo, elimínela y cree una nueva.

Semaphore actualiza los roles de asignaciones de grupo cada vez que el usuario inicia sesión a través del proveedor. Un usuario que sale de un grupo conserva el rol hasta su próximo inicio de sesión. Para que estos cambios tengan efecto antes, limite la duración de la sesión con auth.max_session_life_hours.

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.

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"

Configuración mediante variable de entorno​

*Expresión de claim​

Roles de proyecto a partir de grupos Enterprise​

Enviar los grupos en el token​

Crear una asignación de grupo​

Inicio de sesión iniciado por el IdP​

Habilitarlo​

Configurar el proveedor de identidad​

Seguridad​

Pantalla de inicio de sesión​