diff options
Diffstat (limited to 'doc/integration/azure.md')
| -rw-r--r-- | doc/integration/azure.md | 48 |
1 files changed, 28 insertions, 20 deletions
diff --git a/doc/integration/azure.md b/doc/integration/azure.md index dceb135ad89..47d80ab9a66 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -4,17 +4,19 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Microsoft Azure OAuth2 OmniAuth Provider **(FREE)** +# Microsoft Azure OAuth 2.0 OmniAuth Provider **(FREE)** 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 use v2 endpoints via OmniAuth, please follow [Microsoft Azure OAuth2 OmniAuth Provider v2 instructions](#microsoft-azure-oauth2-omniauth-provider-v2). +To use v2 endpoints via OmniAuth, please follow [Microsoft Azure OAuth 2.0 OmniAuth Provider v2 instructions](#microsoft-azure-oauth-20-omniauth-provider-v2). -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. +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). +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: @@ -23,9 +25,9 @@ As you go through the Microsoft procedure, keep the following in mind: - The redirect URI requires the URL of the Azure OAuth callback of your GitLab installation. For example, `https://gitlab.mycompany.com/users/auth/azure_oauth2/callback`. The type dropdown should be set to **Web**. -- The `client ID` and `client secret` are terms associated with OAuth 2. In some Microsoft documentation, +- 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 need to generate a new client secret, follow the Microsoft documentation +- 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. @@ -89,41 +91,46 @@ As you go through the Microsoft procedure, keep the following in mind: - *If you installed from source,* [restart GitLab](../administration/restart_gitlab.md#installations-from-source). -On the sign-in page, you should now see a Microsoft icon below the regular sign-in form. -Click 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. +On the sign-in page, you should now see a Microsoft icon below the regular +sign-in form. Click 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. 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. -## Microsoft Azure OAuth2 OmniAuth Provider v2 +## Microsoft Azure OAuth 2.0 OmniAuth Provider v2 -In order to use v2 endpoints provided by Microsoft Azure Active Directory you must to configure it via Azure OAuth2 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 OAuth2 OmniAuth provider, you must register your application with Azure. Azure generates a client ID and secret key for you to use. +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). +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. +- 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. In some Microsoft documentation, +- 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 need to generate a new client secret, follow the Microsoft documentation +- 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) -Once 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: +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` @@ -181,7 +188,8 @@ Once you have created an application, follow the [Microsoft Quickstart documenta The `scope` parameter is optional and can be added to `args`. Default `scope` is: `openid profile email`. -1. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID` with the values you got above. +1. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID` with the values you got + above. 1. Save the configuration file. |