Skip to content

G
gitlab-ce
Commit 239898e0 authored by Blair Lunceford's avatar Blair Lunceford Committed by Mike Jang
Browse files
Options

Docs: Improve SAML documentation

parent 0382457b
Hide whitespace changes
Inline Side-by-side
Showing with 92 additions and 63 deletions
doc/administration/auth/okta.md
View file @ 239898e0
......@@ -159,8 +159,7 @@ You might want to try this out on an incognito browser window.
>**Note:**
Make sure the groups exist and are assigned to the Okta app.
You can take a look of the [SAML documentation](../../integration/saml.md#marking-users-as-external-based-on-saml-groups) on external groups since
it works the same.
You can take a look of the [SAML documentation](../../integration/saml.md#saml-groups) on configuring groups.
<!-- ## Troubleshooting
......
doc/integration/saml.md
View file @ 239898e0
---
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/#designated-technical-writers
---
# SAML OmniAuth Provider **(CORE ONLY)**
Note that:
This page describes instance-wide SAML for self-managed GitLab instances. For SAML on GitLab.com, see [SAML SSO for GitLab.com groups](../user/group/saml_sso/index.md).
You should also reference the [OmniAuth documentation](omniauth.md) for general settings that apply to all OmniAuth providers.
- SAML OmniAuth Provider is for SAML on self-managed GitLab instances. For SAML on
GitLab.com, see [SAML SSO for GitLab.com Groups](../user/group/saml_sso/index.md).
- Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an
earlier version, you'll need to explicitly enable it.
## Common SAML Terms
| Term | Description |
|------|-------------|
| Identity Provider (IdP) | The service which manages your user identities such as ADFS, Okta, Onelogin, or Ping Identity. |
| Service Provider (SP) | SAML considers GitLab to be a service provider. |
| Assertion | A piece of information about a user's identity, such as their name or role. Also know as claims or attributes. |
| SSO | Single Sign-On. |
| Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. |
| Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". |
| Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. |
## General Setup
GitLab can be configured to act as a SAML 2.0 Service Provider (SP). This allows
GitLab to consume assertions from a SAML 2.0 Identity Provider (IdP) such as
......@@ -143,17 +161,10 @@ On the sign in page there should now be a SAML button below the regular sign in
Click the icon to begin the authentication process. If everything goes well the user
will be returned to GitLab and will be signed in.
## Marking Users as External based on SAML Groups
>**Note:**
This setting is only available on GitLab 8.7 and above.
## SAML Groups
SAML login includes support for automatically identifying whether a user should
be considered an [external](../user/permissions.md) user based on the user's group
membership in the SAML identity provider. This feature **does not** allow you to
automatically add users to GitLab [Groups](../user/group/index.md), it simply
allows you to mark users as External if they are members of certain groups in the
Identity Provider.
You can require users to be members of a certain group, or assign users `external`, `admin` or `auditor` roles based on group membership. This feature **does not** allow you to
automatically add users to GitLab [Groups](../user/group/index.md).
### Requirements
......@@ -164,74 +175,73 @@ with the regular SAML response. Here is an example:
```xml
<saml:AttributeStatement>
<saml:Attribute Name="Groups">
<saml:AttributeValue xsi:type="xs:string">SecurityGroup</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string">Designers</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string">Freelancers</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string">Admins</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string">Auditors</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
```
The name of the attribute can be anything you like, but it must contain the groups
to which a user belongs. In order to tell GitLab where to find these groups, you need
to add a `groups_attribute:` element to your SAML settings. You will also need to
tell GitLab which groups are external via the `external_groups:` element:
to add a `groups_attribute:` element to your SAML settings.
### Required groups **(STARTER ONLY)**
Your IdP passes Group Information to the SP (GitLab) in the SAML Response. You need to configure GitLab to identify:
- Where to look for the groups in the SAML response via the `groups_attribute` setting
- Which group membership is requisite to sign in via the `required_groups` setting
When `required_groups` is not set or it is empty, anyone with proper authentication
will be able to use the service.
Example:
```yaml
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
external_groups: ['Freelancers', 'Interns'],
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
} }
```
## Required groups **(STARTER ONLY)**
>**Note:**
This setting is only available on GitLab 10.2 EE and above.
This setting works like `External Groups` setting. Just like there, your IdP has to
pass Group Information to GitLab, you have to tell GitLab where to look or the
groups SAML response, and which group membership should be requisite for logging in.
When `required_groups` is not set or it is empty, anyone with proper authentication
will be able to use the service.
### External Groups **(STARTER ONLY)**
Example:
SAML login supports automatic identification on whether a user should be considered an [external](../user/permissions.md) user. This is based on the user's group membership in the SAML identity provider.
```yaml
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Managers', 'Admins'],
external_groups: ['Freelancers'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
} }
```
## Admin Groups **(STARTER ONLY)**
>**Note:**
This setting is only available on GitLab 8.8 EE and above.
### Admin Groups **(STARTER ONLY)**
This setting works very similarly to the `External Groups` setting. The requirements
are the same, your IdP needs to pass Group information to GitLab, you need to tell
GitLab where to look for the groups in the SAML response, and which group should be
considered `admin groups`.
The requirements are the same as the previous settings, your IdP needs to pass Group information to GitLab, you need to tell
GitLab where to look for the groups in the SAML response, and which group(s) should be
considered admin users.
```yaml
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
admin_groups: ['Managers', 'Admins'],
admin_groups: ['Admins'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
......@@ -241,18 +251,20 @@ considered `admin groups`.
} }
```
## Auditor Groups **(STARTER ONLY)**
### Auditor Groups **(STARTER ONLY)**
>**Note:**
This setting is only available on GitLab 11.4 EE and above.
This setting also follows the requirements documented for the `External Groups` setting. GitLab uses the Group information provided by your IdP to determine if a user should be assigned the `auditor` role.
The requirements are the same as the previous settings, your IdP needs to pass Group information to GitLab, you need to tell
GitLab where to look for the groups in the SAML response, and which group(s) should be
considered auditor users.
```yaml
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
auditor_groups: ['Auditors', 'Security'],
auditor_groups: ['Auditors'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
......@@ -265,7 +277,18 @@ This setting also follows the requirements documented for the `External Groups`
## Bypass two factor authentication
If you want some SAML authentication methods to count as 2FA on a per session basis, you can register them in the
`upstream_two_factor_authn_contexts` list:
`upstream_two_factor_authn_contexts` list.
In addition to the changes in GitLab, make sure that your IdP is returning the
`AuthnContext`. For example:
```xml
<saml:AuthnStatement>
<saml:AuthnContext>
<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:MediumStrongCertificateProtectedTransport</saml:AuthnContextClassRef>
</saml:AuthnContext>
</saml:AuthnStatement>
```
**For Omnibus installations:**
......@@ -324,18 +347,7 @@ If you want some SAML authentication methods to count as 2FA on a per session ba
}
```
1. Save the file and [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes ot take effect
In addition to the changes in GitLab, make sure that your Idp is returning the
`AuthnContext`. For example:
```xml
<saml:AuthnStatement>
<saml:AuthnContext>
<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:MediumStrongCertificateProtectedTransport</saml:AuthnContextClassRef>
</saml:AuthnContext>
</saml:AuthnStatement>
```
1. Save the file and [restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect
## Customization
......@@ -368,7 +380,6 @@ You may also bypass the auto signin feature by browsing to
### `attribute_statements`
>**Note:**
This setting is only available on GitLab 8.6 and above.
This setting should only be used to map attributes that are part of the
OmniAuth `info` hash schema.
......@@ -396,6 +407,21 @@ args: {
}
```
#### Setting a username
By default, the email in the SAML response will be used to automatically generate the user's GitLab username. If you'd like to set another attribute as the username, assign it to the `nickname` OmniAuth `info` hash attribute. For example, if you wanted to set the `username` attribute in your SAML Response to the username in GitLab, use the following setting:
```yaml
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
attribute_statements: { nickname: ['username'] }
}
```
### `allowed_clock_drift`
The clock of the Identity Provider may drift slightly ahead of your system clocks.
......@@ -557,10 +583,12 @@ Avoid user control of the following attributes:
These attributes define the SAML user. If users can change these attributes, they can impersonate others.
Refer to the documentation for your [SAML Identity Provider](../user/group/saml_sso/index.md#providers) for information on how to fix these attributes.
Refer to the documentation for your SAML Identity Provider for information on how to fix these attributes.
## Troubleshooting
You can find the base64-encoded SAML Response in the [`production_json.log`](../administration/logs.md#production_jsonlog).
### GitLab+SAML Testing Environments
If you need to troubleshoot, [a complete GitLab+SAML testing environment using Docker compose](https://gitlab.com/gitlab-com/support/toolbox/replication/tree/master/compose_files) is available.
......@@ -614,6 +642,8 @@ is not providing this information, all SAML requests will fail.
Make sure this information is provided.
Another issue that can result in this error is when the correct information is being sent by the IdP, but the attributes don't match the names in the OmniAuth `info` hash. In this case, you'll need to set `attribute_statements` in the SAML configuration to [map the attribute names in your SAML Response to the corresponding OmniAuth `info` hash names](#attribute_statements).
### Key validation error, Digest mismatch or Fingerprint mismatch
These errors all come from a similar place, the SAML certificate. SAML requests
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7