Merge branch 'kpaizee-azure-ctrt-edits-2' into 'master'

CTRT edits for Azure page - part 2

See merge request gitlab-org/gitlab!82388

doc/integration/azure.md

@@ -26,7 +26,9 @@ an Azure application and get a client ID and secret key.
 1. [Register an application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
    and provide the following information:
    - The redirect URI, which requires the URL of the Azure OAuth callback of your GitLab
-     installation. For example, `https://gitlab.mycompany.com/users/auth/azure_oauth2/callback`.
+     installation. For example:
+     - For the v1.0 endpoint: `https://gitlab.example.com/users/auth/azure_oauth2/callback`.
+     - For the v2.0 endpoint: `https://gitlab.example.com/users/auth/azure_activedirectory_v2/callback`.
    - The application type, which must be set to **Web**.
 1. Save the client ID and client secret. The client secret is only
    displayed once.
@@ -37,6 +39,17 @@ an Azure application and get a client ID and secret key.
 In some Microsoft documentation, the terms are named `Application ID` and
 `Application Secret`.
 
+## Add API permissions (scopes)
+
+If you're using the v2.0 endpoint, after you create the application, [configure it to expose a web API](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis).
+Add the following delegated permissions under the Microsoft Graph API:
+
+- `email`
+- `openid`
+- `profile`
+
+Alternatively, add the `User.Read.All` application permission.
+
 ## Enable Microsoft OAuth in GitLab
 
 1. On your GitLab server, open the configuration file.
@@ -62,6 +75,8 @@ In some Microsoft documentation, the terms are named `Application ID` and
 
    - **For Omnibus installations**
 
+     For the v1.0 endpoint:
+
      ```ruby
      gitlab_rails['omniauth_providers'] = [
        {
@@ -76,96 +91,7 @@ In some Microsoft documentation, the terms are named `Application ID` and
      ]
      ```
 
-   - **For installations from source**
-
-     ```yaml
-     - { 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' } }
-     ```
-
-     You can optionally add `base_azure_url` for different locales,
-     for example, `base_azure_url: "https://login.microsoftonline.de"`.
-
-1. Save the configuration file.
-
-1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure)
-   if you installed using Omnibus, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source)
-   if you installed from source.
-
-1. Refresh the GitLab sign-in page. A Microsoft icon should display below the
-   sign-in form.
-
-1. Select the icon. Sign in to Microsoft and authorize the GitLab application.
-
-Read [Enable OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user)
-for information on how existing GitLab users can connect to their new Azure AD accounts.
-
-## Microsoft Azure OAuth 2.0 OmniAuth Provider v2
-
-To use v2 endpoints provided by Microsoft Azure Active Directory you must to
-configure it via Azure OAuth 2.0 OmniAuth Provider v2.
-
-### Registering an Azure application
-
-To enable the Microsoft Azure OAuth 2.0 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 the [Microsoft Quickstart documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app).
-
-As you go through the Microsoft procedure, keep the following in mind:
-
-- If you have multiple instances of Azure Active Directory, you can switch to
-  the desired tenant.
-- You're setting up a Web application.
-- The redirect URI requires the URL of the Azure OAuth callback of your GitLab
-  installation. For example, `https://gitlab.example.com/users/auth/azure_activedirectory_v2/callback`.
-  The type dropdown should be set to **Web**.
-- The `client ID` and `client secret` are terms associated with OAuth 2.0. In some Microsoft documentation,
-  the terms may be listed as `Application ID` and `Application Secret`.
-- If you have to generate a new client secret, follow the Microsoft documentation
-  for [creating a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#create-a-new-application-secret).
-- Save the client ID and client secret for your new app, as the client secret is only
-  displayed one time.
-
-### Adding API permissions (scopes)
-
-After you have created an application, follow the [Microsoft Quickstart documentation to expose a web API](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). Be sure to add the following delegated permissions under the Microsoft Graph API:
-
-- `email`
-- `openid`
-- `profile`
-
-Alternatively, add the `User.Read.All` application permission.
-
-### Configuring GitLab
-
-1. On your GitLab server, open the configuration file.
-
-   For Omnibus GitLab:
-
-   ```shell
-   sudo editor /etc/gitlab/gitlab.rb
-   ```
-
-   For installations from source:
-
-   ```shell
-   cd /home/git/gitlab
-
-   sudo -u git -H editor config/gitlab.yml
-   ```
-
-1. Refer to [Configure initial settings](omniauth.md#configure-initial-settings)
-   for initial settings.
-
-1. Add the provider configuration:
-
-   For Omnibus GitLab:
+     For the v2.0 endpoint:
 
      ```ruby
      gitlab_rails['omniauth_providers'] = [
@@ -181,7 +107,19 @@ Alternatively, add the `User.Read.All` application permission.
      ]
      ```
 
-   For installations from source:
+   - **For installations from source**
+
+     For the v1.0 endpoint:
+
+     ```yaml
+     - { 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' } }
+     ```
+
+     For the v2.0 endpoint:
 
      ```yaml
      - { name: 'azure_activedirectory_v2',
@@ -191,26 +129,21 @@ Alternatively, add the `User.Read.All` application permission.
          tenant_id: "TENANT ID" } }
      ```
 
-   The `base_azure_url` is optional and can be added for different locales;
-   such as `base_azure_url: "https://login.microsoftonline.de"`.
-
-   The `scope` parameter is optional and can be added to `args`. Default `scope` is: `openid profile email`.
+   You can optionally add the following parameters:
 
-1. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID` with the values you got
-   above.
+   - `base_azure_url` for different locales. For example, `base_azure_url: "https://login.microsoftonline.de"`.
+   - `scope`, which you add to `args`. The default is `openid profile email`.
 
 1. Save the configuration file.
 
-1. Reconfigure or restart GitLab, depending on your installation method:
+1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure)
+   if you installed using Omnibus, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source)
+   if you installed from source.
 
-   - *If you installed from Omnibus GitLab,*
-     [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab.
-   - *If you installed from source,*
-     [restart GitLab](../administration/restart_gitlab.md#installations-from-source).
+1. Refresh the GitLab sign-in page. A Microsoft icon should display below the
+   sign-in form.
 
-On the sign-in page, you should now see a Microsoft icon below the regular sign-in form.
-Select the icon to begin the authentication process. Microsoft then asks you to
-sign in and authorize the GitLab application. If successful, you are returned to GitLab and signed in.
+1. Select the icon. Sign in to Microsoft and authorize the GitLab application.
 
-Read [Enable OmniAuth for an Existing User](omniauth.md#enable-omniauth-for-an-existing-user)
-for information on how existing GitLab users can connect to their newly available Azure AD accounts.
+Read [Enable OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user)
+for information on how existing GitLab users can connect to their new Azure AD accounts.

doc/integration/omniauth.md

@@ -26,7 +26,7 @@ GitLab supports the following OmniAuth providers.
 | [Auth0](auth0.md)                                                   | `auth0`                    |
 | [Authentiq](../administration/auth/authentiq.md)                    | `authentiq`                |
 | [AWS Cognito](../administration/auth/cognito.md)                    | `cognito`                  |
-| [Azure v2](azure.md#microsoft-azure-oauth-20-omniauth-provider-v2) | `azure_activedirectory_v2` |
+| [Azure v2](azure.md)                                                | `azure_activedirectory_v2` |
 | [Azure v1](azure.md)                                                | `azure_oauth2`             |
 | [Bitbucket Cloud](bitbucket.md)                                     | `bitbucket`                |
 | [CAS](cas.md)                                                       | `cas3`                     |
@@ -326,7 +326,7 @@ configuration to redirect login requests to your OmniAuth provider for
 authentication. This removes the need to select the provider before signing in.
 
 For example, to enable automatic sign-in for the
-[Azure v2 integration](azure.md#microsoft-azure-oauth-20-omniauth-provider-v2):
+[Azure v2 integration](azure.md):
 
 - **For Omnibus package**