Commit 024ef91f authored by Suzanne Selhorn's avatar Suzanne Selhorn

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

CTRT edits for Azure page - part 1

See merge request gitlab-org/gitlab!81990
parents 36bcb2e2 d4d9a7ff
......@@ -4,102 +4,104 @@ 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 OAuth 2.0 OmniAuth Provider **(FREE SELF)**
# Use Microsoft Azure as an authentication provider **(FREE SELF)**
You can enable the Microsoft Azure OAuth 2.0 OmniAuth provider and sign in to
GitLab with your Microsoft Azure credentials. You can configure the provider that uses
[the earlier Azure Active Directory v1.0 endpoint](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-protocols-oauth-code),
or the provider that uses the v2.0 endpoint.
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 OAuth 2.0 OmniAuth Provider v2 instructions](#microsoft-azure-oauth-20-omniauth-provider-v2).
For new projects, Microsoft suggests you use the
[OpenID Connect protocol](../administration/auth/oidc.md#microsoft-azure),
which uses the Microsoft identity platform (v2.0) endpoint.
## Register 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.
an Azure application and get a client ID and secret key.
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).
1. Sign in to the [Azure portal](https://portal.azure.com).
1. If you have multiple Azure Active Directory tenants, switch to the desired tenant.
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`.
- The application type, which must be set to **Web**.
1. Save the client ID and client secret. The client secret is only
displayed once.
As you go through the Microsoft procedure, keep the following in mind:
If required, you can [create a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret).
- 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.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.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.
`client ID` and `client secret` are terms associated with OAuth 2.0.
In some Microsoft documentation, the terms are named `Application ID` and
`Application Secret`.
## Enable Microsoft OAuth in GitLab
1. On your GitLab server, open the configuration file.
For Omnibus GitLab:
- **For Omnibus installations**
```shell
sudo editor /etc/gitlab/gitlab.rb
```
```shell
sudo editor /etc/gitlab/gitlab.rb
```
For installations from source:
- **For installations from source**
```shell
cd /home/git/gitlab
```shell
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
```
sudo -u git -H editor config/gitlab.yml
```
1. Refer to [Configure initial settings](omniauth.md#configure-initial-settings)
for initial settings.
1. [Configure the initial settings](omniauth.md#configure-initial-settings).
1. Add the provider configuration:
1. Add the provider configuration. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID`
with the values you got when you registered the Azure application.
For Omnibus GitLab:
- **For Omnibus installations**
```ruby
gitlab_rails['omniauth_providers'] = [
{
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",
```ruby
gitlab_rails['omniauth_providers'] = [
{
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 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' } }
```
- **For installations from source**
The `base_azure_url` is optional and can be added for different locales;
such as `base_azure_url: "https://login.microsoftonline.de"`.
```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' } }
```
1. Replace `CLIENT ID`, `CLIENT SECRET` and `TENANT ID` with the values you got above.
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 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. 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.
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.
## Microsoft Azure OAuth 2.0 OmniAuth Provider v2
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment