認証プロバイダーとしてOpenID Connectを使用する

OpenID ConnectをOmniAuthプロバイダーとして利用するクライアントアプリケーションとして、GitLabを設定できます。

OpenID Connect OmniAuthプロバイダーを有効にするには、OpenID Connectプロバイダーにアプリケーションを登録する必要があります。OpenID Connectプロバイダーは、使用するクライアントの詳細とシークレットを提供します。

1. GitLabサーバーで、設定ファイルを開きます。

   Linuxパッケージインストールの場合:

   sudo editor /etc/gitlab/gitlab.rb

   自己コンパイルによるインストールの場合:

   cd /home/git/gitlab
   sudo -u git -H editor config/gitlab.yml

2. 共通設定で、openid_connectをシングルサインオンプロバイダーとして追加します。これにより、既存のGitLabアカウントを持たないユーザーに対して、Just-In-Timeアカウントプロビジョニングが有効になります。

3. プロバイダー設定を追加します。

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

   Linuxパッケージインストールで複数のIdentity Providerを使用する場合:

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

   自己コンパイルによるインストールの場合:

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

   各設定オプションの詳細については、OmniAuth OpenID Connectの使用方法に関するドキュメントおよびOpenID Connect Core 1.0の仕様を参照してください。

4. プロバイダーを設定する際は、ご利用のOpenID Connectクライアントの設定に合わせてプロバイダーの値を変更する必要があります。次の情報を参考にしてください:

   • <your_oidc_label>は、ログインページに表示されるラベルです。
   • <custom_provider_icon>（オプション）は、ログインページに表示されるアイコンです。主要なソーシャルログインプラットフォームのアイコンはGitLabに組み込まれていますが、このパラメータを指定することで、これらのアイコンを上書きできます。GitLabではローカルパスと絶対URLの両方を使用できます。GitLabには、主要なソーシャルログインプラットフォームのほとんどのアイコンが組み込まれていますが、外部URL、または独自のアイコンファイルの絶対パスまたは相対パスを指定することで、これらのアイコンを上書きできます。
     • ローカルの絶対パスを使用する場合は、プロバイダーの設定で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>（オプション）は、OpenID Connectプロバイダーを指すURLです（例: https://example.com/auth/realms/your-realm）。この値を指定しない場合、URLはclient_optionsに基づき次の形式で構築されます。<client_options.scheme>://<client_options.host>:<client_options.port>
   • discoveryがtrueに設定されている場合、OpenID Connectプロバイダーは<your_oidc_url>/.well-known/openid-configurationを使用してクライアントオプションを自動的に検出しようとします。falseがデフォルトです。
   • client_auth_method（オプション）は、OpenID Connectプロバイダーに対してクライアントを認証する際に使用する方法を指定します。
     • サポートされている値は次のとおりです:
       • basic - HTTP基本認証。
       • jwt_bearer - JWTベースの認証（秘密キーとクライアントシークレットによる署名）。
       • mtls - 相互TLSまたはX.509証明書による検証。
       • その他の値はすべて、リクエスト本文にクライアントIDとシークレットを含めてポストします。
     • この値を指定しない場合、デフォルトはbasicです。
   • <uid_field>（オプション）は、user_info.raw_attributesに含まれるフィールド名で、uidの値を定義します（例: preferred_username）。この値を指定しない場合、または設定した値を持つフィールドがuser_info.raw_attributesの詳細に存在しない場合、uidにはsubフィールドを使用します。
   • send_scope_to_token_endpointはデフォルトでtrueであるため、scopeパラメータは通常、トークンエンドポイントへのリクエストに含まれます。ただし、OpenID Connectプロバイダーがこの種のリクエストでscopeパラメータを受け付けない場合は、これをfalseに設定します。
   • pkce（オプション）: Proof Key for Code Exchangeを有効にします。
   • client_optionsは、OpenID Connectクライアント固有のオプションです。具体的には次のとおりです:
     • identifierは、OpenID Connectサービスプロバイダーで設定されているクライアント識別子です。
     • secretは、OpenID Connectサービスプロバイダーで設定されているクライアントシークレットです。たとえば、OmniAuth OpenID Connectではこれが必要です。サービスプロバイダーがシークレットを必要としない場合は、任意の値を指定します。その値は無視されます。
     • redirect_uriは、ログインに成功した後、ユーザーをリダイレクトするGitLabのURLです（例: http://example.com/users/auth/openid_connect/callback）。
     • end_session_endpoint（オプション）は、セッションを終了するエンドポイントのURLです。自動検出が無効になっているか失敗した場合は、このURLを指定できます。
     • 次のclient_optionsは、自動検出が無効になっているか失敗した場合を除き、オプションです:
       • authorization_endpoint: エンドユーザーを認可するエンドポイントのURL。
       • token_endpoint: アクセストークンを提供するエンドポイントのURL。
       • userinfo_endpoint: ユーザー情報を提供するエンドポイントのURL。
       • jwks_uri: トークン署名者がキーを公開するエンドポイントのURL。

