1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
---
stage: Create
group: Ecosystem
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)**
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 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
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.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 terms may be listed as `Application ID` and `Application Secret`.
- If you need 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.
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 [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration)
for initial settings.
1. Add the provider configuration:
For Omnibus GitLab:
```ruby
gitlab_rails['omniauth_providers'] = [
{
"name" => "azure_oauth2",
"args" => {
"client_id" => "CLIENT ID",
"client_secret" => "CLIENT SECRET",
"tenant_id" => "TENANT ID",
}
}
]
```
For installations from source:
```yaml
- { name: 'azure_oauth2',
args: { client_id: "CLIENT ID",
client_secret: "CLIENT SECRET",
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"`.
1. Replace `CLIENT ID`, `CLIENT SECRET` and `TENANT ID` with the values you got above.
1. Save the configuration file.
1. Reconfigure or restart GitLab, depending on your installation method:
- *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).
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
In order to use v2 endpoints provided by Microsoft Azure Active Directory you must to configure it via Azure OAuth2 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.
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. 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
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:
- `email`
- `openid`
- `profile`
### 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 [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration)
for initial settings.
1. Add the provider configuration:
For Omnibus GitLab:
```ruby
gitlab_rails['omniauth_providers'] = [
{
"name" => "azure_activedirectory_v2",
"args" => {
"client_id" => "CLIENT ID",
"client_secret" => "CLIENT SECRET",
"tenant_id" => "TENANT ID",
}
}
]
```
For installations from source:
```yaml
- { name: 'azure_activedirectory_v2',
args: { client_id: "CLIENT ID",
client_secret: "CLIENT SECRET",
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`.
1. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID` with the values you got above.
1. Save the configuration file.
1. Reconfigure or restart GitLab, depending on your installation method:
- *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).
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.
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.
|
