Merge branch 'docs/multiple-oidc-provider-and-use-within-azure' into 'master'

Document usage of multiple OpenID connect provider

Closes omnibus-gitlab#5992

See merge request !117764



Merged-by: Jon Glassman <jglassman@gitlab.com>
Approved-by: Jon Glassman <jglassman@gitlab.com>
Reviewed-by: Roger Meier <r.meier@siemens.com>
Co-authored-by: Roger Meier <r.meier@siemens.com>

doc/administration/auth/oidc.md

@@ -561,6 +561,153 @@ Example installations from source configuration (file path: `config/gitlab.yml`)
     }
 ```
 
+## Configure multiple OpenID Connect providers
+
+You can configure your application to use multiple OpenID Connect (OIDC) providers. You do this by explicitly setting the `strategy_class` in your configuration file.
+
+You should do this in either of the following scenarios:
+
+- [Migrating to the OpenID Connect protocol](../../integration/azure.md#migrate-to-the-openid-connect-protocol).
+- Offering different levels of authentication.
+
+NOTE:
+This is not compatible with [configuring users based on OIDC group membership](#configure-users-based-on-oidc-group-membership). For more information, see [issue 408248](https://gitlab.com/gitlab-org/gitlab/-/issues/408248).
+
+The following example configurations show how to offer different levels of authentication, one option with 2FA and one without 2FA.
+
+For Omnibus GitLab:
+
+```ruby
+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"
+      }
+    }
+  }
+]
+```
+
+For installation from source:
+
+```yaml
+  - { 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'
+        }
+      }
+    }
+```
+
+In this use case, you might want to synchronize the `extern_uid` across the
+different providers based on an existing known identifier in your
+corporate directory.
+
+To do this, you set the `uid_field`. The following example code shows how to
+do this:
+
+```python
+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
+```
+
+For more information, see the [GitLab API user method documentation](https://python-gitlab.readthedocs.io/en/stable/gl_objects/users.html#examples).
+
 ## Configure users based on OIDC group membership **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209898) in GitLab 15.10.

doc/integration/azure.md

@@ -16,6 +16,140 @@ For new projects, Microsoft suggests you use the
 [OpenID Connect protocol](../administration/auth/oidc.md#configure-microsoft-azure),
 which uses the Microsoft identity platform (v2.0) endpoint.
 
+## Migrate to the OpenID Connect protocol
+
+To migrate to the OpenID Connect protocol, see [configure multiple OpenID Connect providers](../administration/auth/oidc.md#configure-multiple-openid-connect-providers).
+
+You must set the `uid_field`, which differs across the providers:
+
+| Provider                                                                                                        | `uid` | Remarks                                                               |
+|-----------------------------------------------------------------------------------------------------------------|-------|-----------------------------------------------------------------------|
+| [`omniauth-azure-oauth2`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/vendor/gems/omniauth-azure-oauth2) | `sub` | Additional attributes `oid`, `tid` are offered within the info object |
+| [`omniauth-azure-activedirectory-v2`](https://github.com/RIPAGlobal/omniauth-azure-activedirectory-v2/)         | `oid` | You must configure `oid` as `uid_field` when migrating                |
+| [`omniauth_openid_connect`](https://github.com/omniauth/omniauth_openid_connect/)                               | `sub` | Specify `uid_field` to use another field                              |
+
+To migrate from `omniauth-azure-oauth2` to `omniauth_openid_connect` you
+must change the configuration:
+
+- **For Omnibus installations**
+
+```diff
+gitlab_rails['omniauth_providers'] = [
+  {
+    name: "azure_oauth2",
+    # label: "Provider name", # optional label for login button, defaults to "Azure AD"
+    args: {
++      name: "azure_oauth2",
++      strategy_class: "OmniAuth::Strategies::OpenIDConnect",
++      scope: ["openid", "profile", "email"],
++      response_type: "code",
++      issuer:  "https://login.microsoftonline.com/<tenant_id>/v2.0",
++      client_auth_method: "query",
++      discovery: true,
++      uid_field: "sub",
++      client_options: {
++        identifier: "<client_id>",
++        secret: "<client_secret>",
++        redirect_uri: "https://gitlab.example.com/users/auth/azure_oauth2/callback"
++      }
+-      client_id: "<client_id>",
+-      client_secret: "<client_secret>",
+-      tenant_id: "<tenant_id>",
+    }
+  }
+]
+```
+
+- **For installations from source**
+
+```diff
+  - { name: 'azure_oauth2',
+      # label: 'Provider name', # optional label for login button, defaults to "Azure AD"
+-      args: { client_id: '<client_id>',
+-              client_secret: '<client_secret>',
+-              tenant_id: '<tenant_id>' } }
++      icon: "<custom_provider_icon>",
++      args: {
++        name: "azure_oauth2",
++        strategy_class: "OmniAuth::Strategies::OpenIDConnect",
++        scope: ["openid","profile","email"],
++        response_type: "code",
++        issuer: 'https://login.microsoftonline.com/<tenant_id>/v2.0',
++        discovery: true,
++        client_auth_method: 'query',
++        uid_field: 'sub',
++        send_scope_to_token_endpoint: "false",
++        client_options: {
++          identifier: "<client_id>",
++          secret: "<client_secret>",
++          redirect_uri: "<your_gitlab_url>/users/auth/azure_oauth2/callback"
++        }
++      }
+    }
+```
+
+To migrate for example from `omniauth-azure-activedirectory-v2` to `omniauth_openid_connect` you
+must change the configuration:
+
+- **For Omnibus installations**
+
+```diff
+gitlab_rails['omniauth_providers'] = [
+  {
+ -    name: "azure_activedirectory_v2",
+    # label: "Provider name", # optional label for login button, defaults to "Azure AD v2"
+    args: {
++      name: "azure_activedirectory_v2",
++      strategy_class: "OmniAuth::Strategies::OpenIDConnect",
++      scope: ["openid", "profile", "email"],
++      response_type: "code",
++      issuer:  "https://login.microsoftonline.com/<tenant_id>/v2.0",
++      client_auth_method: "query",
++      discovery: true,
++      uid_field: "oid",
++      client_options: {
++        identifier: "<client_id>",
++        secret: "<client_secret>",
++        redirect_uri: "https://gitlab.example.com/users/auth/azure_activedirectory_v2/callback"
++      }
+-      client_id: "<client_id>",
+-      client_secret: "<client_secret>",
+-      tenant_id: "<tenant_id>",
+    }
+  }
+]
+```
+
+- **For installations from source**
+
+```diff
+  - { name: 'azure_activedirectory_v2',
+      # label: 'Provider name', # optional label for login button, defaults to "Azure AD v2"
+-      args: { client_id: '<client_id>',
+-              client_secret: '<client_secret>',
+-              tenant_id: '<tenant_id>' } }
++      icon: "<custom_provider_icon>",
++      args: {
++        name: "azure_activedirectory_v2",
++        strategy_class: "OmniAuth::Strategies::OpenIDConnect",
++        scope: ["openid","profile","email"],
++        response_type: "code",
++        issuer: 'https://login.microsoftonline.com/<tenant_id>/v2.0',
++        discovery: true,
++        client_auth_method: 'query',
++        uid_field: 'oid',
++        send_scope_to_token_endpoint: "false",
++        client_options: {
++          identifier: "<client_id>",
++          secret: "<client_secret>",
++          redirect_uri: "<your_gitlab_url>/users/auth/azure_activedirectory_v2/callback"
++        }
++      }
+    }
+```
+
+For more information on other customizations, see [`gitlab_username_claim`](index.md#authentication-sources).
+
 ## Register an Azure application
 
 To enable the Microsoft Azure OAuth 2.0 OmniAuth provider, you must register