5. 設定ファイルを保存します。

6. 変更を有効にするには、次の手順に従います:

   • Linuxパッケージを使用してGitLabをインストールした場合は、GitLabを再設定します。
   • GitLabインストールを自分でコンパイルした場合は、GitLabを再起動します。

サインインページで、標準のサインインフォームの下にOpenID Connectオプションが表示されます。このオプションを選択すると、認証プロセスが開始されます。クライアントによる確認が必要な場合、OpenID Connectプロバイダーは、サインインとGitLabアプリケーションの認可を求めます。その後、GitLabにリダイレクトされ、サインインが完了します。

設定例

次の設定は、Linuxパッケージインストールを使用している場合に、さまざまなプロバイダーでOpenIDをセットアップする方法を示しています。

Googleを設定する

詳細については、Googleのドキュメントを参照してください:

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",
       }
     }
  }
]

Microsoft Azureを設定する

Microsoft AzureにおけるOpenID Connect（OIDC）プロトコルは、Microsoft IDプラットフォーム（v2）エンドポイントを使用します。開始するには、Azureポータルにサインインします。アプリには、次の情報が必要です:

• テナントID。すでにお持ちの場合もあります。詳細については、Microsoft Azureのテナントに関するドキュメントを参照してください。
• クライアントIDとクライアントシークレット。Microsoftのアプリケーション登録に関するクイックスタートドキュメントの手順に従って、アプリ用のテナントID、クライアントID、クライアントシークレットを取得します。

Microsoft Azureアプリケーションを登録するときには、GitLabが必要な詳細を取得できるように、API権限を付与する必要があります。少なくともopenid、profile、emailの各権限を付与する必要があります。詳細については、Web APIのアプリ権限の設定に関するMicrosoftのドキュメントを参照してください。

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は、自社のプラットフォームがOIDCプロトコルでどのように動作するのかを文書化しています。

Microsoft Entraのカスタム署名キー

SAMLクレームマッピング機能を使用しているためにアプリケーションでカスタム署名キーを使用している場合は、OpenIDプロバイダーを次のように設定する必要があります:

• args.discoveryを省略するか、falseに設定して、OpenID Connectのディスカバリを無効にします。
• client_optionsで、次のように指定します:
  • appidクエリパラメータを含むjwks_uri: https://login.microsoftonline.com/<YOUR-TENANT-ID>/discovery/v2.0/keys?appid=<YOUR APP CLIENT ID>
  • end_session_endpoint。
  • authorization_endpoint。
  • userinfo_endpoint。

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

認証エラーが発生し、KidNotFoundというメッセージが表示される場合、原因はappidクエリパラメータの欠落または誤りである可能性が高いです。Microsoftから返されたIDトークンが、jwks_uriエンドポイントで提供されるキーによって検証できないときに、GitLabはこのエラーを返します。

詳細については、Microsoft Entraのトークンの検証に関するドキュメントを参照してください。

汎用OpenID Connect設定に移行する

azure_activedirectory_v2とazure_oauth2のどちらからでも、汎用OpenID Connect設定に移行できます。

まず、uid_fieldを設定します。uid_field、およびuid_fieldとして設定できるsubクレームは、プロバイダーによって異なります。uid_fieldを設定せずにサインインすると、GitLab内に別のIDが作成され、手動で変更する必要があります:

