Skip to content

G
gitlab-ce
Commit 8de1bc8a authored by Mike Jang's avatar Mike Jang
Browse files
Options

Merge branch '298853-saml-docs' into 'master' 

Deduplicate SAML docs information

See merge request gitlab-org/gitlab!56595
parents 960b6409 0d09c9fa
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 194 additions and 430 deletions
doc/administration/auth/README.md
View file @ 8de1bc8a
......@@ -23,13 +23,11 @@ providers:
- [GitHub](../../integration/github.md)
- [GitLab.com](../../integration/gitlab.md)
- [Google OAuth](../../integration/google.md)
- [Google Workspace SSO](../../integration/google_workspace_saml.md)
- [JWT](jwt.md)
- [Kerberos](../../integration/kerberos.md)
- [LDAP](ldap/index.md): Includes Active Directory, Apple Open Directory, Open LDAP,
and 389 Server.
- [Google Secure LDAP](ldap/google_secure_ldap.md)
- [Okta](okta.md)
- [Salesforce](../../integration/salesforce.md)
- [SAML](../../integration/saml.md)
- [SAML for GitLab.com groups](../../user/group/saml_sso/index.md) **(PREMIUM SAAS)**
......
doc/administration/auth/okta.md
View file @ 8de1bc8a
---
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
redirect_to: '../../integration/saml.md'
---
# Okta SSO provider
This document was moved to [another location](../../integration/saml.md).
Okta is a [Single Sign-on provider](https://www.okta.com/products/single-sign-on/) that can be used to authenticate
with GitLab.
The following documentation enables Okta as a SAML provider.
## Configure the Okta application
The following guidance is based on this Okta article, on adding a [SAML Application with an Okta Developer account](https://support.okta.com/help/s/article/Why-can-t-I-add-a-SAML-Application-with-an-Okta-Developer-account?language=en_US):
1. In the Okta admin section, make sure to select Classic UI view in the top left corner. From there, choose to **Add an App**.
1. When the app screen comes up you see another button to **Create an App** and
choose SAML 2.0 on the next screen.
1. Optionally you can add a logo
(you can choose it from <https://about.gitlab.com/press/>). You'll have to
crop and resize it.
1. Next, you'll need the to fill in the SAML general configuration. Here's an example (showing the required URLs and attribute mapping):
image.
![Okta admin panel view](img/okta_admin_panel_v13_9.png)
1. The last part of the configuration is the feedback section where you can
just say you're a customer and creating an app for internal use.
1. When you have your app you'll have a few tabs on the top of the app's
profile. Click on the SAML 2.0 configuration instructions button which should
look like the following:
![Okta SAML settings](img/okta_saml_settings.png)
1. On the screen that comes up take note of the
**Identity Provider Single Sign-On URL** which you'll use for the
`idp_sso_target_url` on your GitLab configuration file.
1. **Before you leave Okta make sure you add your user and groups if any.**
---
Now that the Okta 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 your users to use Okta to sign up without having to manually create
an account first, don't forget to 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. You can also automatically link Okta users with existing GitLab users if
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.
>**Notes:**
>
>- Change the value for `assertion_consumer_service_url` to match the HTTPS endpoint
> of GitLab (append `users/auth/saml/callback` to the HTTPS URL of your GitLab
> installation to generate the correct value).
>
>- To get the `idp_cert_fingerprint` fingerprint, first download the
> certificate from the Okta app you registered and then run:
> `openssl x509 -in okta.cert -noout -fingerprint`. Substitute `okta.cert`
> with the location of your certificate.
>
>- Change the value of `idp_sso_target_url`, with the value of the
> **Identity Provider Single Sign-On URL** from the step when you
> configured the Okta app.
>
>- Change the value of `issuer` to the value of the **Audience Restriction** from your Okta app configuration. This will identify GitLab
> to the IdP.
>
>- Leave `name_identifier_format` as-is.
**For Omnibus GitLab installations**
```ruby
gitlab_rails['omniauth_providers'] = [
{
name: 'saml',
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://gitlab.oktapreview.com/app/gitlabdev773716_gitlabsaml_1/exk8odl81tBrjpD4B0h7/sso/saml',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
},
label: 'Okta' # optional label for SAML login button, defaults to "Saml"
}
]
```
**For installations from source**
```yaml
- {
name: 'saml',
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://gitlab.oktapreview.com/app/gitlabdev773716_gitlabsaml_1/exk8odl81tBrjpD4B0h7/sso/saml',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
},
label: 'Okta' # optional label for SAML login button, defaults to "Saml"
}
```
1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../restart_gitlab.md#installations-from-source) GitLab for Omnibus and installations
from source respectively for the changes to take effect.
You might want to try this out on an incognito browser window.
## Configuring groups
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#saml-groups) on configuring groups.
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
<!-- This redirect file can be deleted after 2021-06-15>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
doc/administration/troubleshooting/group_saml_scim.md
View file @ 8de1bc8a
......@@ -20,6 +20,7 @@ They may then set up a test configuration of the desired identity provider. We i
This section includes relevant screenshots of the following example configurations of [Group SAML](../../user/group/saml_sso/index.md) and [Group SCIM](../../user/group/saml_sso/scim_setup.md):
- [Azure Active Directory](#azure-active-directory)
- [Okta](#okta)
- [OneLogin](#onelogin)
WARNING:
......@@ -59,6 +60,14 @@ IdP Links and Certificate:
![Okta Links and Certificate](img/Okta-linkscert.png)
Sign on settings:
![Okta SAML settings](img/okta_saml_settings.png)
Self-managed instance example:
![Okta admin panel view](img/okta_admin_panel_v13_9.png)
## OneLogin
Application details:
......
doc/integration/google_workspace_saml.md
View file @ 8de1bc8a
---
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
redirect_to: 'saml.md'
---
# Google Workspace SSO provider
This document was moved to [another location](saml.md).
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`
<!-- This redirect file can be deleted after 2021-06-15>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
doc/integration/saml.md
View file @ 8de1bc8a
This diff is collapsed.
doc/topics/authentication/index.md
View file @ 8de1bc8a
......@@ -35,7 +35,6 @@ This page gathers all the resources for the topic **Authentication** within GitL
- [SAML OmniAuth Provider](../../integration/saml.md)
- [SAML for GitLab.com Groups](../../user/group/saml_sso/index.md) **(PREMIUM SAAS)**
- [SCIM user provisioning for GitLab.com Groups](../../user/group/saml_sso/scim_setup.md) **(PREMIUM SAAS)**
- [Okta SSO provider](../../administration/auth/okta.md)
- [Kerberos integration (GitLab EE)](../../integration/kerberos.md) **(STARTER)**
## API
......
doc/user/group/saml_sso/index.md
View file @ 8de1bc8a
This diff is collapsed.
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