Commit 562517d5 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'docs-repo-merge-10-group-misc' into 'master'

Docs: Merge EE doc/​user/group to CE

See merge request gitlab-org/gitlab-ce!27702
parents 23c195d2 5ddfa576
...@@ -15,7 +15,7 @@ templates are also available from this API endpoint. ...@@ -15,7 +15,7 @@ templates are also available from this API endpoint.
Support will be added for [Issue and Merge Request templates](../user/project/description_templates.md) Support will be added for [Issue and Merge Request templates](../user/project/description_templates.md)
in a future release. in a future release.
Support for [Group-level file templates](../user/group/index.md#group-level-file-templates-premium) Support for [Group-level file templates](../user/group/index.md#group-file-templates-premium)
**[PREMIUM]** was [added](https://gitlab.com/gitlab-org/gitlab-ee/issues/5987) **[PREMIUM]** was [added](https://gitlab.com/gitlab-org/gitlab-ee/issues/5987)
in GitLab 11.5 in GitLab 11.5
......
...@@ -111,7 +111,7 @@ The domain should have a wildcard DNS configured to the Ingress IP address. ...@@ -111,7 +111,7 @@ The domain should have a wildcard DNS configured to the Ingress IP address.
When adding more than one Kubernetes cluster to your project, you need to differentiate When adding more than one Kubernetes cluster to your project, you need to differentiate
them with an environment scope. The environment scope associates clusters with them with an environment scope. The environment scope associates clusters with
[environments](../../../ci/environments.md) similar to how the [environments](../../../ci/environments.md) similar to how the
[environment-specific variables](https://docs.gitlab.com/ee/ci/variables/README.html#limiting-environment-scopes-of-variables-premium) [environment-specific variables](https://docs.gitlab.com/ee/ci/variables/#limiting-environment-scopes-of-environment-variables-premium)
work. work.
While evaluating which environment matches the environment scope of a While evaluating which environment matches the environment scope of a
......
# Contribution Analytics **[STARTER]**
>**Note:**
Introduced in [GitLab Starter][ee] 8.3.
Track your team members' activity across your organization.
## Overview
With Contribution Analytics you can get an overview of the activity of
issues, merge requests, and push events of your organization and its members.
The analytics page is located at **Group > Contribution Analytics**
under the URL `/groups/<groupname>/analytics`.
## Use cases
- Analyze your team's contributions over a period of time and offer a bonus for the top contributors
- Identify opportunities for improvement with group members who may benefit from additional support
## Using Contribution Analytics
There are three main bar graphs that are deducted from the number of
contributions per group member. These contributions include push events, merge
requests and closed issues. Hovering on each bar you can see the number of
events for a specific member.
![Contribution analytics bar graphs](img/group_stats_graph.png)
## Changing the period time
There are three periods you can choose from, 'Last week', 'Last month' and
'Last three months'. The default is 'Last week'.
You can choose which period to display by using the dropdown calendar menu in
the upper right corner.
![Contribution analytics choose period](img/group_stats_cal.png)
## Sorting by different factors
Apart from the bar graphs you can also see the contributions per group member
which are depicted in a table that can be sorted by:
* Member name
* Number of pushed events
* Number of opened issues
* Number of closed issues
* Number of opened MRs
* Number of accepted MRs
* Number of total contributions
![Contribution analytics contributions table](img/group_stats_table.png)
[ee]: https://about.gitlab.com/pricing/
# Epics **[ULTIMATE]**
> Introduced in [GitLab Ultimate][ee] 10.2.
Epics let you manage your portfolio of projects more efficiently and with less
effort by tracking groups of issues that share a theme, across projects and
milestones.
![epics list view](img/epics_list_view.png)
## Use cases
- Suppose your team is working on a large feature that involves multiple discussions throughout different issues created in distinct projects within a [Group](../index.md). With Epics, you can track all the related activities that together contribute to that single feature.
- Track when the work for the group of issues is targeted to begin, and when it is targeted to end.
- Discuss and collaborate on feature ideas and scope at a high-level.
## Creating an epic
A paginated list of epics is available in each group from where you can create
a new epic. The list of epics includes also epics from all subgroups of the
selected group. From your group page:
1. Go to **Epics**
1. Click the **New epic** button at the top right
1. Enter a descriptive title and hit **Create epic**
Once created, you will be taken to the view for that newly-created epic where
you can change its title, description, start date, and due date.
![epic view](img/epic_view.png)
## Adding an issue to an epic
An epic contains a list of issues and an issue can be associated with at most
one epic. When on an epic, you can add its associated issues:
1. Click the plus icon (<kbd>+</kbd>) under the epic description.
1. Paste the link of the issue (you can hit <kbd>Spacebar</kbd> to add more than
one issues at a time).
1. Click **Add**.
Any issue belonging to a project in the epic's group or any of the epic's
subgroups are eligible to be added. To remove an issue from an epic, click
on the <kbd>x</kbd> button in the epic's issue list.
NOTE: **Note:**
When you add an issue or an epic to an epic that's already associated with another epic,
the issue or the epic is automatically removed from the previous epic.
## Multi-level child epics
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8333) in GitLab Ultimate 11.7.
Much like adding issues to an epic, an epic can have multiple child epics with
the maximum depth being 5. To add a child epic:
1. Click the plus icon (<kbd>+</kbd>) under the epic description.
1. Paste the link of the epic.
1. Click **Add**.
Any epic that belongs to a group or subgroup of the parent epic's group is
eligible to be added. To remove a child epic from a parent epic,
click on the <kbd>x</kbd> button in the parent epic's epic list.
## Start date and due date
For each of the dates in the sidebar of an epic, you can choose to either:
- Enter a fixed value.
- Inherit a dynamic value called "From milestones".
If you select "From milestones" for the start date, GitLab will automatically set the
date to be earliest start date across all milestones that are currently assigned
to the issues that are attached to the epic. Similarly, if you select "From milestones"
for the due date, GitLab will set it to be the latest due date across all
milestones that are currently assigned to those issues.
These are dynamic dates in that if milestones are re-assigned to the issues, if the
milestone dates change, or if issues are added or removed from the epic, then
the re-calculation will happen immediately to set a new dynamic date.
## Roadmap in epics
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.10.
If your epic contains one or more [child epics](#multi-level-child-epics) which
have a [start or due date](#start-date-and-due-date), then you can see a
[roadmap](../roadmap/index.md) view of the child epics under the parent epic itself.
![Child epics roadmap](img/child_epics_roadmap.png)
## Reordering issues and child epics
Drag and drop to reorder issues and child epics. New issues and child epics added to an epic appear at the top of the list.
## Deleting an epic
NOTE: **Note:**
To delete an epic, you need to be an [Owner][permissions] of a group/subgroup.
When inside a single epic view, click the **Delete** button to delete the epic.
A modal will pop-up to confirm your action.
Deleting an epic releases all existing issues from their associated epic in the
system.
## Closing and reopening epics
### Using buttons
Whenever you decide that there is no longer need for that epic,
close the epic using the close button:
![close epic - button](img/button_close_epic.png)
You can always reopen it using the reopen button.
![reopen epic - button](img/button_reopen_epic.png)
### Using quick actions
You can close or reopen an epic using [Quick actions](../../project/quick_actions.md)
## Navigating to an epic from an issue
If an issue belongs to an epic, you can navigate to the containing epic with the
link in the issue sidebar.
![containing epic](img/containing_epic.png)
## Promoting an issue to an epic
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6.
If you have [permissions](../../permissions.md) to close an issue and create an
epic in the parent group, you can promote an issue to an epic with the `/promote`
[quick action](../../project/quick_actions.md#quick-actions-for-epics-ultimate).
Only issues from projects that are in groups can be promoted.
When the quick action is executed:
- An epic is created in the same group as the project of the issue.
- Subscribers of the issue are notified that the epic was created.
The following issue metadata will be copied to the epic:
- Title, description, activity/comment thread.
- Upvotes/downvotes.
- Participants.
- Group labels that the issue already has.
## Searching for an epic from epics list page
> Introduced in [GitLab Ultimate][ee] 10.5.
You can search for an epic from the list of epics using filtered search bar (similar to
that of Issues and Merge requests) based on following parameters:
- Title or description
- Author name / username
- Labels
![epics search](img/epics_search.png)
To search, go to the list of epics and click on the field **Search or filter results...**.
It will display a dropdown menu, from which you can add an author. You can also enter plain
text to search by epic title or description. When done, press <kbd>Enter</kbd> on your
keyboard to filter the list.
You can also sort epics list by:
- **Created date**
- **Last updated**
- **Start date**
- **Due date**
Each option contains a button that can toggle the order between **ascending** and **descending**. The sort option and order will be persisted to be used wherever epics are browsed including the [roadmap](../roadmap/index.md).
![epics sort](img/epics_sort.png)
## Permissions
If you have access to view an epic and have access to view an issue already
added to that epic, then you can view the issue in the epic issue list.
If you have access to edit an epic and have access to edit an issue, then you
can add the issue to or remove it from the epic.
Note that for a given group, the visibility of all projects must be the same as
the group, or less restrictive. That means if you have access to a group's epic,
then you already have access to its projects' issues.
You may also consult the [group permissions table][permissions].
[ee]: https://about.gitlab.com/pricing/
[permissions]: ../../permissions.md#group-members-permissions
## Thread
- Comments: collaborate on that epic by posting comments in its thread.
These text fields also fully support
[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm).
## Comment, or start a discussion
Once you wrote your comment, you can either:
- Click "Comment" and your comment will be published.
- Click "Start discussion": start a thread within that epic's thread to discuss specific points.
## Award emoji
- You can [award an emoji](../../award_emojis.md) to that epic or its comments.
## Notifications
- [Receive notifications](../../../workflow/notifications.md) for epic events.
...@@ -5,10 +5,12 @@ and grant members access to several projects at once. ...@@ -5,10 +5,12 @@ and grant members access to several projects at once.
Groups can also be nested in [subgroups](subgroups/index.md). Groups can also be nested in [subgroups](subgroups/index.md).
Find your groups by expanding the left menu and clicking **Groups**: Find your groups by clicking **Groups** in the top navigation.
![GitLab Groups](img/groups.png) ![GitLab Groups](img/groups.png)
> The groups dropdown in the top navigation was [introduced][ce-36234] in [GitLab 11.1](https://about.gitlab.com/2018/07/22/gitlab-11-1-released/#groups-dropdown-in-navigation).
The Groups page displays all groups you are a member of, how many projects it holds, The Groups page displays all groups you are a member of, how many projects it holds,
how many members it has, the group visibility, and, if you have enough permissions, how many members it has, the group visibility, and, if you have enough permissions,
a link to the group settings. By clicking the last button you can leave that group. a link to the group settings. By clicking the last button you can leave that group.
...@@ -44,7 +46,7 @@ For example, consider a user named Alex: ...@@ -44,7 +46,7 @@ For example, consider a user named Alex:
1. Alex creates an account on GitLab.com with the username `alex`; 1. Alex creates an account on GitLab.com with the username `alex`;
their profile will be accessed under `https://gitlab.example.com/alex` their profile will be accessed under `https://gitlab.example.com/alex`
1. Alex creates a group for their team with the groupname `alex-team`; 1. Alex creates a group for their team with the group name `alex-team`;
the group and its projects will be accessed under `https://gitlab.example.com/alex-team` the group and its projects will be accessed under `https://gitlab.example.com/alex-team`
1. Alex creates a subgroup of `alex-team` with the subgroup name `marketing`; 1. Alex creates a subgroup of `alex-team` with the subgroup name `marketing`;
this subgroup and its projects will be accessed under `https://gitlab.example.com/alex-team/marketing` this subgroup and its projects will be accessed under `https://gitlab.example.com/alex-team/marketing`
...@@ -160,6 +162,10 @@ There are two different ways to add a new project to a group: ...@@ -160,6 +162,10 @@ There are two different ways to add a new project to a group:
### Default project creation level ### Default project creation level
> [Introduced][ee-2534] in [GitLab Premium][ee] 10.5.
> Brought to [GitLab Starter][ee] in 10.7.
> [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/25975) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.10.
Group owners or administrators can allow users with the Group owners or administrators can allow users with the
Developer role to create projects under groups. Developer role to create projects under groups.
...@@ -185,6 +191,32 @@ Alternatively, you can [lock the sharing with group feature](#share-with-group-l ...@@ -185,6 +191,32 @@ Alternatively, you can [lock the sharing with group feature](#share-with-group-l
In GitLab Enterprise Edition it is possible to manage GitLab group memberships using LDAP groups. In GitLab Enterprise Edition it is possible to manage GitLab group memberships using LDAP groups.
See [the GitLab Enterprise Edition documentation](../../integration/ldap.md) for more information. See [the GitLab Enterprise Edition documentation](../../integration/ldap.md) for more information.
## Epics **[ULTIMATE]**
> Introduced in [GitLab Ultimate][ee] 10.2.
Epics let you manage your portfolio of projects more efficiently and with less
effort by tracking groups of issues that share a theme, across projects and
milestones.
[Learn more about Epics.](epics/index.md)
## Group Security Dashboard **[ULTIMATE]**
Get an overview of the vulnerabilities of all the projects in a group and its subgroups.
[Learn more about the Group Security Dashboard.](security_dashboard/index.md)
## Insights **[ULTIMATE]**
> Introduced in [GitLab Ultimate][ee] 11.9 behind the `insights` feature flag.
Configure the Insights that matter for your groups or projects to explore data
such as triage hygiene, issues created/closed per a given period, average time
for merge requests to be merged and much more.
[Learn more about Insights](insights/index.md).
## Transferring groups ## Transferring groups
From GitLab 10.5, groups can be transferred in the following ways: From GitLab 10.5, groups can be transferred in the following ways:
...@@ -257,7 +289,7 @@ working together in a project. ...@@ -257,7 +289,7 @@ working together in a project.
To inherit the group membership, you share the project between the To inherit the group membership, you share the project between the
two groups A and B. **Share with group lock** prevents any project within two groups A and B. **Share with group lock** prevents any project within
the group from being shared with another group. By doing so, you the group from being shared with another group. By doing so, you
guarantee only the right group members have access to that projects. guarantee only the right group members have access to those projects.
To enable this feature, navigate to the group settings page. Select To enable this feature, navigate to the group settings page. Select
**Share with group lock** and **Save the group**. **Share with group lock** and **Save the group**.
...@@ -266,17 +298,50 @@ To enable this feature, navigate to the group settings page. Select ...@@ -266,17 +298,50 @@ To enable this feature, navigate to the group settings page. Select
#### Member Lock **[STARTER]** #### Member Lock **[STARTER]**
With **Member Lock** it is possible to lock membership in project to the With Member lock, it is possible to lock membership in a project to the
level of members in group. level of members in the group.
Member lock lets a group owner lock down any new project membership to all the
projects within the group, allowing tighter control over project membership.
Learn more about [Member Lock](https://docs.gitlab.com/ee/user/group/index.html#member-lock). For instance, if you want to lock the group for an [Audit Event](https://docs.gitlab.com/ee/administration/audit_events.html),
you enable Member lock to guarantee that membership of a project cannot be modified during that audit.
#### Group-level file templates **[PREMIUM]** To enable this feature:
Group-level file templates allow you to share a set of templates for common file 1. Navigate to the group's **Settings > General** page.
types with every project in a group. 1. Expand the **Permissions, LFS, 2FA** section and select **Member lock**.
1. Click the **Save changes** button.
Learn more about [Group-level file templates](https://docs.gitlab.com/ee/user/group/index.html#group-level-file-templates-premium). ![Checkbox for membership lock](img/member_lock.png)
This will disable the option for all users who previously had permissions to
operate project memberships so no new users can be added. Furthermore, any
request to add a new user to a project through API will not be possible.
#### Group file templates **[PREMIUM]**
Group file templates allow you to share a set of templates for common file
types with every project in a group. It is analogous to the
[instance template repository](https://docs.gitlab.com/ee/user/admin_area/settings/instance_template_repository.html)
feature, and the selected project should follow the same naming conventions as
are documented on that page.
Only projects that are in the group may be chosen as the source of templates.
This includes projects shared with the group, but **excludes** projects in
subgroups or parent groups of the group being configured.
This feature may be configured for subgroups as well as parent groups. A project
in a subgroup will have access to the templates for that subgroup, as well as
any parent groups.
![Group file template dropdown](img/group_file_template_dropdown.png)
To enable this feature, navigate to the group settings page, expand the
**Templates** section, choose a project to act as the template repository, and
**Save group**.
![Group file template settings](img/group_file_template_settings.png)
#### Group-level project templates **[PREMIUM]** #### Group-level project templates **[PREMIUM]**
...@@ -289,6 +354,19 @@ Define project templates at a group-level by setting a group as a template sourc ...@@ -289,6 +354,19 @@ Define project templates at a group-level by setting a group as a template sourc
access each project's settings, and remove any project from the same screen. access each project's settings, and remove any project from the same screen.
- **Webhooks**: configure [webhooks](../project/integrations/webhooks.md) to your group. - **Webhooks**: configure [webhooks](../project/integrations/webhooks.md) to your group.
- **Kubernetes cluster integration**: connect your GitLab group with [Kubernetes clusters](clusters/index.md). - **Kubernetes cluster integration**: connect your GitLab group with [Kubernetes clusters](clusters/index.md).
- **Audit Events**: view [Audit Events](https://docs.gitlab.com/ee/administration/audit_events.html#audit-events) - **Audit Events**: view [Audit Events](https://docs.gitlab.com/ee/administration/audit_events.html)
for the group. **[STARTER ONLY]** for the group. **[STARTER ONLY]**
- **Pipelines quota**: keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group. - **Pipelines quota**: keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group.
## User contribution analysis **[STARTER]**
With [GitLab Contribution Analytics](contribution_analytics/index.md)
you have an overview of the contributions (pushes, merge requests,
and issues) performed by your group members.
## Issues analytics **[PREMIUM]**
With [GitLab Issues Analytics](issues_analytics/index.md), in groups, you can see a bar chart of the number of issues created each month.
[ee]: https://about.gitlab.com/pricing/
[ee-2534]: https://gitlab.com/gitlab-org/gitlab-ee/issues/2534
# Insights **[ULTIMATE]**
> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9 behind the `insights` feature flag.
CAUTION: **Beta:**
Insights is considered beta, and is not ready for production use.
Follow [gitlab-org&725](https://gitlab.com/groups/gitlab-org/-/epics/725) for
updates.
Configure the Insights that matter for your groups to explore data such as
triage hygiene, issues created/closed per a given period, average time for merge
requests to be merged and much more.
![Insights example stacked bar chart](img/insights_example_stacked_bar_chart.png)
## Configure your Insights
Navigate to your group's **Settings > General**, expand **Insights**, and choose
the project that holds your `.gitlab/insights.yml` configuration file:
![group insights configuration](img/insights_group_configuration.png)
If no configuration was set, a [default configuration file](
https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/fixtures/insights/ee/fixtures/insights/default.yml)
will be used.
See the [Project's Insights documentation](https://docs.gitlab.com/ee/user/project/insights/index.html) for
more details about the `.gitlab/insights.yml` configuration file.
## Permissions
If you have access to view a group, then you have access to view their Insights.
NOTE: **Note:**
Issues or merge requests that you don't have access to (because you don't have
access to the project they belong to, or because they are confidential) are
filtered out of the Insights charts.
You may also consult the [group permissions table](../../permissions.md#group-members-permissions).
# Issues Analytics **[PREMIUM]**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5.
GitLab by default displays a bar chart of the number of issues created each month, for the
current month, and 12 months prior, for a total of 13 months.
You can change the total number of months displayed by setting a URL parameter.
For example, `https://gitlab.com/groups/gitlab-org/-/issues_analytics?months_back=15`
would show a total of 15 months for the chart in the GitLab.org group.
The **Search or filter results...** field can be used for filtering the issues by any attribute. For example, labels, assignee, milestone, and author.
To access the chart, navigate to a group's sidebar and select **Issues > Analytics**.
![Issues created per month](img/issues_created_per_month.png)
# Roadmap **[ULTIMATE]**
> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 10.5.
An Epic within a group containing **Start date** and/or **Due date**
can be visualized in a form of a timeline (e.g. a Gantt chart). The Epics Roadmap page
shows such a visualization for all the epics which are under a group and/or its subgroups.
![roadmap view](img/roadmap_view.png)
A dropdown allows you to show only open or closed epics. By default, all epics are shown.
![epics state dropdown](img/epics_state_dropdown.png)
Epics in the view can be sorted by:
- **Created date**
- **Last updated**
- **Start date**
- **Due date**
Each option contains a button that can toggle the order between **ascending** and **descending**. The sort option and order will be persisted to be used wherever epics are browsed including the [epics list view](../epics/index.md).
Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics).
## Timeline duration
Starting with [GitLab Ultimate][ee] 11.0, Roadmap supports three different date ranges; Quarters, Months (Default) and Weeks.
### Quarters
![roadmap date range in quarters](img/roadmap_timeline_quarters.png)
In _Quarters_ preset, roadmap shows epics which have start or due dates _falling within_ or
_going through_ **past quarter**, **current quarter** and **next 4 quarters**, where _today_
is shown by the vertical red line in the timeline. The sub-headers underneath the quarter name on
the timeline header represent the month of the quarter.
### Months
![roadmap date range in months](img/roadmap_timeline_months.png)
In _Months_ preset, roadmap shows epics which have start or due dates _falling within_ or
_going through_ **past month**, **current month** and **next 5 months**, where _today_
is shown by the vertical red line in the timeline. The sub-headers underneath the month name on
the timeline header represent the date on starting day (Sunday) of the week. This preset is
selected by default.
### Weeks
![roadmap date range in weeks](img/roadmap_timeline_weeks.png)
In _Weeks_ preset, roadmap shows epics which have start or due dates _falling within_ or
_going through_ **past week**, **current week** and **next 4 weeks**, where _today_
is shown by the vertical red line in the timeline. The sub-headers underneath the week name on
the timeline header represent the days of the week.
## Timeline bar for an epic
The timeline bar indicates the approximate position of an epic based on its start
and due date. If an epic doesn't have a due date, the timeline bar fades
away towards the future. Similarly, if an epic doesn't have a start date, the
timeline bar becomes more visible as it approaches the epic's due date on the
timeline.
# SAML SSO for GitLab.com Groups **[SILVER ONLY]**
> Introduced in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.0.
NOTE: **Note:**
This topic is for SAML on GitLab.com Silver tier and above. For SAML on self-managed GitLab instances, see [SAML OmniAuth Provider](../../../integration/saml.md).
Currently SAML on GitLab.com can be used to automatically add users to a group, and does not yet sign users into GitLab.com. Users should already have an account on the GitLab instance, or can create one when logging in for the first time.
User synchronization for GitLab.com is partially supported using [SCIM](scim_setup.md).
NOTE: **Note:**
SAML SSO for groups is used only as a convenient way to add users and does not sync users between providers without using SCIM. If a group is not using SCIM, group Owners will still need to manage user accounts, such as removing users when necessary.
## Configuring your Identity Provider
1. Navigate to the group and click **Settings > SAML SSO**.
1. Configure your SAML server using the **Assertion consumer service URL** and **Issuer**. See [your identity provider's documentation](#providers) for more details.
1. Configure the SAML response to include a NameID that uniquely identifies each user.
1. Configure required assertions using the [table below](#assertions).
1. Once the identity provider is set up, move on to [configuring GitLab](#configuring-gitlab).
![Issuer and callback for configuring SAML identity provider with GitLab.com](img/group_saml_configuration_information.png)
NOTE: **Note:**
Partial SSO enforcement was introduced in [11.8](https://gitlab.com/gitlab-org/gitlab-ee/issues/5291). With this option enabled, users must use your group's GitLab single sign on URL to be added to the group or be added via SCIM. Users can no longer be added manually. After a user has been added to the group, GitLab does not continue to enforce the use of SSO, but we'll [add a persistent check](https://gitlab.com/gitlab-org/gitlab-ee/issues/9255) in a later version.
### NameID
GitLab.com uses the SAML NameID to identify users. The NameID element:
- Is a required field in the SAML response.
- Must be unique to each user.
- Must be a persistent value that will never change, such as a unique ID or username. Email could also be used as the NameID, but only if it can be guaranteed to never change.
### Assertions
| Field | Supported keys | Notes |
|-|----------------|-------------|
| Email | `email`, `mail` | (required) |
| Full Name | `name` | |
| First Name | `first_name`, `firstname`, `firstName` | |
| Last Name | `last_name`, `lastname`, `lastName` | |
## Configuring GitLab
Once you've set up your identity provider to work with GitLab, you'll need to configure GitLab to use it for authentication:
1. Navigate to the group's **Settings > SAML SSO**.
1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign on URL** field.
1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field.
1. Check the **Enable SAML authentication for this group** checkbox.
1. Click the **Save changes** button.
![Group SAML Settings for GitLab.com](img/group_saml_settings.png)
## Providers
| Provider | Documentation |
|----------|---------------|
| ADFS (Active Directory Federation Services) | [Create a Relying Party Trust](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) |
| Azure | [Configuring single sign-on to applications](https://docs.microsoft.com/en-us/azure/active-directory/active-directory-saas-custom-apps) |
| Auth0 | [Auth0 as Identity Provider](https://auth0.com/docs/protocols/saml/saml-idp-generic) |
| G Suite | [Set up your own custom SAML application](https://support.google.com/a/answer/6087519?hl=en) |
| JumpCloud | [Single Sign On (SSO) with GitLab](https://support.jumpcloud.com/customer/en/portal/articles/2810701-single-sign-on-sso-with-gitlab) |
| Okta | [Setting up a SAML application in Okta](https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta) |
| OneLogin | [Use the OneLogin SAML Test Connector](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f) |
| Ping Identity | [Add and configure a new SAML application](https://docs.pingidentity.com/bundle/p1_enterpriseConfigSsoSaml_cas/page/enableAppWithoutURL.html) |
## Unlinking accounts
Users can unlink SAML for a group from their profile page. This can be helpful if:
- You no longer want a group to be able to sign you in to GitLab.com.
- Your SAML NameID has changed and so GitLab can no longer find your user.
For example, to unlink the `MyOrg` account, the following **Disconnect** button will be available under **Profile > Accounts**:
![Unlink Group SAML](img/unlink_group_saml.png)
## Glossary
| Term | Description |
|------|-------------|
| Identity Provider | The service which manages your user identities such as ADFS, Okta, Onelogin or Ping Identity. |
| Service Provider | 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. |
# SCIM provisioning using SAML SSO for Groups **[SILVER ONLY]**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10.
GitLab's [SCIM API](https://docs.gitlab.com/ee/api/scim.html) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644).
Currently, the following actions are available:
- CREATE
- UPDATE
- DELETE (deprovisioning)
The following identity providers are supported:
- Azure
## Requirements
- [Group SSO](index.md) needs to be configured.
- The `scim_group` feature flag must be enabled:
Run the following commands in a Rails console:
```sh
# Omnibus GitLab
gitlab-rails console
# Installation from source
cd /home/git/gitlab
sudo -u git -H bin/rails console RAILS_ENV=production
```
To enable SCIM for a group named `group_name`:
```ruby
group = Group.find_by_full_path('group_name')
Feature.enable(:group_scim, group)
```
### GitLab configuration
Once [Single sign-on](index.md) has been configured, we can:
1. Navigate to the group and click **Settings > SAML SSO**.
1. Click on the **Generate a SCIM token** button.
1. Save the token and URL so they can be used in the next step.
![SCIM token configuration](img/scim_token.png)
## SCIM IdP configuration
### Configuration on Azure
In the [Single sign-on](index.md) configuration for the group, make sure
that the **Name identifier value** (NameID) points to a unique identifier, such
as the `user.objectid`. This will match the `extern_uid` used on GitLab.
The GitLab app in Azure needs to be configured following
[Azure's SCIM setup](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#getting-started).
Note the following:
- The `Tenant URL` and `secret token` are the ones retrieved in the
[previous step](#gitlab-configuration).
- Should there be any problems with the availability of GitLab or similar
errors, the notification email set will get those.
- For mappings, we will only leave `Synchronize Azure Active Directory Users to AppName` enabled.
You can then test the connection clicking on `Test Connection`.
### Synchronize Azure Active Directory users
1. Click on `Synchronize Azure Active Directory Users to AppName`, to configure
the attribute mapping.
1. Select the unique identifier (in the example `objectId`) as the `id` and `externalId`,
and enable the `Create`, `Update`, and `Delete` actions.
1. Map the `userPricipalName` to `emails[type eq "work"].value` and `mailNickname` to
`userName`.
Example configuration:
![Azure's attribute mapping configuration](img/scim_attribute_mapping.png)
1. Click on **Show advanced options > Edit attribute list for AppName**.
1. Leave the `id` as the primary and only required field.
NOTE: **Note:**
`username` should neither be primary nor required as we don't support
that field on GitLab SCIM yet.
![Azure's attribute advanced configuration](img/scim_advanced.png)
1. Save all the screens and, in the **Provisioning** step, set
the `Provisioning Status` to `ON`.
NOTE: **Note:**
You can control what is actually synced by selecting the `Scope`. For example,
`Sync only assigned users and groups` will only sync the users assigned to
the application (`Users and groups`), otherwise it will sync the whole Active Directory.
Once enabled, the synchronization details and any errors will appear on the
bottom of the **Provisioning** screen, together with a link to the audit logs.
---
redirect_to: 'https://docs.gitlab.com/ee/user/application_security/security_dashboard/index.html'
---
This document was moved to [another location](https://docs.gitlab.com/ee/user/application_security/security_dashboard/index.html).
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