diff options
Diffstat (limited to 'doc/integration/saml.md')
| -rw-r--r-- | doc/integration/saml.md | 161 |
1 files changed, 96 insertions, 65 deletions
diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 97384d8f6cf..9dce7269c86 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -1,11 +1,29 @@ +--- +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. @@ -580,13 +608,14 @@ Make sure the IdP provides a claim containing the user's email address, using cl If after signing in into your SAML server you are redirected back to the sign in page and no error is displayed, check your `production.log` file. It will most likely contain the message `Can't verify CSRF token authenticity`. This means that there is an error during -the SAML request, but this error never reaches GitLab due to the CSRF check. +the SAML request, but in GitLab 11.7 and earlier this error never reaches GitLab due to +the CSRF check. To bypass this you can add `skip_before_action :verify_authenticity_token` to the `omniauth_callbacks_controller.rb` file immediately after the `class` line and -comment out the `protect_from_forgery` line using a `#` then restart Unicorn. This -will allow the error to hit GitLab, where it can then be seen in the usual logs, -or as a flash message on the login screen. +comment out the `protect_from_forgery` line using a `#`. Restart Unicorn for this +change to take effect. This will allow the error to hit GitLab, where it can then +be seen in the usual logs, or as a flash message on the login screen. That file is located in `/opt/gitlab/embedded/service/gitlab-rails/app/controllers` for Omnibus installations and by default in `/home/git/gitlab/app/controllers` for @@ -613,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 |