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
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
---
stage: Manage
group: Authentication and Authorization
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
---
# Use GitHub as an authentication provider **(FREE SELF)**
You can integrate your GitLab instance with GitHub.com and GitHub Enterprise.
You can import projects from GitHub, or sign in to GitLab
with your GitHub credentials.
## Create an OAuth app in GitHub
To enable the GitHub OmniAuth provider, you need an OAuth 2.0 client ID and client
secret from GitHub:
1. Sign in to GitHub.
1. [Create an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app)
and provide the following information:
- The URL of your GitLab instance, such as `https://gitlab.example.com`.
- The authorization callback URL, such as, `https://gitlab.example.com/users/auth`.
Include the port number if your GitLab instance uses a non-default port.
### Check for security vulnerabilities
For some integrations, the [OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/)
vulnerability can compromise GitLab accounts.
To mitigate this vulnerability, append `/users/auth` to the authorization
callback URL.
However, as far as we know, GitHub does not validate the subdomain part of the `redirect_uri`.
Therefore, a subdomain takeover, an XSS, or an open redirect on any subdomain of
your website could enable the covert redirect attack.
## Enable GitHub OAuth in GitLab
1. [Configure the initial settings](omniauth.md#configure-initial-settings) in GitLab.
1. Edit the GitLab configuration file using the following information:
| GitHub setting | Value in the GitLab configuration file | Description |
|----------------|----------------------------------------|-------------------------|
| Client ID | `YOUR_APP_ID` | OAuth 2.0 client ID |
| Client secret | `YOUR_APP_SECRET` | OAuth 2.0 client secret |
| URL | `https://github.example.com/` | GitHub deployment URL |
- **For Omnibus installations**
1. Open the `/etc/gitlab/gitlab.rb` file.
For GitHub.com, update the following section:
```ruby
gitlab_rails['omniauth_providers'] = [
{
name: "github",
# label: "Provider name", # optional label for login button, defaults to "GitHub"
app_id: "YOUR_APP_ID",
app_secret: "YOUR_APP_SECRET",
args: { scope: "user:email" }
}
]
```
For GitHub Enterprise, update the following section and replace
`https://github.example.com/` with your GitHub URL:
```ruby
gitlab_rails['omniauth_providers'] = [
{
name: "github",
# label: "Provider name", # optional label for login button, defaults to "GitHub"
app_id: "YOUR_APP_ID",
app_secret: "YOUR_APP_SECRET",
url: "https://github.example.com/",
args: { scope: "user:email" }
}
]
```
1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure)
GitLab.
- **For installations from source**
1. Open the `config/gitlab.yml` file.
For GitHub.com, update the following section:
```yaml
- { name: 'github',
# label: 'Provider name', # optional label for login button, defaults to "GitHub"
app_id: 'YOUR_APP_ID',
app_secret: 'YOUR_APP_SECRET',
args: { scope: 'user:email' } }
```
For GitHub Enterprise, update the following section and replace
`https://github.example.com/` with your GitHub URL:
```yaml
- { name: 'github',
# label: 'Provider name', # optional label for login button, defaults to "GitHub"
app_id: 'YOUR_APP_ID',
app_secret: 'YOUR_APP_SECRET',
url: "https://github.example.com/",
args: { scope: 'user:email' } }
```
1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source)
GitLab.
1. Refresh the GitLab sign-in page. A GitHub icon should display below the
sign-in form.
1. Select the icon. Sign in to GitHub and authorize the GitLab application.
## Troubleshooting
### Imports from GitHub Enterprise with a self-signed certificate fail
When you import projects from GitHub Enterprise using a self-signed
certificate, the imports fail.
To fix this issue, you must disable SSL verification:
1. Set `verify_ssl` to `false` in the configuration file.
- **For Omnibus installations**
```ruby
gitlab_rails['omniauth_providers'] = [
{
name: "github",
# label: "Provider name", # optional label for login button, defaults to "GitHub"
app_id: "YOUR_APP_ID",
app_secret: "YOUR_APP_SECRET",
url: "https://github.example.com/",
verify_ssl: false,
args: { scope: "user:email" }
}
]
```
- **For installations from source**
```yaml
- { name: 'github',
# label: 'Provider name', # optional label for login button, defaults to "GitHub"
app_id: 'YOUR_APP_ID',
app_secret: 'YOUR_APP_SECRET',
url: "https://github.example.com/",
verify_ssl: false,
args: { scope: 'user:email' } }
```
1. Change the global Git `sslVerify` option to `false` on the GitLab server.
- **For Omnibus installations in [GitLab 15.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6800) and later**:
```ruby
gitaly['gitconfig'] = [
{key: "http.sslVerify", value: "false"},
]
```
- **For Omnibus installations in GitLab 15.2 and earlier (legacy method)**:
```ruby
omnibus_gitconfig['system'] = { "http" => ["sslVerify = false"] }
```
- **For installations from source in [GitLab 15.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6800) and later**, edit the Gitaly configuration (`gitaly.toml`):
```toml
[[git.config]]
key = "http.sslVerify"
value = "false"
```
- **For installations from source in GitLab 15.2 and earlier (legacy method)**:
```shell
git config --global http.sslVerify false
```
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.
### Signing in using GitHub Enterprise returns a 500 error
This error can occur because of a network connectivity issue between your
GitLab instance and GitHub Enterprise.
To check for a connectivity issue:
1. Go to the [`production.log`](../administration/logs/index.md#productionlog)
on your GitLab server and look for the following error:
``` plaintext
Faraday::ConnectionFailed (execution expired)
```
1. [Start the rails console](../administration/operations/rails_console.md#starting-a-rails-console-session)
and run the following commands. Replace `<github_url>` with the URL of your
GitHub Enterprise instance:
```ruby
uri = URI.parse("https://<github_url>") # replace `GitHub-URL` with the real one here
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.verify_mode = 1
response = http.request(Net::HTTP::Get.new(uri.request_uri))
```
1. If a similar `execution expired` error is returned, this confirms the error is
caused by a connectivity issue. Make sure the GitLab server can reach
your GitHub Enterprise instance.
### Signing in using your GitHub account without a pre-existing GitLab account is not allowed
When you sign in to GitLab, you get the following error:
```plaintext
Signing in using your GitHub account without a pre-existing
GitLab account is not allowed. Create a GitLab account first,
and then connect it to your GitHub account
```
To fix this issue, you must activate GitHub sign-in in GitLab:
1. On the top bar, in the top right corner, select your avatar.
1. Select **Edit profile**.
1. On the left sidebar, select **Account**.
1. In the **Service sign-in** section, select **Connect to GitHub**.
|