汎用OpenID Connect設定に移行するには、設定を更新する必要があります。

Linuxパッケージインストールの場合、次のように設定を更新します:

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

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

Helmインストールの場合:

YAMLファイル（例: provider.yaml）にプロバイダーの設定を追加します:

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

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

GitLab 17.0以降へのアップグレードに伴い、azure_oauth2からomniauth_openid_connectに移行する際、組織に設定されるsubクレームの値が異なる場合があります。azure_oauth2はMicrosoft V1エンドポイントを使用しますが、azure_activedirectory_v2およびomniauth_openid_connectはどちらも、共通のsub値を持つMicrosoft V2エンドポイントを使用します。

• For users with an email address in Entra ID（Entra IDにメールアドレスを登録しているユーザーに対して）、メールアドレスへのフォールバックを許可してユーザーのアイデンティティを更新するには、次のように設定します:

  • Linuxパッケージインストールの場合: omniauth_auto_link_user。
  • Helmインストールの場合: autoLinkUser。

• For users with no email address（メールアドレスを持たないユーザーに対して）、管理者は次のいずれかの操作を行う必要があります:

  • 別の認証方法を設定するか、GitLabのユーザー名とパスワードによるサインインを有効にします。ユーザーはその後サインインして、自分のプロファイルを使用してAzureのアイデンティティを手動でリンクできます。
  • 既存のazure_oauth2に加えて、OpenID Connectを新しいプロバイダーとして実装します。これにより、ユーザーがOAuth 2.0を通じてサインインし、OpenID Connectのアイデンティティをリンクできるようになります（前述の方法と同様）。この方法は、auto_link_userが有効になっている限り、メールアドレスを持つユーザーにも有効です。
  • extern_uidを手動で更新します。これを行うには、APIまたはRailsコンソールを使用して、各ユーザーのextern_uidを更新します。この方法は、インスタンスがすでに17.0以降にアップグレードされており、ユーザーがサインインを試みた場合に必要になることがあります。

Microsoft Azure Active Directory B2Cを設定する

GitLabをAzure Active Directory B2Cと連携させるには、特別な設定が必要です。開始するには、Azureポータルにサインインします。アプリには、Azureからの次の情報が必要です:

• テナントID。すでにお持ちの場合もあります。詳細については、Microsoft Azureのテナントに関するドキュメントを参照してください。
• クライアントIDとクライアントシークレット。Microsoftのチュートリアルドキュメントの手順に従って、アプリ用のクライアントIDとクライアントシークレットを取得します。
• ユーザーフローまたはポリシー名。Microsoftのチュートリアルの手順に従います。

アプリを設定します:

1. アプリのRedirect URIを設定します。たとえば、GitLabドメインがgitlab.example.comの場合、アプリのRedirect URIを、https://gitlab.example.com/users/auth/openid_connect/callbackに設定します。

2. IDトークンを有効にします。

3. アプリに次のAPI権限を追加します:

   • openid
   • offline_access

カスタムポリシーを設定する

Azure B2Cは、ユーザーのログインに関するビジネスロジックを定義する方法を2つ提供しています:

• ユーザーフロー
• カスタムポリシー

標準のAzure B2CユーザーフローはOpenIDのemailクレームを送信しないため、カスタムポリシーが必要です。そのため、標準のユーザーフローはallow_single_sign_onまたはauto_link_userパラメータでは機能しません。標準のAzure B2Cポリシーでは、GitLabは新しいアカウントを作成したり、メールアドレスを持つ既存のアカウントにリンクしたりできません。

まず、カスタムポリシーを作成します。

Microsoftの手順では、カスタムポリシースターターパックにおいてSocialAndLocalAccountsを使用していますが、LocalAccountsはローカルActive Directoryアカウントに対して認証を行います。ポリシーをアップロードする前に、次の操作を行います:

1. emailクレームをエクスポートするには、SignUpOrSignin.xmlを変更します。次の行を置き換えます:

   <OutputClaim ClaimTypeReferenceId="email" />

   変更後は次のようになります:

   <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email" />

2. B2CでOIDCディスカバリを機能させるには、OIDC仕様と互換性のある発行者をポリシーに設定します。トークンの互換性設定を参照してください。TrustFrameworkBase.xmlのJwtIssuerで、IssuanceClaimPatternを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>
           ...

3. ポリシーをアップロードします。既存のポリシーを更新する場合は、既存のファイルを上書きします。

4. 発行者URLを指定する際は、サインインポリシーを使用します。発行者URLの形式は次のとおりです:

   https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/

   ポリシー名はURL内では小文字になります。たとえば、B2C_1A_signup_signinポリシーの場合は、b2c_1a_signup_siginと小文字で指定します。

   末尾にスラッシュを付加してください。

5. OIDCディスカバリURLと発行者URLの動作を確認し、.well-known/openid-configurationを発行者URLに付加します:

   https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/.well-known/openid-configuration

   たとえば、domainがexample.b2clogin.comで、テナントIDがfc40c736-476c-4da1-b489-ee48cee84386の場合、curlとjqを使用して発行者を抽出できます:

   $ 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/"

6. signup_signinに使用するカスタムポリシーで、発行者URLを設定します。たとえば、Linuxパッケージインストールでb2c_1a_signup_signinのカスタムポリシーを使用した場合の設定は次のとおりです:

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

Azure B2Cのトラブルシューティング

• yourtenant.onmicrosoft.com、ProxyIdentityExperienceFrameworkAppId、IdentityExperienceFrameworkAppIdのすべての箇所が、B2Cテナントのホスト名およびXMLポリシーファイル内の対応するクライアントIDと一致していることを確認します。

• アプリのリダイレクトURIとしてhttps://jwt.msを追加し、カスタムポリシーテスターを使用します。ペイロードに、ユーザーのメールアクセスと一致するemailが含まれていることを確認します。

• カスタムポリシーを有効にした後、ユーザーがサインインしようとすると、Invalid username or passwordと表示される場合があります。これは、IdentityExperienceFrameworkアプリの設定に問題がある可能性があります。こちらのMicrosoftのコメントを参照してください。このコメントでは、アプリのマニフェストに次の設定が含まれているかを確認することが推奨されています:

  • "accessTokenAcceptedVersion": null
  • "signInAudience": "AzureADMyOrg"

この設定は、IdentityExperienceFrameworkアプリの作成時に使用したSupported account typesの設定に対応しています。

Keycloakを設定する

GitLabは、HTTPSを使用するOpenIDプロバイダーと連携します。HTTPを使用するKeycloakサーバーをセットアップすることもできますが、GitLabが通信できるのはHTTPSを使用するKeycloakサーバーのみです。

トークンに署名するために公開キーアルゴリズムを使用するようにKeycloakを構成します。たとえば、HS256またはHS358の代わりにRSA256またはRSA512を使用します。公開キー暗号化アルゴリズムには次の利点があります:

• 簡単に設定できる。
• 秘密キーが漏えいした場合はセキュリティ上重大な結果を招く可能性があるため、公開キー暗号化アルゴリズムのほうが安全性が高い。

1. Keycloak管理コンソールを開きます。
2. Realm Settings > Tokens > Default Signature Algorithmを選択します。
3. 署名アルゴリズムを設定します。

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

対称キーアルゴリズムでKeycloakを設定する

対称キー暗号化を使用するには、次の手順に従います:

1. Keycloakデータベースからシークレットキーを抽出します。Keycloakでは、この値をWebインターフェースでは公開していません。Webインターフェースに表示されるクライアントシークレットはOAuth 2.0クライアントシークレットであり、JSON Web Tokenの署名に使用されるシークレットとは異なります。

   たとえば、PostgreSQLをKeycloakのバックエンドデータベースとして使用する場合:

   • データベースコンソールにサインインします。

   • 次のSQLクエリを実行して、キーを抽出します:

     $ 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

     この例では、2つの秘密キーがあります。1つはHS256用（hmac-generated）、もう1つはHS384用（fallback-HS384）です。GitLabの設定には、最初のvalueを使用します。

2. valueを標準のbase64に変換します。「HS256トークンでの無効な署名」の投稿で説明されているように、valueは、RFC 4648の「URLおよびファイル名に安全なアルファベットを使用したBase 64エンコード」セクションでエンコードされています。これは、RFC 2045で定義されている標準のbase64に変換する必要があります。次のRubyスクリプトはその変換を行います:

   require 'base64'
   
   value = "lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62-sqGc8drp3XW-wr93zru8PFsQokHZZuJJbaUXvmiOftCZM3C4KW3-g"
   Base64.encode64(Base64.urlsafe_decode64(value))

   これにより、次のような値が得られます:

   lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62+sqGc8drp3XW+wr93zru8PFsQokH\nZZuJJbaUXvmiOftCZM3C4KW3+g==\n

3. このbase64エンコードされたシークレットをjwt_secret_base64に指定します。例は次のとおりです:

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

JSON::JWS::VerificationFailedエラーが表示された場合は、間違ったシークレットを指定しています。

Casdoor

GitLabは、HTTPSを使用するOpenIDプロバイダーと連携します。Casdoorを使用してOpenID経由でGitLabに接続するには、HTTPSを使用してください。

アプリに対して、Casdoorで次の手順を実行します:

1. クライアントIDとクライアントシークレットを取得します。
2. GitLabのリダイレクトURLを追加します。たとえば、GitLabドメインがgitlab.example.comの場合、Casdoorアプリに次のRedirect URIが設定されていることを確認してください: https://gitlab.example.com/users/auth/openid_connect/callback。

詳細については、Casdoorのドキュメントを参照してください。

Linuxパッケージインストールにおける設定例（ファイルパス: /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"
            }
        }
    }
]

自己コンパイルインストールにおける設定例（ファイルパス: 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'
        }
      }
    }

複数のOpenID Connectプロバイダーを設定する

複数のOpenID Connect（OIDC）プロバイダーを使用するようにアプリケーションを設定できます。そのためには、設定ファイルでstrategy_classを明示的に指定します。

これは、次のいずれかのシナリオで行う必要があります:

• OpenID Connectプロトコルに移行する。
• 異なるレベルの認証を提供する。

次の設定例は、2FAがある場合と2FAがない場合という、異なるレベルの認証を提供する方法を示しています。

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

自己コンパイルによるインストールの場合:

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

このユースケースでは、社内ディレクトリ内の既知の識別子に基づいて、異なるプロバイダー間でextern_uidを同期させたい場合があります。

これを行うには、uid_fieldを設定します。次のコード例は、その設定方法を示しています:

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

詳細については、GitLab APIのユーザーメソッドに関するドキュメントを参照してください。

OIDCグループメンバーシップに基づいてユーザーを設定する

OIDCグループメンバーシップを設定して、次のことを行えます:

• ユーザーが特定のグループのメンバーであることを必須にする。
• グループメンバーシップに基づいて、ユーザーに外部 、管理者、監査担当者のいずれかのロールを割り当てる。

GitLabは、サインインのたびにこれらのグループをチェックし、必要に応じてユーザー属性を更新します。ただし、この機能では、GitLabグループにユーザーを自動的に追加することはdoes not（できません）。

必須グループ

Identity Provider（IdP）は、OIDC応答でグループ情報をGitLabに渡す必要があります。この応答を利用して、特定のグループへの所属を必須にする場合は、GitLab側で次の項目を識別するように設定します:

• OIDC応答内でグループがある場所（groups_attribute設定を使用）。
• サインインに必要なグループメンバーシップ（required_groups設定を使用）。

required_groupsを設定しない場合、または設定を空のままにしている場合は、IdPによってOIDC経由で認証されたユーザーであれば誰でもGitLabを使用できます。

外部グループ

IdPは、OIDC応答でグループ情報をGitLabに渡す必要があります。この応答を使用して、グループメンバーシップに基づいてユーザーを外部ユーザーとして識別するには、次の情報を特定できるようにGitLabを設定します:

• OIDC応答内でグループがある場所（groups_attribute設定を使用）。
• どのグループメンバーシップに基づきユーザーを外部ユーザーとして識別するか（external_groups設定を使用。

監査担当者グループ

