OpenID Connect

Semaphore supporta l'autenticazione tramite OpenID Connect (OIDC).

Collegamenti:

• Configurazione GitHub
• Configurazione Google
• Configurazione GitLab
• Configurazione Authelia
• Configurazione Authentik
• Configurazione Keycloak
• Configurazione Okta
• Configurazione PingFederate
• Configurazione Azure
• Configurazione Zitadel
• Configurazione Pocket-ID

Esempio di configurazione di un provider 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"
    }
  }
}

Configurazione tramite variabile d'ambiente

Quando si esegue in container, può essere comodo configurare i provider tramite un'unica variabile d'ambiente:

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

Questo valore deve essere una stringa JSON valida corrispondente alla struttura oidc_providers mostrata sopra.

Tutte le opzioni del provider SSO:

Parametro	Descrizione
display_name	Nome del provider visualizzato nella schermata di accesso.
icon	Icona MDI visualizzata prima del nome del provider nella schermata di accesso.
color	Nome del provider visualizzato nella schermata di accesso.
client_id	Client ID del provider.
client_id_file	Percorso del file in cui è memorizzato il client ID del provider. Ha priorità inferiore rispetto a client_id.
client_secret	Client secret del provider.
client_secret_file	Percorso del file in cui è memorizzato il client secret del provider. Ha priorità inferiore rispetto a client_secret.
redirect_url
provider_url
scopes
username_claim	Espressione del claim per il nome utente*.
email_claim	Espressione del claim per l'email*.
name_claim	Espressione del claim per il nome del profilo*.
groups_claim	Nome del claim del token che contiene i gruppi dell'utente. Usato dalle mappature di gruppo.
order	Posizione del pulsante del provider nella schermata di accesso.
allow_idp_initiated	Abilita l'accesso avviato dall'IdP per questo provider. Valore predefinito false.
return_via_state	Passa il percorso di ritorno post-accesso tramite il parametro OAuth state invece che tramite l'URL di redirect. Valore predefinito true.
endpoint.issuer
endpoint.auth
endpoint.token
endpoint.userinfo
endpoint.jwks
endpoint.algorithms

*Espressione del claim

Esempio di espressione del claim:

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

Semaphore tenta prima di ottenere il campo email. Se questo è vuoto, viene valutata l'espressione successiva.

L'espressione "username_claim": "|" genera uno username casuale per ogni utente che accede tramite il provider.

Ruoli di Project dai gruppi Enterprise

informazioni

Le mappature di gruppo sono disponibili nell'edizione Semaphore Enterprise.

Una mappatura di gruppo dà un ruolo di Project a ogni utente di un gruppo dell'identity provider. Ad esempio, una mappatura può dare ai membri del gruppo devops il ruolo Manager nel Project Infrastructure.

Inviare i gruppi nel token

Impostare groups_claim sul nome del claim che contiene i gruppi dell'utente. Senza questa impostazione, gli accessi tramite il provider non cambiano i ruoli dalle mappature di gruppo.

I gruppi devono essere nell'ID token. Molti identity provider, ad esempio Dex, inviano i gruppi solo quando Semaphore richiede lo 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"
    }
  }
}

Creare una mappatura di gruppo

1. Aprire il menu di amministrazione in basso a sinistra e selezionare Group mappings.
2. Selezionare New mapping.
3. Scegliere il provider, inserire il nome del gruppo e scegliere il Project e il ruolo.
4. Selezionare Save.

Il nome del gruppo deve corrispondere esattamente al nome nel token, comprese le maiuscole e le minuscole. Per cambiare una mappatura di gruppo, eliminarla e crearne una nuova.

Semaphore aggiorna i ruoli dalle mappature di gruppo ogni volta che l'utente accede tramite il provider. Un utente che lascia un gruppo mantiene il ruolo fino al suo prossimo accesso. Per rendere effettive prima queste modifiche, limitare la durata della sessione con auth.max_session_life_hours.

Accesso avviato dall'IdP

Per impostazione predefinita Semaphore supporta solo l'accesso avviato dall'SP: l'utente apre Semaphore, fa clic sul pulsante del provider e viene reindirizzato all'identity provider (IdP).

Con l'accesso avviato dall'IdP il percorso può invece iniziare dall'identity provider, ad esempio facendo clic sul riquadro di Semaphore nella dashboard di Okta, in My Apps di Azure o in un launcher di applicazioni di Keycloak / Authentik.

Semaphore implementa questa funzionalità tramite il meccanismo standard Third-Party Initiated Login (OpenID Connect Core 1.0 §4). L'IdP reindirizza il browser a un Initiate Login URI dedicato e Semaphore avvia quindi un normale flusso Authorization Code. L'autenticazione vera e propria rimane uno scambio di codice completo e sicuro: Semaphore non accetta mai un token non richiesto.

Abilitazione

Impostare allow_idp_initiated a true per il provider:

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

Configurazione dell'identity provider

Nel proprio IdP, impostare l'Initiate Login URI dell'applicazione a:

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

dove <provider-id> è la chiave sotto oidc_providers (ad esempio mysso).

L'IdP deve inviare a questo endpoint il parametro iss (issuer); Semaphore rifiuta le richieste il cui iss non corrisponde al provider configurato. Il parametro opzionale login_hint viene inoltrato all'IdP e il parametro opzionale target_link_uri imposta la pagina da aprire dopo l'accesso (deve puntare a Semaphore, altrimenti viene ignorato).

Note specifiche per provider:

• Okta — impostare Login initiated by su Either Okta or App (oppure App Only) e compilare Initiate login URI. Okta invia sia iss sia target_link_uri.
• Keycloak / Authentik / Ping / OneLogin — impostare l'URL di avvio / home dell'applicazione sull'Initiate Login URI.
• Azure AD / Entra — My Apps utilizza un URL di avvio SP-initiated e non invia sempre iss; puntare invece l'URL di avvio a https://your-domain.com/api/auth/oidc/<provider-id>/login.

Sicurezza

• L'accesso avviato dall'IdP è disattivato per impostazione predefinita e deve essere abilitato per ogni provider.
• Il parametro iss viene convalidato rispetto all'issuer configurato per prevenire confusioni tra provider.
• target_link_uri viene accettato solo se punta a Semaphore (nessun open redirect).
• Il flusso passa attraverso lo scambio Authorization Code completo con state CSRF e un nonce, quindi un token intercettato o riutilizzato non può essere usato per accedere.

Schermata di accesso

Per ciascuno dei provider configurati, alla pagina di accesso viene aggiunto un ulteriore pulsante di accesso: