Merge branch 'sh-add-microsoft-azure-oidc-docs' into 'master'

Add example of using Microsoft Azure with OpenID Connect

See merge request gitlab-org/gitlab!54049

doc/administration/auth/oidc.md

@@ -130,8 +130,7 @@ different providers with Omnibus GitLab.
 
 ### Google
 
-See the [Google
-documentation](https://developers.google.com/identity/protocols/oauth2/openid-connect)
+See the [Google documentation](https://developers.google.com/identity/protocols/oauth2/openid-connect)
 for more details:
 
 ```ruby
@@ -156,6 +155,44 @@ for more details:
  }
 ```
 
+### Microsoft Azure
+
+The OpenID Connect (OIDC) protocol for Microsoft Azure uses the [Microsoft identity platform (v2) endpoints](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/azure-ad-endpoint-comparison).
+To get started, sign in to the [Azure Portal](https://portal.azure.com). For your app, you'll need the
+following information:
+
+- A tenant ID. You may already have one. For more information, review the
+  [Microsoft Azure Tenant](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) documentation.
+- A client ID and a client secret. Follow the instructions in the
+  [Microsoft Quickstart Register an Application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) documentation.
+to obtain the tenant ID, client ID, and client secret for your app.
+
+Example Omnibus configuration block:
+
+```ruby
+ gitlab_rails['omniauth_providers'] = [
+ {
+   'name' => 'openid_connect',
+   'label' => 'Azure OIDC',
+   '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',
+     'client_options' => {
+       'identifier' => '<YOUR APP CLIENT ID>',
+       'secret' => '<YOUR APP CLIENT SECRET>',
+       'redirect_uri' => 'https://gitlab.example.com/users/auth/openid_connect/callback'
+     }
+   }
+ }
+```
+
+Microsoft has documented how its platform works with [the OIDC protocol](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc).
+
 ## Troubleshooting
 
 If you're having trouble, here are some tips:

doc/integration/azure.md

@@ -6,6 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Microsoft Azure OAuth2 OmniAuth Provider
 
+NOTE:
+Per Microsoft, this provider uses the [older Azure Active Directory v1.0 endpoint](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-protocols-oauth-code).
+Microsoft documentation suggests that you should use the [OpenID Connect protocol to use the v2 endpoints](../administration/auth/oidc.md#microsoft-azure) for new projects.
+
 To enable the Microsoft Azure OAuth2 OmniAuth provider, you must register your application with Azure. Azure generates a client ID and secret key for you to use.
 
 Sign in to the [Azure Portal](https://portal.azure.com), and follow the instructions in