IdPは、OIDC応答でグループ情報をGitLabに渡す必要があります。この応答を使用して、グループメンバーシップに基づいてユーザーに監査担当者を割り当てるには、次の情報を特定できるようにGitLabを設定します:

• OIDC応答内でグループがある場所（groups_attribute設定を使用）。
• どのグループメンバーシップに基づきユーザーに監査担当者アクセス権を付与するか（auditor_groups設定を使用）。

管理者グループ

IdPは、OIDC応答でグループ情報をGitLabに渡す必要があります。この応答を使用して、グループメンバーシップに基づいてユーザーに管理者を割り当てるには、次の情報を特定できるようにGitLabを設定します:

• OIDC応答内でグループがある場所（groups_attribute設定を使用）。
• どのグループメンバーシップに基づきユーザーに管理者アクセス権を付与するか（admin_groups設定を使用）。

IDトークンのカスタム有効期間を設定する

デフォルトでは、GitLabのIDトークンは120秒で有効期限が切れます。

IDトークンのカスタム有効期間を設定するには、次の手順に従います:

ステップアップ認証

場合によっては、デフォルトの認証方法では重要なリソースやリスクの高いアクションを十分に保護できないことがあります。ステップアップ認証は、特権行動または機密オペレーションのための追加レイヤーを追加します。たとえば、管理者エリアにアクセスするなどです。

ステップアップ認証を使用すると、特定の機能にアクセスする前に、ユーザーは登録済みの2要素認証で追加の認証を完了する必要があります。

OIDC標準には、認証コンテキストクラス参照（ACR）が含まれています。このACRの概念は、管理者モードなどのさまざまなシナリオに合わせてステップアップ認証を設定および実装する際に役立ちます。

これは実験的機能であり、予告なく変更される場合があります。この機能は本番環境での使用には対応していません。この機能を使用する場合は、まず本番環境以外でテストする必要があります。

管理者モードのステップアップ認証を有効にする

1. GitLab設定ファイル（gitlab.ymlまたは/etc/gitlab/gitlab.rb）を編集して、特定のOmniAuthプロバイダーに対してステップアップ認証を有効にします。

   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'
             },
           }
         }

2. 設定ファイルを保存してGitLabを再起動し、変更を有効にします。

Keycloakでステップアップ認証を要求する

Keycloakは、認証レベルとカスタムブラウザログインフローを定義することで、ステップアップ認証に対応します。

Keycloakで管理者モードのステップアップ認証を要求するには、次の手順を実行します:

1. GitLabでKeycloakを設定します。

2. Keycloakドキュメントの手順に従って、Keycloakでステップアップ認証を使用してブラウザログインフローを作成します。

3. GitLab設定ファイル（gitlab.ymlまたは/etc/gitlab/gitlab.rb）を編集して、Keycloak OIDCプロバイダー設定でステップアップ認証を有効にします。

   Keycloakは、silverとgoldという2種類の認証レベルを定義します。次の例では、セキュリティレベルが強化されていることを示すためにgoldを使用しています。

   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'
             },
           }
         }

4. 設定ファイルを保存してGitLabを再起動し、変更を有効にします。

Microsoft Entra IDでステップアップ認証を要求する

Microsoft Entra ID（旧称: Azure Active Directory）は、条件付きアクセス認証のコンテキストでステップアップ認証をサポートしています。Microsoft Entra IDの管理者と協力して、正しい設定を定義する必要があります。

次の点を考慮してください:

• 認証コンテキストIDは、他のIdentity Providerに使用されるIDトークンクレームacrではなく、acrsクレームのみを介してリクエストされます。
• 認証コンテキストIDは、c1からc99までの固定値を使用します。それぞれの値は、条件付きアクセスポリシーが適用された特定の認証コンテキストを表します。
• デフォルトでは、Microsoft Entra IDはIDトークンにacrsクレームを含めません。これを有効にするには、オプションのクレームを設定する必要があります。
• ステップアップ認証が成功すると、応答はacrsクレームを文字列のJSON配列として返します。例: acrs: ["c1", "c2", "c3"]。

Microsoft Entra IDで管理者モードのステップアップ認証を要求するには、次の手順を実行します:

