doc-locale/fr-fr/administration/auth/oidc.md
{{< details >}}
{{< /details >}}
Vous pouvez utiliser GitLab comme application cliente avec OpenID Connect en tant que fournisseur OmniAuth.
Pour activer le fournisseur OmniAuth OpenID Connect, vous devez enregistrer votre application auprès d'un fournisseur OpenID Connect. Le fournisseur OpenID Connect vous fournit les informations et le secret du client à utiliser.
Sur votre serveur GitLab, ouvrez le fichier de configuration.
Pour les installations de packages Linux :
sudo editor /etc/gitlab/gitlab.rb
Pour les installations compilées manuellement :
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
Configurez les paramètres communs pour ajouter openid_connect comme fournisseur d'authentification unique. Cela active le provisionnement de compte juste-à-temps pour les utilisateurs qui n'ont pas de compte GitLab existant.
Ajoutez la configuration du fournisseur.
Pour les installations de packages Linux :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect", # do not change this parameter
label: "Provider name", # optional label for login button, defaults to "Openid Connect"
icon: "<custom_provider_icon>",
args: {
name: "openid_connect",
scope: ["openid","profile","email"],
response_type: "code",
issuer: "<your_oidc_url>",
discovery: true,
client_auth_method: "query",
uid_field: "<uid_field>",
send_scope_to_token_endpoint: "false",
pkce: true,
client_options: {
identifier: "<your_oidc_client_id>",
secret: "<your_oidc_client_secret>",
redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback"
}
}
}
]
Pour les installations de packages Linux avec plusieurs fournisseurs d'identité :
{ 'name' => 'openid_connect',
'label' => '...',
'icon' => '...',
'args' => {
'name' => 'openid_connect',
'strategy_class': 'OmniAuth::Strategies::OpenIDConnect',
'scope' => ['openid', 'profile', 'email'],
'discovery' => true,
'response_type' => 'code',
'issuer' => 'https://...',
'client_auth_method' => 'query',
'uid_field' => '...',
'client_options' => {
`identifier`: "<your_oidc_client_id>",
`secret`: "<your_oidc_client_secret>",
'redirect_uri' => 'https://.../users/auth/openid_connect/callback'
}
}
},
{ 'name' => 'openid_connect_2fa',
'label' => '...',
'icon' => '...',
'args' => {
'name' => 'openid_connect_2fa',
'strategy_class': 'OmniAuth::Strategies::OpenIDConnect',
'scope' => ['openid', 'profile', 'email'],
'discovery' => true,
'response_type' => 'code',
'issuer' => 'https://...',
'client_auth_method' => 'query',
'uid_field' => '...',
'client_options' => {
...
'redirect_uri' => 'https://.../users/auth/openid_connect_2fa/callback'
}
}
}
Pour les installations compilées manuellement :
- { name: 'openid_connect', # do not change this parameter
label: 'Provider name', # optional label for login button, defaults to "Openid Connect"
icon: '<custom_provider_icon>',
args: {
name: 'openid_connect',
scope: ['openid','profile','email'],
response_type: 'code',
issuer: '<your_oidc_url>',
discovery: true,
client_auth_method: 'query',
uid_field: '<uid_field>',
send_scope_to_token_endpoint: false,
pkce: true,
client_options: {
identifier: '<your_oidc_client_id>',
secret: '<your_oidc_client_secret>',
redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback'
}
}
}
[!note] Pour plus d'informations sur chaque option de configuration, reportez-vous à la documentation d'utilisation d'OmniAuth OpenID Connect et à la spécification OpenID Connect Core 1.0.
Pour la configuration du fournisseur, modifiez les valeurs du fournisseur pour les adapter à votre configuration client OpenID Connect. Utilisez les éléments suivants comme guide :
<your_oidc_label> est le label qui apparaît sur la page de connexion.<custom_provider_icon> (facultatif) est l'icône qui apparaît sur la page de connexion. Les icônes des principales plateformes de connexion sociale sont intégrées dans GitLab, mais vous pouvez remplacer ces icônes en spécifiant ce paramètre. GitLab accepte les chemins locaux et les URL absolues. GitLab inclut des icônes pour la plupart des principales plateformes de connexion sociale, mais vous pouvez remplacer ces icônes en spécifiant une URL externe ou un chemin absolu ou relatif vers votre propre fichier d'icône.
icon: <path>/<to>/<your-icon>.
/opt/gitlab/embedded/service/gitlab-rails/public/<path>/<to>/<your-icon>.https://gitlab.example/<path>/<to>/<your-icon>.icon: <your-icon>.
/opt/gitlab/embedded/service/gitlab-rails/public/images/<your-icon>.https://gitlab.example.com/images/<your-icon>.<your_oidc_url> (facultatif) est l'URL qui pointe vers le fournisseur OpenID Connect (par exemple, https://example.com/auth/realms/your-realm). Si cette valeur n'est pas fournie, l'URL est construite à partir de client_options dans le format suivant : <client_options.scheme>://<client_options.host>:<client_options.port>.discovery est défini sur true, le fournisseur OpenID Connect tente de découvrir automatiquement les options client en utilisant <your_oidc_url>/.well-known/openid-configuration. La valeur par défaut est false.client_auth_method (facultatif) spécifie la méthode utilisée pour authentifier le client auprès du fournisseur OpenID Connect.
basic - Authentification HTTP de base.jwt_bearer - Authentification basée sur JWT (signature par clé privée et secret client).mtls - Validation par TLS mutuel ou certificat X.509.basic.<uid_field> (facultatif) est le nom de champ issu de user_info.raw_attributes qui définit la valeur de uid (par exemple, preferred_username). Si vous ne fournissez pas cette valeur, ou si le champ avec la valeur configurée est manquant dans les détails de user_info.raw_attributes, uid utilise le champ sub.send_scope_to_token_endpoint est true par défaut, donc le paramètre scope est généralement inclus dans les requêtes adressées au point de terminaison du jeton. Cependant, si votre fournisseur OpenID Connect n'accepte pas le paramètre scope dans ces requêtes, définissez cette valeur sur false.pkce (facultatif) : Activer Proof Key for Code Exchange.client_options sont les options spécifiques au client OpenID Connect. En particulier :
identifier est l'identifiant client tel que configuré dans le fournisseur de services OpenID Connect.secret est le secret client tel que configuré dans le fournisseur de services OpenID Connect. Par exemple, OmniAuth OpenID Connect l'exige. Si le fournisseur de services ne nécessite pas de secret, fournissez n'importe quelle valeur, elle sera ignorée.redirect_uri est l'URL GitLab vers laquelle rediriger l'utilisateur après une connexion réussie (par exemple, http://example.com/users/auth/openid_connect/callback).client_options suivantes sont facultatives, sauf si la découverte automatique est désactivée ou échoue :
authorization_endpoint est l'URL du point de terminaison qui autorise l'utilisateur final.token_endpoint est l'URL du point de terminaison qui fournit le jeton d'accès.userinfo_endpoint est l'URL du point de terminaison qui fournit les informations de l'utilisateur.jwks_uri est l'URL du point de terminaison où le signataire de jeton publie ses clés.Enregistrez le fichier de configuration.
Pour que les modifications prennent effet, si vous :
Sur la page de connexion, une option OpenID Connect est disponible sous le formulaire de connexion habituel. Sélectionnez cette option pour commencer le processus d'authentification. Le fournisseur OpenID Connect vous demande de vous connecter et d'autoriser l'application GitLab si une confirmation est requise par le client. Vous êtes redirigé vers GitLab et connecté.
Les configurations suivantes illustrent comment configurer OpenID avec différents fournisseurs lors de l'utilisation de l'installation de package Linux.
Consultez la documentation Google pour plus de détails :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect", # do not change this parameter
label: "Google OpenID", # optional label for login button, defaults to "Openid Connect"
args: {
name: "openid_connect",
scope: ["openid", "profile", "email"],
response_type: "code",
issuer: "https://accounts.google.com",
client_auth_method: "query",
discovery: true,
uid_field: "preferred_username",
pkce: true,
client_options: {
identifier: "<YOUR PROJECT CLIENT ID>",
secret: "<YOUR PROJECT CLIENT SECRET>",
redirect_uri: "https://example.com/users/auth/openid_connect/callback",
}
}
}
]
Le protocole OpenID Connect (OIDC) pour Microsoft Azure utilise les points de terminaison de la plateforme d'identité Microsoft (v2). Pour commencer, connectez-vous au portail Azure. Pour votre application, vous avez besoin des informations suivantes :
Lorsque vous enregistrez une application Microsoft Azure, vous devez accorder des autorisations d'API pour permettre à GitLab de récupérer les informations requises. Vous devez fournir au minimum les autorisations openid, profile et email. Pour plus d'informations, consultez la documentation Microsoft sur la configuration des autorisations d'application pour une API web.
[!note] Tous les comptes provisionnés par Azure doivent avoir une adresse e-mail définie. Si une adresse e-mail n'est pas définie, Azure attribue une adresse générée aléatoirement. Si vous avez configuré des restrictions de domaine pour les nouveaux utilisateurs, cette adresse aléatoire pourrait empêcher la création du compte.
Exemple de bloc de configuration pour les installations de packages Linux :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect", # do not change this parameter
label: "Azure OIDC", # optional label for login button, defaults to "Openid Connect"
args: {
name: "openid_connect",
scope: ["openid", "profile", "email"],
response_type: "code",
issuer: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0",
client_auth_method: "query",
discovery: true,
uid_field: "preferred_username",
pkce: true,
client_options: {
identifier: "<YOUR APP CLIENT ID>",
secret: "<YOUR APP CLIENT SECRET>",
redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
}
}
}
]
Microsoft a documenté le fonctionnement de sa plateforme avec le protocole OIDC.
Si votre application possède des clés de signature personnalisées parce que vous utilisez la fonctionnalité de mappage des revendications SAML, vous devez configurer le fournisseur OpenID de la manière suivante :
args.discovery ou en le définissant sur false.client_options, spécifiez les éléments suivants :
jwks_uri avec le paramètre de requête appid : https://login.microsoftonline.com/<YOUR-TENANT-ID>/discovery/v2.0/keys?appid=<YOUR APP CLIENT ID>.end_session_endpoint.authorization_endpoint.userinfo_endpoint.Exemple de configuration pour les installations de packages Linux :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect", # do not change this parameter
label: "Azure OIDC", # optional label for login button, defaults to "Openid Connect"
args: {
name: "openid_connect",
scope: ["openid", "profile", "email"],
response_type: "code",
issuer: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0",
client_auth_method: "basic",
discovery: false,
uid_field: "preferred_username",
pkce: true,
client_options: {
identifier: "<YOUR APP CLIENT ID>",
secret: "<YOUR APP CLIENT SECRET>",
redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback",
end_session_endpoint: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/oauth2/v2.0/logout",
authorization_endpoint: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/oauth2/v2.0/authorize",
token_endpoint: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/oauth2/v2.0/token",
userinfo_endpoint: "https://graph.microsoft.com/oidc/userinfo",
jwks_uri: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/discovery/v2.0/keys?appid=<YOUR APP CLIENT ID>"
}
}
}
]
Si vous voyez des échecs d'authentification avec un message KidNotFound, c'est probablement en raison d'un paramètre de requête appid manquant ou incorrect. GitLab génère cette erreur si le jeton d'identité renvoyé par Microsoft ne peut pas être validé avec les clés fournies par le point de terminaison jwks_uri.
Pour plus d'informations, consultez la documentation Microsoft Entra sur la validation des jetons.
Vous pouvez migrer vers la configuration générique OpenID Connect depuis azure_activedirectory_v2 et azure_oauth2.
Tout d'abord, définissez le uid_field. Le uid_field et la revendication sub que vous pouvez sélectionner comme uid_field varient selon le fournisseur. La connexion sans définir le uid_field entraîne la création d'identités supplémentaires dans GitLab qui doivent être modifiées manuellement :
| Fournisseur | uid_field | Informations complémentaires |
|---|---|---|
omniauth-azure-oauth2 | sub | Les attributs supplémentaires oid et tid sont proposés dans l'objet info. |
omniauth-azure-activedirectory-v2 | oid | Vous devez configurer oid comme uid_field lors de la migration. |
omniauth_openid_connect | sub | Spécifiez uid_field pour utiliser un autre champ. |
Pour migrer vers la configuration générique OpenID Connect, vous devez mettre à jour la configuration.
Pour les installations de packages Linux, mettez à jour la configuration comme suit :
{{< tabs >}}
{{< tab title="Azure OAuth 2.0" >}}
gitlab_rails['omniauth_providers'] = [
{
name: "azure_oauth2",
label: "Azure OIDC", # optional label for login button, defaults to "Openid Connect"
args: {
name: "azure_oauth2", # this matches the existing azure_oauth2 provider name, and only the strategy_class immediately below configures OpenID Connect
strategy_class: "OmniAuth::Strategies::OpenIDConnect",
scope: ["openid", "profile", "email"],
response_type: "code",
issuer: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0",
client_auth_method: "query",
discovery: true,
uid_field: "sub",
send_scope_to_token_endpoint: "false",
client_options: {
identifier: "<YOUR APP CLIENT ID>",
secret: "<YOUR APP CLIENT SECRET>",
redirect_uri: "https://gitlab.example.com/users/auth/azure_oauth2/callback"
}
}
}
]
{{< /tab >}}
{{< tab title="Azure Active Directory v2" >}}
gitlab_rails['omniauth_providers'] = [
{
name: "azure_activedirectory_v2",
label: "Azure OIDC", # optional label for login button, defaults to "Openid Connect"
args: {
name: "azure_activedirectory_v2",
strategy_class: "OmniAuth::Strategies::OpenIDConnect",
scope: ["openid", "profile", "email"],
response_type: "code",
issuer: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0",
client_auth_method: "query",
discovery: true,
uid_field: "oid",
send_scope_to_token_endpoint: "false",
client_options: {
identifier: "<YOUR APP CLIENT ID>",
secret: "<YOUR APP CLIENT SECRET>",
redirect_uri: "https://gitlab.example.com/users/auth/azure_activedirectory_v2/callback"
}
}
}
]
{{< /tab >}}
{{< /tabs >}}
Pour les installations Helm :
Ajoutez la configuration du fournisseur dans un fichier YAML (par exemple, provider.yaml) :
{{< tabs >}}
{{< tab title="Azure OAuth 2.0" >}}
{
"name": "azure_oauth2",
"args": {
"name": "azure_oauth2",
"strategy_class": "OmniAuth::Strategies::OpenIDConnect",
"scope": [
"openid",
"profile",
"email"
],
"response_type": "code",
"issuer": "https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0",
"client_auth_method": "query",
"discovery": true,
"uid_field": "sub",
"send_scope_to_token_endpoint": false,
"client_options": {
"identifier": "<YOUR APP CLIENT ID>",
"secret": "<YOUR APP CLIENT SECRET>",
"redirect_uri": "https://gitlab.example.com/users/auth/azure_oauth2/callback"
}
}
}
{{< /tab >}}
{{< tab title="Azure Active Directory v2" >}}
{
"name": "azure_activedirectory_v2",
"args": {
"name": "azure_activedirectory_v2",
"strategy_class": "OmniAuth::Strategies::OpenIDConnect",
"scope": [
"openid",
"profile",
"email"
],
"response_type": "code",
"issuer": "https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0",
"client_auth_method": "query",
"discovery": true,
"uid_field": "sub",
"send_scope_to_token_endpoint": false,
"client_options": {
"identifier": "<YOUR APP CLIENT ID>",
"secret": "<YOUR APP CLIENT SECRET>",
"redirect_uri": "https://gitlab.example.com/users/auth/activedirectory_v2/callback"
}
}
}
{{< /tab >}}
{{< /tabs >}}
Lors de la migration de azure_oauth2 vers omniauth_openid_connect dans le cadre d'une mise à niveau vers GitLab 17.0 ou une version ultérieure, la valeur de la revendication sub définie pour votre organisation peut varier. azure_oauth2 utilise le point de terminaison Microsoft V1, tandis que azure_activedirectory_v2 et omniauth_openid_connect utilisent tous deux le point de terminaison Microsoft V2 avec une valeur sub commune.
omniauth_auto_link_user.autoLinkUser.azure_oauth2 existant afin que l'utilisateur puisse se connecter via OAuth 2.0 et lier son identité OpenID Connect (de manière similaire à la méthode précédente). Cette méthode fonctionnerait également pour les utilisateurs ayant des adresses e-mail, à condition que auto_link_user soit activé.extern_uid manuellement. Pour ce faire, utilisez l'API ou la console Rails pour mettre à jour le extern_uid pour chaque utilisateur. Cette méthode peut être nécessaire si l'instance a déjà été mise à niveau vers la version 17.0 ou ultérieure et que les utilisateurs ont tenté de se connecter.[!note]
azure_oauth2peut avoir utilisé la revendicationupnd'Entra ID comme adresse e-mail, si la revendication
GitLab nécessite une configuration spéciale pour fonctionner avec Azure Active Directory B2C. Pour commencer, connectez-vous au portail Azure. Pour votre application, vous avez besoin des informations suivantes provenant d'Azure :
Configurez l'application :
Définissez l'Redirect URI de l'application. Par exemple, si votre domaine GitLab est gitlab.example.com, définissez l'Redirect URI de l'application sur https://gitlab.example.com/users/auth/openid_connect/callback.
Ajoutez les autorisations d'API suivantes à l'application :
openidoffline_accessAzure B2C propose deux façons de définir la logique métier pour la connexion d'un utilisateur :
Les stratégies personnalisées sont requises car les flux utilisateurs Azure B2C standard n'envoient pas la revendication OpenID email dont GitLab a besoin pour créer ou lier des utilisateurs. Par conséquent, les flux utilisateurs standard ne fonctionnent pas avec les paramètres allow_single_sign_on ou auto_link_user. Avec une stratégie Azure B2C standard, GitLab ne peut pas créer de nouveau compte ni établir un lien avec un compte existant via une adresse e-mail.
Pour plus d'informations sur la façon dont Azure AD B2C émet des jetons et des revendications dans les flux utilisateurs et les stratégies personnalisées, consultez la documentation Microsoft sur les flux utilisateurs et les stratégies personnalisées et la configuration du schéma de revendications.
Tout d'abord, créez une stratégie personnalisée.
Les instructions Microsoft utilisent SocialAndLocalAccounts dans le pack de démarrage de stratégie personnalisée, mais LocalAccounts s'authentifie auprès des comptes Active Directory locaux. Avant de charger les stratégies, effectuez les opérations suivantes :
Pour exporter la revendication email, modifiez le fichier SignUpOrSignin.xml. Remplacez la ligne suivante :
<OutputClaim ClaimTypeReferenceId="email" />
par :
<OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email" />
Pour que la découverte OIDC fonctionne avec B2C, configurez la stratégie avec un émetteur compatible avec la spécification OIDC. Consultez les paramètres de compatibilité des jetons. Dans TrustFrameworkBase.xml sous JwtIssuer, définissez IssuanceClaimPattern sur AuthorityWithTfp :
<ClaimsProvider>
<DisplayName>Token Issuer</DisplayName>
<TechnicalProfiles>
<TechnicalProfile Id="JwtIssuer">
<DisplayName>JWT Issuer</DisplayName>
<Protocol Name="None" />
<OutputTokenFormat>JWT</OutputTokenFormat>
<Metadata>
<Item Key="IssuanceClaimPattern">AuthorityWithTfp</Item>
...
Chargez la stratégie. Écrasez les fichiers existants si vous mettez à jour une stratégie existante.
Pour déterminer l'URL de l'émetteur, utilisez la stratégie de connexion. L'URL de l'émetteur est de la forme :
https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/
Le nom de la stratégie est en minuscules dans l'URL. Par exemple, la stratégie B2C_1A_signup_signin apparaît sous la forme b2c_1a_signup_sigin.
Veillez à inclure la barre oblique finale.
Vérifiez le fonctionnement de l'URL de découverte OIDC et de l'URL de l'émetteur, puis ajoutez .well-known/openid-configuration à l'URL de l'émetteur :
https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/.well-known/openid-configuration
Par exemple, si domain est example.b2clogin.com et que l'identifiant de locataire est fc40c736-476c-4da1-b489-ee48cee84386, vous pouvez utiliser curl et jq pour extraire l'émetteur :
$ curl --silent "https://example.b2clogin.com/tfp/fc40c736-476c-4da1-b489-ee48cee84386/b2c_1a_signup_signin/v2.0/.well-known/openid-configuration" | jq .issuer
"https://example.b2clogin.com/tfp/fc40c736-476c-4da1-b489-ee48cee84386/b2c_1a_signup_signin/v2.0/"
Configurez l'URL de l'émetteur avec la stratégie personnalisée utilisée pour signup_signin. Par exemple, voici la configuration avec une stratégie personnalisée pour b2c_1a_signup_signin pour les installations de packages Linux :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect", # do not change this parameter
label: "Azure B2C OIDC", # optional label for login button, defaults to "Openid Connect"
args: {
name: "openid_connect",
scope: ["openid"],
response_mode: "query",
response_type: "id_token",
issuer: "https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/b2c_1a_signup_signin/v2.0/",
client_auth_method: "query",
discovery: true,
send_scope_to_token_endpoint: true,
pkce: true,
client_options: {
identifier: "<YOUR APP CLIENT ID>",
secret: "<YOUR APP CLIENT SECRET>",
redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
}
}
}]
Assurez-vous que toutes les occurrences de yourtenant.onmicrosoft.com, ProxyIdentityExperienceFrameworkAppId et IdentityExperienceFrameworkAppId correspondent au nom d'hôte de votre locataire B2C et aux identifiants client respectifs dans les fichiers de stratégie XML.
Ajoutez https://jwt.ms comme URI de redirection à l'application et utilisez le testeur de stratégie personnalisée. Vérifiez que le payload inclut email correspondant à l'accès e-mail de l'utilisateur.
Après avoir activé la stratégie personnalisée, les utilisateurs pourraient voir Invalid username or password après avoir tenté de se connecter. Cela peut être un problème de configuration avec l'application IdentityExperienceFramework. Consultez ce commentaire Microsoft qui suggère de vérifier que le manifeste de l'application contient ces paramètres :
"accessTokenAcceptedVersion": null"signInAudience": "AzureADMyOrg"Cette configuration correspond au paramètre Supported account types utilisé lors de la création de l'application IdentityExperienceFramework.
GitLab fonctionne avec les fournisseurs OpenID qui utilisent HTTPS. Bien que vous puissiez configurer un serveur Keycloak qui utilise HTTP, GitLab ne peut communiquer qu'avec un serveur Keycloak qui utilise HTTPS.
Configurez Keycloak pour utiliser des algorithmes à clé publique pour signer les jetons. Par exemple, utilisez RSA256 ou RSA512 au lieu de HS256 ou HS358. Les algorithmes de chiffrement à clé publique sont :
Exemple de bloc de configuration pour les installations de packages Linux :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect", # do not change this parameter
label: "Keycloak", # optional label for login button, defaults to "Openid Connect"
args: {
name: "openid_connect",
scope: ["openid", "profile", "email"],
response_type: "code",
issuer: "https://keycloak.example.com/realms/myrealm",
client_auth_method: "query",
discovery: true,
uid_field: "preferred_username",
pkce: true,
client_options: {
identifier: "<YOUR CLIENT ID>",
secret: "<YOUR CLIENT SECRET>",
redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
}
}
}
]
[!warning] Les instructions suivantes sont incluses par souci d'exhaustivité, mais n'utilisez le chiffrement à clé symétrique que si cela est absolument nécessaire.
Pour utiliser le chiffrement à clé symétrique :
Extrayez la clé secrète de la base de données Keycloak. Keycloak n'expose pas cette valeur dans l'interface web. Le secret client visible dans l'interface web est le secret client OAuth 2.0, qui est différent du secret utilisé pour signer les JSON Web Tokens.
Par exemple, si vous utilisez PostgreSQL comme base de données backend pour Keycloak :
Connectez-vous à la console de base de données.
Exécutez la requête SQL suivante pour extraire la clé :
$ psql -U keycloak
psql (13.3 (Debian 13.3-1.pgdg100+1))
Type "help" for help.
keycloak=# SELECT c.name, value FROM component_config CC INNER JOIN component C ON(CC.component_id = C.id) WHERE C.realm_id = 'master' and provider_id = 'hmac-generated' AND CC.name = 'secret';
-[ RECORD 1 ]---------------------------------------------------------------------------------
name | hmac-generated
value | lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62-sqGc8drp3XW-wr93zru8PFsQokHZZuJJbaUXvmiOftCZM3C4KW3-g
-[ RECORD 2 ]---------------------------------------------------------------------------------
name | fallback-HS384
value | UfVqmIs--U61UYsRH-NYBH3_mlluLONpg_zN7CXEwkJcO9xdRNlzZfmfDLPtf2xSTMvqu08R2VhLr-8G-oZ47A
Dans cet exemple, il y a deux clés privées : une pour HS256 (hmac-generated) et une autre pour HS384 (fallback-HS384). Nous utilisons la première value pour configurer GitLab.
Convertissez value en base64 standard. Comme indiqué dans le post « Invalid signature with HS256 token », value est encodé dans la section « Base 64 Encoding with URL and Filename Safe Alphabet » de la RFC 4648. Cela doit être converti en base64 standard tel que défini dans la RFC 2045. Le script Ruby suivant effectue cette opération :
require 'base64'
value = "lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62-sqGc8drp3XW-wr93zru8PFsQokHZZuJJbaUXvmiOftCZM3C4KW3-g"
Base64.encode64(Base64.urlsafe_decode64(value))
Cela donne la valeur suivante :
lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62+sqGc8drp3XW+wr93zru8PFsQokH\nZZuJJbaUXvmiOftCZM3C4KW3+g==\n
Spécifiez ce secret encodé en base64 dans jwt_secret_base64. Par exemple :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect", # do not change this parameter
label: "Keycloak", # optional label for login button, defaults to "Openid Connect"
args: {
name: "openid_connect",
scope: ["openid", "profile", "email"],
response_type: "code",
issuer: "https://keycloak.example.com/auth/realms/myrealm",
client_auth_method: "query",
discovery: true,
uid_field: "preferred_username",
jwt_secret_base64: "<YOUR BASE64-ENCODED SECRET>",
pkce: true,
client_options: {
identifier: "<YOUR CLIENT ID>",
secret: "<YOUR CLIENT SECRET>",
redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
}
}
}
]
Si vous voyez une erreur JSON::JWS::VerificationFailed, vous avez spécifié un secret incorrect.
GitLab fonctionne avec les fournisseurs OpenID qui utilisent HTTPS. Utilisez HTTPS pour vous connecter à GitLab via OpenID avec Casdoor.
Pour votre application, effectuez les étapes suivantes sur Casdoor :
gitlab.example.com, assurez-vous que l'application Casdoor possède le Redirect URI suivant : https://gitlab.example.com/users/auth/openid_connect/callback.Consultez la documentation Casdoor pour plus de détails.
Exemple de configuration pour les installations de packages Linux (chemin du fichier : /etc/gitlab/gitlab.rb) :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect", # do not change this parameter
label: "Casdoor", # optional label for login button, defaults to "Openid Connect"
args: {
name: "openid_connect",
scope: ["openid", "profile", "email"],
response_type: "code",
issuer: "https://<CASDOOR_HOSTNAME>",
client_auth_method: "query",
discovery: true,
uid_field: "sub",
client_options: {
identifier: "<YOUR CLIENT ID>",
secret: "<YOUR CLIENT SECRET>",
redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
}
}
}
]
Exemple de configuration pour les installations compilées manuellement (chemin du fichier : config/gitlab.yml) :
- { name: 'openid_connect', # do not change this parameter
label: 'Casdoor', # optional label for login button, defaults to "Openid Connect"
args: {
name: 'openid_connect',
scope: ['openid', 'profile', 'email'],
response_type: 'code',
issuer: 'https://<CASDOOR_HOSTNAME>',
discovery: true,
client_auth_method: 'query',
uid_field: 'sub',
client_options: {
identifier: '<YOUR CLIENT ID>',
secret: '<YOUR CLIENT SECRET>',
redirect_uri: 'https://gitlab.example.com/users/auth/openid_connect/callback'
}
}
}
Vous pouvez configurer votre application pour utiliser plusieurs fournisseurs OpenID Connect (OIDC). Pour ce faire, définissez explicitement le strategy_class dans votre fichier de configuration.
Vous devriez procéder ainsi dans l'un ou l'autre des scénarios suivants :
Les exemples de configurations suivants montrent comment proposer différents niveaux d'authentification, une option avec authentification à deux facteurs (2FA) et une sans 2FA.
Pour les installations de packages Linux :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect",
label: "Provider name", # optional label for login button, defaults to "Openid Connect"
icon: "<custom_provider_icon>",
args: {
name: "openid_connect",
strategy_class: "OmniAuth::Strategies::OpenIDConnect",
scope: ["openid","profile","email"],
response_type: "code",
issuer: "<your_oidc_url>",
discovery: true,
client_auth_method: "query",
uid_field: "<uid_field>",
send_scope_to_token_endpoint: "false",
pkce: true,
client_options: {
identifier: "<your_oidc_client_id>",
secret: "<your_oidc_client_secret>",
redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback"
}
}
},
{
name: "openid_connect_2fa",
label: "Provider name 2FA", # optional label for login button, defaults to "Openid Connect"
icon: "<custom_provider_icon>",
args: {
name: "openid_connect_2fa",
strategy_class: "OmniAuth::Strategies::OpenIDConnect",
scope: ["openid","profile","email"],
response_type: "code",
issuer: "<your_oidc_url>",
discovery: true,
client_auth_method: "query",
uid_field: "<uid_field>",
send_scope_to_token_endpoint: "false",
pkce: true,
client_options: {
identifier: "<your_oidc_client_id>",
secret: "<your_oidc_client_secret>",
redirect_uri: "<your_gitlab_url>/users/auth/openid_connect_2fa/callback"
}
}
}
]
Pour les installations compilées manuellement :
- { name: 'openid_connect',
label: 'Provider name', # optional label for login button, defaults to "Openid Connect"
icon: '<custom_provider_icon>',
args: {
name: 'openid_connect',
strategy_class: "OmniAuth::Strategies::OpenIDConnect",
scope: ['openid', 'profile', 'email'],
response_type: 'code',
issuer: '<your_oidc_url>',
discovery: true,
client_auth_method: 'query',
uid_field: '<uid_field>',
send_scope_to_token_endpoint: false,
pkce: true,
client_options: {
identifier: '<your_oidc_client_id>',
secret: '<your_oidc_client_secret>',
redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback'
}
}
}
- { name: 'openid_connect_2fa',
label: 'Provider name 2FA', # optional label for login button, defaults to "Openid Connect"
icon: '<custom_provider_icon>',
args: {
name: 'openid_connect_2fa',
strategy_class: "OmniAuth::Strategies::OpenIDConnect",
scope: ['openid', 'profile', 'email'],
response_type: 'code',
issuer: '<your_oidc_url>',
discovery: true,
client_auth_method: 'query',
uid_field: '<uid_field>',
send_scope_to_token_endpoint: false,
pkce: true,
client_options: {
identifier: '<your_oidc_client_id>',
secret: '<your_oidc_client_secret>',
redirect_uri: '<your_gitlab_url>/users/auth/openid_connect_2fa/callback'
}
}
}
Dans ce cas d'utilisation, vous pourriez vouloir synchroniser le extern_uid entre les différents fournisseurs en vous basant sur un identifiant connu existant dans votre annuaire d'entreprise.
Pour ce faire, définissez le uid_field. L'exemple de code suivant montre comment procéder :
def sync_missing_provider(self, user: User, extern_uid: str)
existing_identities = []
for identity in user.identities:
existing_identities.append(identity.get("provider"))
local_extern_uid = extern_uid.lower()
for provider in ("openid_connect_2fa", "openid_connect"):
identity = [
identity
for identity in user.identities
if identity.get("provider") == provider
and identity.get("extern_uid").lower() != local_extern_uid
]
if provider not in existing_identities or identity:
if identity and identity[0].get("extern_uid") != "":
logger.error(f"Found different identity for provider {provider} for user {user.id}")
continue
else:
logger.info(f"Add identity 'provider': {provider}, 'extern_uid': {extern_uid} for user {user.id}")
user.provider = provider
user.extern_uid = extern_uid
user = self.save_user(user)
return user
Pour plus d'informations, consultez la documentation de la méthode utilisateur de l'API GitLab.
{{< details >}}
{{< /details >}}
Vous pouvez configurer l'appartenance aux groupes OIDC pour :
GitLab vérifie ces groupes à chaque connexion et met à jour les attributs utilisateur si nécessaire. Cette fonctionnalité ne vous permet pas d'ajouter automatiquement des utilisateurs aux groupes GitLab.
La valeur définie pour un groupe spécifique doit refléter la valeur renvoyée par le fournisseur d'identité. Par exemple, Microsoft Entra OIDC renvoie un GroupID, donc la configuration required_groups ressemblerait à required_groups: ["55db8574-c392-4e8b-892d-1e086394be9c"].
Votre fournisseur d'identité (IdP) doit transmettre les informations de groupe à GitLab dans la réponse OIDC. Pour utiliser cette réponse afin d'exiger que les utilisateurs soient membres d'un certain groupe, configurez GitLab pour identifier :
groups_attribute.required_groups.Si vous ne définissez pas required_groups ou laissez le paramètre vide, tout utilisateur authentifié par l'IdP via OIDC peut utiliser GitLab.
{{< tabs >}}
{{< tab title="Linux package (Omnibus)" >}}
Modifiez /etc/gitlab/gitlab.rb :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect",
label: "Provider name",
args: {
name: "openid_connect",
scope: ["openid","profile","email"],
response_type: "code",
issuer: "<your_oidc_url>",
discovery: true,
client_auth_method: "query",
uid_field: "<uid_field>",
client_options: {
identifier: "<your_oidc_client_id>",
secret: "<your_oidc_client_secret>",
redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback",
gitlab: {
groups_attribute: "groups",
required_groups: ["Developer"]
}
}
}
}
]
Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.
{{< /tab >}}
{{< tab title="Self-compiled (source)" >}}
Modifiez /home/git/gitlab/config/gitlab.yml :
production: &base
omniauth:
providers:
- { name: 'openid_connect',
label: 'Provider name',
args: {
name: 'openid_connect',
scope: ['openid','profile','email'],
response_type: 'code',
issuer: '<your_oidc_url>',
discovery: true,
client_auth_method: 'query',
uid_field: '<uid_field>',
client_options: {
identifier: '<your_oidc_client_id>',
secret: '<your_oidc_client_secret>',
redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback',
gitlab: {
groups_attribute: "groups",
required_groups: ["Developer"]
}
}
}
}
Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.
{{< /tab >}}
{{< /tabs >}}
Votre IdP doit transmettre les informations de groupe à GitLab dans la réponse OIDC. Pour utiliser cette réponse afin d'identifier les utilisateurs comme des utilisateurs externes en fonction de l'appartenance au groupe, configurez GitLab pour identifier :
groups_attribute.external_groups.{{< tabs >}}
{{< tab title="Linux package (Omnibus)" >}}
Modifiez /etc/gitlab/gitlab.rb :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect",
label: "Provider name",
args: {
name: "openid_connect",
scope: ["openid","profile","email"],
response_type: "code",
issuer: "<your_oidc_url>",
discovery: true,
client_auth_method: "query",
uid_field: "<uid_field>",
client_options: {
identifier: "<your_oidc_client_id>",
secret: "<your_oidc_client_secret>",
redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback",
gitlab: {
groups_attribute: "groups",
external_groups: ["Freelancer"]
}
}
}
}
]
Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.
{{< /tab >}}
{{< tab title="Self-compiled (source)" >}}
Modifiez /home/git/gitlab/config/gitlab.yml :
production: &base
omniauth:
providers:
- { name: 'openid_connect',
label: 'Provider name',
args: {
name: 'openid_connect',
scope: ['openid','profile','email'],
response_type: 'code',
issuer: '<your_oidc_url>',
discovery: true,
client_auth_method: 'query',
uid_field: '<uid_field>',
client_options: {
identifier: '<your_oidc_client_id>',
secret: '<your_oidc_client_secret>',
redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback',
gitlab: {
groups_attribute: "groups",
external_groups: ["Freelancer"]
}
}
}
}
Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.
{{< /tab >}}
{{< /tabs >}}
{{< details >}}
{{< /details >}}
Votre IdP doit transmettre les informations de groupe à GitLab dans la réponse OIDC. Pour utiliser cette réponse afin d'affecter des utilisateurs en tant qu'auditeurs en fonction de l'appartenance au groupe, configurez GitLab pour identifier :
groups_attribute.auditor_groups.{{< tabs >}}
{{< tab title="Linux package (Omnibus)" >}}
Modifiez /etc/gitlab/gitlab.rb :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect",
label: "Provider name",
args: {
name: "openid_connect",
scope: ["openid","profile","email","groups"],
response_type: "code",
issuer: "<your_oidc_url>",
discovery: true,
client_auth_method: "query",
uid_field: "<uid_field>",
client_options: {
identifier: "<your_oidc_client_id>",
secret: "<your_oidc_client_secret>",
redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback",
gitlab: {
groups_attribute: "groups",
auditor_groups: ["Auditor"]
}
}
}
}
]
Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.
{{< /tab >}}
{{< tab title="Self-compiled (source)" >}}
Modifiez /home/git/gitlab/config/gitlab.yml :
production: &base
omniauth:
providers:
- { name: 'openid_connect',
label: 'Provider name',
args: {
name: 'openid_connect',
scope: ['openid','profile','email','groups'],
response_type: 'code',
issuer: '<your_oidc_url>',
discovery: true,
client_auth_method: 'query',
uid_field: '<uid_field>',
client_options: {
identifier: '<your_oidc_client_id>',
secret: '<your_oidc_client_secret>',
redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback',
gitlab: {
groups_attribute: "groups",
auditor_groups: ["Auditor"]
}
}
}
}
Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.
{{< /tab >}}
{{< /tabs >}}
Votre IdP doit transmettre les informations de groupe à GitLab dans la réponse OIDC. Pour utiliser cette réponse afin d'affecter des utilisateurs en tant qu'administrateurs en fonction de l'appartenance au groupe, configurez GitLab pour identifier :
groups_attribute.admin_groups.{{< tabs >}}
{{< tab title="Linux package (Omnibus)" >}}
Modifiez /etc/gitlab/gitlab.rb :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect",
label: "Provider name",
args: {
name: "openid_connect",
scope: ["openid","profile","email"],
response_type: "code",
issuer: "<your_oidc_url>",
discovery: true,
client_auth_method: "query",
uid_field: "<uid_field>",
client_options: {
identifier: "<your_oidc_client_id>",
secret: "<your_oidc_client_secret>",
redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback",
gitlab: {
groups_attribute: "groups",
admin_groups: ["Admin"]
}
}
}
}
]
Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.
{{< /tab >}}
{{< tab title="Self-compiled (source)" >}}
Modifiez /home/git/gitlab/config/gitlab.yml :
production: &base
omniauth:
providers:
- { name: 'openid_connect',
label: 'Provider name',
args: {
name: 'openid_connect',
scope: ['openid','profile','email'],
response_type: 'code',
issuer: '<your_oidc_url>',
discovery: true,
client_auth_method: 'query',
uid_field: '<uid_field>',
client_options: {
identifier: '<your_oidc_client_id>',
secret: '<your_oidc_client_secret>',
redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback',
gitlab: {
groups_attribute: "groups",
admin_groups: ["Admin"]
}
}
}
}
Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.
{{< /tab >}}
{{< /tabs >}}
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
Par défaut, les jetons d'identifiant GitLab expirent après 120 secondes.
Pour configurer une durée personnalisée pour vos jetons d'identifiant :
{{< tabs >}}
{{< tab title="Linux package (Omnibus)" >}}
Modifiez /etc/gitlab/gitlab.rb :
gitlab_rails['oidc_provider_openid_id_token_expire_in_seconds'] = 3600
Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.
{{< /tab >}}
{{< tab title="Self-compiled (source)" >}}
Modifiez /home/git/gitlab/config/gitlab.yml :
production: &base
oidc_provider:
openid_id_token_expire_in_seconds: 3600
Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.
{{< /tab >}}
{{< /tabs >}}
{{< details >}}
{{< /details >}}
[!flag] La disponibilité de cette fonctionnalité est contrôlée par un feature flag. Pour plus d'informations, consultez l'historique. Cette fonctionnalité est disponible pour les tests, mais n'est pas prête pour une utilisation en production.
Dans certains cas, les méthodes d'authentification par défaut ne protègent pas les ressources critiques ou les actions à haut risque. L'authentification step-up ajoute une couche supplémentaire pour les actions privilégiées ou les opérations sensibles. Par exemple, l'accès à la zone d'administration.
Avec l'authentification step-up, les utilisateurs doivent effectuer une authentification supplémentaire avec une méthode d'authentification à deux facteurs inscrite avant de pouvoir accéder à certaines fonctionnalités.
La norme OIDC inclut les références de classe de contexte d'authentification (ACR). Le concept ACR aide à configurer et à implémenter l'authentification step-up pour différents scénarios, tels que le mode administrateur.
Cette fonctionnalité est une expérience et est susceptible de changer sans préavis. Cette fonctionnalité n'est pas prête pour une utilisation en production. Si vous souhaitez utiliser cette fonctionnalité, vous devez d'abord la tester en dehors de la production.
{{< history >}}
omniauth_step_up_auth_for_admin_mode. Désactivé par défaut.{{< /history >}} Pour activer l'authentification step-up pour le mode administrateur :
Modifiez votre fichier de configuration GitLab (gitlab.yml ou /etc/gitlab/gitlab.rb) pour activer l'authentification step-up pour un fournisseur OmniAuth spécifique.
production: &base
omniauth:
providers:
- { name: 'openid_connect',
label: 'Provider name',
args: {
name: 'openid_connect',
# ...
allow_authorize_params: ["claims"], # Match this to the parameters defined in `step_up_auth => admin_mode => params`
},
step_up_auth: {
admin_mode: {
# The `id_token` field defines the claims that must be included with the token.
# You can specify claims in one or both of the `required` or `included` fields.
# The token must include matching values for every claim you define in these fields.
id_token: {
# The `required` field defines key-value pairs that must be included with the ID token.
# The values must match exactly what is defined.
# In this example, the 'acr' (Authentication Context Class Reference) claim
# must have the value 'gold' to pass the step-up authentication challenge.
# This ensures a specific level of authentication assurance.
required: {
acr: 'gold'
},
# The `included` field also defines key-value pairs that must be included with the ID token.
# Multiple accepted values can be defined in an array. If an array is not used, the value must match exactly.
# In this example, the 'amr' (Authentication Method References) claim
# must have a value of either 'mfa' or 'fpt' to pass the step-up authentication challenge.
# This is useful for scenarios where the user must provide additional authentication factors.
included: {
amr: ['mfa', 'fpt']
},
},
# The `params` field defines any additional parameters that are sent during the authentication process.
# In this example, the `claims` parameter is added to the authorization request and instructs the
# identity provider to include an 'acr' claim with the value 'gold' in the ID token.
# The 'essential: true' indicates that this claim is required for successful authentication.
params: {
claims: {
id_token: {
acr: {
essential: true,
values: ['gold']
}
}
}
},
# Optional: Provide a custom documentation link for users who fail step-up authentication
# This link is displayed when step-up authentication fails, directing users to
# organization-specific authentication documentation.
documentation_link: 'https://internal.example.com/path/to/documentation'
},
}
}
Enregistrez le fichier de configuration et redémarrez GitLab pour que les modifications prennent effet.
[!note] Bien qu'OIDC soit standardisé, différents fournisseurs d'identité (IdP) peuvent avoir des exigences spécifiques. Le paramètre
paramspermet un hash flexible pour définir les paramètres nécessaires à l'authentification step-up. Ces valeurs peuvent varier en fonction des exigences de chaque IdP.
Keycloak prend en charge l'authentification step-up en définissant des niveaux d'authentification et des flux de connexion de navigateur personnalisés.
Pour exiger l'authentification step-up pour le mode administrateur avec Keycloak :
Configurez Keycloak dans GitLab.
Suivez les étapes de la documentation Keycloak pour créer un flux de connexion de navigateur avec authentification step-up dans Keycloak.
Modifiez votre fichier de configuration GitLab (gitlab.yml ou /etc/gitlab/gitlab.rb) pour activer l'authentification step-up dans la configuration du fournisseur OIDC Keycloak.
Keycloak définit deux niveaux d'authentification différents : silver et gold. L'exemple suivant utilise gold pour représenter le niveau de sécurité accru.
production: &base
omniauth:
providers:
- { name: 'openid_connect',
label: 'Keycloak',
args: {
name: 'openid_connect',
# ...
allow_authorize_params: ["claims"] # Match this to the parameters defined in `step_up_auth => admin_mode => params`
},
step_up_auth: {
admin_mode: {
id_token: {
# In this example, the 'acr' claim must have the value 'gold' that is also defined in the Keycloak documentation.
required: {
acr: 'gold'
}
},
params: {
claims: {
id_token: {
acr: { essential: true, values: ['gold'] }
}
},
},
# Optional: Add a custom documentation link for Keycloak-specific step-up authentication help
documentation_link: 'https://internal.example.com/path/to/documentation'
},
}
}
Enregistrez le fichier de configuration et redémarrez GitLab pour que les modifications prennent effet.
Microsoft Entra ID (anciennement connu sous le nom d'Azure Active Directory) prend en charge l'authentification step-up via le contexte d'authentification par accès conditionnel. Vous devez travailler avec vos administrateurs Microsoft Entra ID pour définir la configuration correcte.
Tenez compte des aspects suivants :
acrs, et non via la revendication de jeton d'identifiant acr utilisée pour d'autres fournisseurs d'identité.c1 à c99, chacun représentant un contexte d'authentification spécifique avec des stratégies d'accès conditionnel.acrs dans le jeton d'identifiant. Pour activer cela, vous devez configurer les revendications facultatives.acrs sous forme de tableau JSON de chaînes. Par exemple : acrs: ["c1", "c2", "c3"].Pour exiger l'authentification step-up pour le mode administrateur avec Microsoft Entra ID :
Configurez Microsoft Entra ID dans GitLab.
Suivez les étapes de la documentation Microsoft Entra ID pour définir les contextes d'authentification par accès conditionnel dans Microsoft Entra ID.
Dans Microsoft Entra ID, définissez la revendication facultative acrs à inclure dans le jeton d'identifiant.
Modifiez votre fichier de configuration GitLab (gitlab.yml ou /etc/gitlab/gitlab.rb) pour activer l'authentification step-up dans la configuration du fournisseur Microsoft Entra ID :
production: &base
omniauth:
providers:
- { name: 'openid_connect',
label: 'Azure OIDC',
args: {
name: 'openid_connect',
# ...
allow_authorize_params: ["claims"] # Match this to the parameters defined in `step_up_auth => admin_mode => params`
},
step_up_auth: {
admin_mode: {
id_token: {
# In this example, the Microsoft Entra ID administrators have defined `c20`
# as the authentication context ID with the desired security level and
# an optional claim `acrs` to be included in the ID token.
# The `included` field declares that the id token claim `acrs` must include the value `c20`.
included: {
acrs: ["c20"],
},
},
params: {
claims: {
id_token: {
acrs: { essential: true, value: 'c20' }
}
},
},
# Optional: Add a custom documentation link for Microsoft Entra ID step-up authentication
documentation_link: 'https://internal.example.com/path/to/documentation'
},
}
}
Enregistrez le fichier de configuration et redémarrez GitLab pour que les modifications prennent effet.
{{< history >}}
omniauth_step_up_auth_for_namespace. Désactivé par défaut.{{< /history >}}
Vous pouvez également ajouter des fournisseurs d'authentification step-up disponibles pour tous les groupes de votre instance. Cela ne force pas les groupes à utiliser l'authentification step-up ; chaque groupe doit encore configurer cette fonctionnalité individuellement.
Pour ajouter un fournisseur d'authentification step-up pour les groupes :
Modifiez votre fichier de configuration GitLab (gitlab.yml ou /etc/gitlab/gitlab.rb) pour activer l'authentification step-up pour un fournisseur OmniAuth spécifique.
production: &base
omniauth:
providers:
- { name: 'openid_connect',
label: 'Provider name',
args: {
name: 'openid_connect',
# ...
allow_authorize_params: ["claims"], # Match this to the parameters defined in `step_up_auth => admin_mode => params`
},
step_up_auth: {
# Unlike step-up authentication configuration for Admin Mode, you use the `namespace`
# object. This is because you're adding step-up authentication to access the entire
# group, not just Admin Mode.
namespace : {
# The `id_token` field defines the claims that must be included with the token.
# You can specify claims in one or both of the `required` or `included` fields.
# The token must include matching values for every claim you define in these fields.
id_token: {
# The `required` field defines key-value pairs that must be included with the ID token.
# The values must match exactly what is defined.
# In this example, the 'acr' (Authentication Context Class Reference) claim
# must have the value 'gold' to pass the step-up authentication challenge.
# This ensures a specific level of authentication assurance.
required: {
acr: 'gold'
},
# The `included` field also defines key-value pairs that must be included with the ID token.
# Multiple accepted values can be defined in an array. If an array is not used, the value must match exactly.
# In this example, the 'amr' (Authentication Method References) claim
# must have a value of either 'mfa' or 'fpt' to pass the step-up authentication challenge.
# This is useful for scenarios where the user must provide additional authentication factors.
included: {
amr: ['mfa', 'fpt']
},
},
# The `params` field defines any additional parameters that are sent during the authentication process.
# In this example, the `claims` parameter is added to the authorization request and instructs the
# identity provider to include an 'acr' claim with the value 'gold' in the ID token.
# The 'essential: true' indicates that this claim is required for successful authentication.
params: {
claims: {
id_token: {
acr: {
essential: true,
values: ['gold']
}
}
}
}
},
}
}
Enregistrez le fichier de configuration et redémarrez GitLab pour que les modifications prennent effet.
Vous pouvez forcer les utilisateurs à effectuer une authentification step-up avant d'accéder à un groupe. Ce paramètre est géré individuellement pour chaque groupe, mais nécessite un fournisseur d'authentification step-up préalablement ajouté pour l'ensemble de l'instance.
Prérequis :
Pour forcer l'authentification step-up pour un groupe :
Lorsque l'authentification step-up échoue, GitLab peut afficher des liens de documentation personnalisés pour aider les utilisateurs à comprendre les exigences d'authentification de votre organisation. Cette fonctionnalité permet aux administrateurs de fournir des conseils spécifiques à l'organisation qui dirigent les utilisateurs vers la documentation interne ou les ressources d'aide.
Pour ajouter des liens de documentation personnalisés :
Modifiez votre fichier de configuration GitLab (gitlab.yml ou /etc/gitlab/gitlab.rb) pour ajouter un champ documentation_link à step_up_auth => admin_mode
production: &base
omniauth:
providers:
- { name: 'openid_connect',
label: 'Corporate SSO',
# ... other provider configuration ...
step_up_auth: {
admin_mode: {
# ... id_token and params configuration ...
documentation_link: 'https://internal.example.com/path/to/documentation'
}
}
}
Enregistrez le fichier de configuration et redémarrez GitLab pour que les modifications prennent effet.
Lorsque les utilisateurs échouent à l'authentification step-up, ils voient un message d'erreur utile avec des liens vers la documentation pertinente pour les fournisseurs qui ont échoué. Les liens s'affichent uniquement pour les fournisseurs pour lesquels l'authentification step-up a réellement échoué, rendant les conseils plus pertinents et exploitables.
[!note] Bonnes pratiques pour les liens de documentation :
- Utilisez des URL HTTPS pour des raisons de sécurité.
- Créez un lien vers la documentation interne qui explique les exigences d'authentification spécifiques à votre organisation.
- Incluez des informations sur la façon d'activer
MFAou d'autres méthodes d'authentification requises.
Par défaut, les sessions d'authentification step-up expirent en fonction du délai d'expiration du jeton du fournisseur d'identité (IdP), généralement environ 10 minutes.
Vous pouvez contrôler l'expiration de la session avec le paramètre session_expiration_enabled :
| Paramètre | Comportement |
|---|---|
session_expiration_enabled: true (par défaut) | L'authentification step-up expire en fonction de la revendication exp du jeton IdP. Cela représente généralement environ 10 minutes. |
session_expiration_enabled: false | L'authentification step-up reste valide pendant toute la session utilisateur jusqu'à la déconnexion de l'utilisateur. |
[!warning] La désactivation de l'expiration de session signifie que les utilisateurs ne s'authentifient qu'une seule fois par session plutôt que de vérifier périodiquement leur identité. Ne désactivez ce paramètre que si vos exigences de sécurité autorisent une authentification step-up valable pour toute la durée de la session.
Pour désactiver l'expiration de session :
{{< tabs >}}
{{< tab title="Linux package (Omnibus)" >}}
Modifiez /etc/gitlab/gitlab.rb :
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect",
label: "Provider name",
args: {
name: "openid_connect",
# ... other args ...
},
step_up_auth: {
session_expiration_enabled: false, # Disable session expiration
admin_mode: {
# ... admin_mode config ...
},
namespace: {
# ... namespace config ...
}
}
}
]
Enregistrez le fichier et reconfigurez GitLab :
sudo gitlab-ctl reconfigure
{{< /tab >}}
{{< tab title="Self-compiled (source)" >}}
Modifiez config/gitlab.yml :
production: &base
omniauth:
providers:
- { name: 'openid_connect',
label: 'Provider name',
args: {
name: 'openid_connect',
# ... other args ...
},
step_up_auth: {
session_expiration_enabled: false,
admin_mode: {
# ... admin_mode config ...
},
namespace: {
# ... namespace config ...
}
}
}
Enregistrez le fichier et redémarrez GitLab :
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
{{< /tab >}}
{{< /tabs >}}
discovery est défini sur true. Si vous le définissez sur false, vous devez spécifier toutes les URL et clés requises pour que OpenID fonctionne.issuer correspond à l'URL de base de l'URL de découverte. Par exemple, https://accounts.google.com est utilisé pour l'URL https://accounts.google.com/.well-known/openid-configuration.client_auth_method n'est pas défini ou s'il est défini sur basic. Si vous voyez des erreurs 401 lors de la récupération du point de terminaison userinfo, vérifiez la configuration de votre serveur web OpenID. Par exemple, pour oauth2-server-php , vous devrez peut-être ajouter un paramètre de configuration à Apache.step_up_auth => admin_mode => params sont également définis dans args => allow_authorize_params. Cela inclut les paramètres dans les paramètres de requête de la requête utilisés pour la redirection vers le point de terminaison d'autorisation de l'IdP.