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
|
---
type: reference
stage: Manage
group: Access
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
---
# Google Workspace SSO provider
Google Workspace (formerly G Suite) is a [Single Sign-on provider](https://support.google.com/a/answer/60224?hl=en) that can be used to authenticate
with GitLab.
The following documentation enables Google Workspace as a SAML provider for GitLab.
## Configure the Google Workspace SAML app
The following guidance is based on this Google Workspace article, on how to [Set up your own custom SAML application](https://support.google.com/a/answer/6087519?hl=en):
Make sure you have access to a Google Workspace [Super Admin](https://support.google.com/a/answer/2405986#super_admin) account.
Follow the instructions in the linked Google Workspace article, where you'll need the following information:
| | Typical value | Description |
|------------------|--------------------------------------------------|----------------------------------------------------------|
| Name of SAML App | GitLab | Other names OK. |
| ACS URL | `https://<GITLAB_DOMAIN>/users/auth/saml/callback` | ACS is short for Assertion Consumer Service. |
| GITLAB_DOMAIN | `gitlab.example.com` | Set to the domain of your GitLab instance. |
| Entity ID | `https://gitlab.example.com` | A value unique to your SAML app, you'll set it to the `issuer` in your GitLab configuration. |
| Name ID format | EMAIL | Required value. Also known as `name_identifier_format` |
| Name ID | Primary email address | Make sure someone receives content sent to that address |
| First name | `first_name` | Required value to communicate with GitLab. |
| Last name | `last_name` | Required value to communicate with GitLab. |
You will also need to setup the following SAML attribute mappings:
| Google Directory attributes | App attributes |
|-----------------------------------|----------------|
| Basic information > Email | `email` |
| Basic Information > First name | `first_name` |
| Basic Information > Last name | `last_name` |
You may also use some of this information when you [Configure GitLab](#configure-gitlab).
When configuring the Google Workspace SAML app, be sure to record the following information:
| | Value | Description |
|-------------|--------------|-----------------------------------------------------------------------------------|
| SSO URL | Depends | Google Identity Provider details. Set to the GitLab `idp_sso_target_url` setting. |
| Certificate | Downloadable | Run `openssl x509 -in <your_certificate.crt> -noout -fingerprint` to generate the SHA1 fingerprint that can be used in the `idp_cert_fingerprint` setting. |
While the Google Workspace Admin provides IDP metadata, Entity ID and SHA-256 fingerprint,
GitLab does not need that information to connect to the Google Workspace SAML app.
---
Now that the Google Workspace SAML app is configured, it's time to enable it in GitLab.
## Configure GitLab
1. See [Initial OmniAuth Configuration](../integration/omniauth.md#initial-omniauth-configuration)
for initial settings.
1. To allow people to register for GitLab, through their Google accounts, add the following
values to your configuration:
**For Omnibus GitLab installations**
Edit `/etc/gitlab/gitlab.rb`:
```ruby
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_block_auto_created_users'] = false
```
---
**For installations from source**
Edit `config/gitlab.yml`:
```yaml
allow_single_sign_on: ["saml"]
block_auto_created_users: false
```
1. If an existing GitLab user has the same email address as a Google Workspace user, the registration
process automatically links their accounts, if you add the following setting:
their email addresses match by adding the following setting:
**For Omnibus GitLab installations**
Edit `/etc/gitlab/gitlab.rb`:
```ruby
gitlab_rails['omniauth_auto_link_saml_user'] = true
```
---
**For installations from source**
Edit `config/gitlab.yml`:
```yaml
auto_link_saml_user: true
```
1. Add the provider configuration.
For guidance on how to set up these values, see the [SAML General Setup steps](saml.md#general-setup).
Pay particular attention to the values for:
- `assertion_consumer_service_url`
- `idp_cert_fingerprint`
- `idp_sso_target_url`
- `issuer`
- `name_identifier_format`
**For Omnibus GitLab installations**
```ruby
gitlab_rails['omniauth_providers'] = [
{
name: 'saml',
args: {
assertion_consumer_service_url: 'https://<GITLAB_DOMAIN>/users/auth/saml/callback',
idp_cert_fingerprint: '00:00:00:00:00:00:0:00:00:00:00:00:00:00:00:00',
idp_sso_target_url: 'https://accounts.google.com/o/saml2/idp?idpid=00000000',
issuer: 'https://<GITLAB_DOMAIN>',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress'
},
label: 'Google Workspace' # optional label for SAML log in button, defaults to "Saml"
}
]
```
**For installations from source**
```yaml
- {
name: 'saml',
args: {
assertion_consumer_service_url: 'https://<GITLAB_DOMAIN>/users/auth/saml/callback',
idp_cert_fingerprint: '00:00:00:00:00:00:0:00:00:00:00:00:00:00:00:00',
idp_sso_target_url: 'https://accounts.google.com/o/saml2/idp?idpid=00000000',
issuer: 'https://<GITLAB_DOMAIN>',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress'
},
label: 'Google Workspace' # optional label for SAML log in button, defaults to "Saml"
}
```
1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for Omnibus and installations
from source respectively for the changes to take effect.
To avoid caching issues, test the result on an incognito or private browser window.
## Troubleshooting
The Google Workspace documentation on [SAML app error messages](https://support.google.com/a/answer/6301076?hl=en) is helpful for debugging if you are seeing an error from Google while signing in.
Pay particular attention to the following 403 errors:
- `app_not_configured`
- `app_not_configured_for_user`
|