1. GitLabでMicrosoft Entra IDを設定します。

2. Microsoft Entra IDのドキュメントの手順に従って、Microsoft Entra IDで条件付きアクセス認証コンテキストを定義します。

3. Microsoft Entra IDで、IDトークンに含めるオプションのacrsクレームを定義します。

4. GitLab設定ファイル（gitlab.ymlまたは/etc/gitlab/gitlab.rb）を編集して、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'
           },
         }
       }

5. 設定ファイルを保存してGitLabを再起動し、変更を有効にします。

グループのステップアップ認証プロバイダーを追加する

インスタンス内のすべてのグループが利用できるステップアップ認証プロバイダーを追加することもできます。これにより、グループでステップアップ認証の使用が強制されることはありません。各グループでこの機能を個別に設定する必要があります。

グループのステップアップ認証プロバイダーを追加するには、次の手順を実行します:

1. GitLab設定ファイル（gitlab.ymlまたは/etc/gitlab/gitlab.rb）を編集して、特定のOmniAuthプロバイダーに対してステップアップ認証を有効にします。

   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']
                     }
                   }
                 }
               }
             },
           }
         }

2. 設定ファイルを保存してGitLabを再起動し、変更を有効にします。

グループのステップアップ認証を強制する

ユーザーがグループにアクセスする前に、ステップアップ認証を完了するように強制できます。この設定はグループごとに個別に管理されますが、インスタンス全体に対して以前に追加されたステップアップ認証プロバイダーが要件となります。

前提要件:

• インスタンス内のグループのステップアップ認証プロバイダー。
• オーナーロールを持っている必要があります。

グループのステップアップ認証を強制するには、次の手順を実行します:

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. 設定 > 一般を選択します。
3. 権限とグループ機能セクションを展開します。
4. ステップアップ認証で、利用可能な認証プロバイダーを選択します。
5. 変更を保存を選択します。

ステップアップ認証のカスタムドキュメントリンクを追加する

ステップアップ認証に失敗した場合、GitLabはカスタムドキュメントへのリンクを表示し、ユーザーが組織の認証要件を理解できるようにします。この機能により、管理者は組織固有のガイダンスを提供し、ユーザーを社内ドキュメントやヘルプリソースへ案内できます。

カスタムドキュメントリンクを追加するには、次の手順を実行します:

1. gitlab.ymlまたは/etc/gitlab/gitlab.rbのGitLabの設定ファイルを編集して、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'
             }
           }
         }

2. 設定ファイルを保存してGitLabを再起動し、変更を有効にします。

ユーザーがステップアップ認証に失敗すると、失敗したプロバイダーに対応する関連ドキュメントへのリンク付きのエラーメッセージが表示されます。リンクは実際にステップアップ認証に失敗したプロバイダーにのみ表示されるため、より適切で実用的なガイダンスを提供できます。

トラブルシューティング

1. discoveryがtrueに設定されていることを確認してください。falseに設定すると、OpenIDを機能させるために必要なすべてのURLとキーを指定する必要があります。

2. システムクロックをチェックして、時刻が正しく同期されていることを確認してください。

3. OmniAuth OpenID Connectのドキュメントで説明されているように、issuerがディスカバリURLのベースURLに対応していることを確認してください。たとえば、URLがhttps://accounts.google.com/.well-known/openid-configurationの場合、https://accounts.google.comが使用されます。

4. client_auth_methodが未定義の場合、またはbasicに設定されている場合、OpenID ConnectクライアントはHTTP基本認証を使用してOAuth 2.0アクセストークンを送信します。userinfoエンドポイントの取得時に401エラーが表示される場合は、OpenID Webサーバーの設定を確認してください。たとえば、oauth2-server-phpの場合、Apacheに設定パラメータを追加する必要がある場合があります。

5. Step-up authentication only（ステップアップ認証のみ）: step_up_auth => admin_mode => paramsで定義されているパラメータがargs => allow_authorize_paramsでも定義されていることを確認します。これにより、IdP認証エンドポイントへのリダイレクトに使用されるリクエストクエリパラメータにパラメータが含まれるようになります。