diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md
index 9ca7e6e0a7ea50fa8f1679af512d358c804ac805..35cf496bbe96605798ca3b6be7a0fee4cd127a91 100644
--- a/doc/user/group/saml_sso/group_sync.md
+++ b/doc/user/group/saml_sso/group_sync.md
@@ -22,6 +22,59 @@ or that all groups are removed from GitLab to disable Group Sync.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For a demo of Group Sync using Azure, see [Demo: SAML Group Sync](https://youtu.be/Iqvo2tJfXjg).
+## Configure SAML Group Links
+
+SAML Group Sync only manages a group if that group has one or more SAML group links.
+
+You must configure the SAML group links before you configure SAML Group Sync.
+
+When SAML is enabled, users with the Maintainer or Owner role see a new menu
+item in group **Settings > SAML Group Links**.
+
+- You can configure one or more **SAML Group Links** to map a SAML identity
+ provider group name to a GitLab role.
+- Members of the SAML identity provider group are added as members of the GitLab
+ group on their next SAML sign-in.
+- Group membership is evaluated each time a user signs in using SAML.
+- SAML Group Links can be configured for a top-level group or any subgroup.
+- If a SAML group link is created then removed, and there are:
+ - Other SAML group links configured, users that were in the removed group
+ link are automatically removed from the group during sync.
+ - No other SAML group links configured, users remain in the group during sync.
+ Those users must be manually removed from the group.
+
+Prerequisites:
+
+- Self-managed GitLab instances must have configured SAML Group Sync. GitLab.com
+ instances are already configured for SAML Group Sync, and require no extra configuration.
+
+To link the SAML groups:
+
+1. In **SAML Group Name**, enter the value of the relevant `saml:AttributeValue`. The value entered here must exactly match the value sent in the SAML response. For some IdPs, this may be a group ID or object ID (Azure AD) instead of a friendly group name.
+1. Choose the role in **Access Level**.
+1. Select **Save**.
+1. Repeat to add additional group links if required.
+
+
+
+If a user is a member of multiple SAML groups mapped to the same GitLab group,
+the user gets the highest role from the groups. For example, if one group
+is linked as Guest and another Maintainer, a user in both groups gets the Maintainer
+role.
+
+Users granted:
+
+- A higher role with Group Sync are displayed as having
+ [direct membership](../../project/members/index.md#display-direct-members) of the group.
+- A lower or the same role with Group Sync are displayed as having
+ [inherited membership](../../project/members/index.md#display-inherited-members) of the group.
+
+### Use the API
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3.
+
+You can use the GitLab API to [list, add, and delete](../../../api/groups.md#saml-group-links) SAML group links.
+
## Configure SAML Group Sync
NOTE:
@@ -31,7 +84,7 @@ WARNING:
To prevent users being accidentally removed from the GitLab group, follow these instructions closely before
enabling Group Sync in GitLab.
-To configure SAML Group Sync for self-managed GitLab instances:
+To configure SAML Group Sync for **self-managed GitLab instances**:
1. Configure the [SAML OmniAuth Provider](../../../integration/saml.md).
1. Ensure your SAML identity provider sends an attribute statement with the same name as the value of the `groups_attribute` setting. See the following attribute statement example for reference:
@@ -53,7 +106,7 @@ To configure SAML Group Sync for self-managed GitLab instances:
]
```
-To configure SAML Group Sync for GitLab.com instances:
+To configure SAML Group Sync for **GitLab.com instances**:
1. See [SAML SSO for GitLab.com groups](index.md).
1. Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups`.
@@ -78,56 +131,6 @@ For more information on configuring the
required group attribute name in the SAML identity provider's settings, see
example configurations for [Azure AD](../../../user/group/saml_sso/example_saml_config.md#group-sync) and [Okta](../../../user/group/saml_sso/example_saml_config.md#group-sync-1).
-## Configure SAML Group Links
-
-When SAML is enabled, users with the Maintainer or Owner role see a new menu
-item in group **Settings > SAML Group Links**.
-
-- You can configure one or more **SAML Group Links** to map a SAML identity
- provider group name to a GitLab role.
-- Members of the SAML identity provider group are added as members of the GitLab
- group on their next SAML sign-in.
-- Group membership is evaluated each time a user signs in using SAML.
-- SAML Group Links can be configured for a top-level group or any subgroup.
-- SAML Group Sync only manages a group if that group has one or more SAML group
- links. If a SAML group link is created then removed, and there are:
- - Other SAML group links configured, users that were in the removed group
- link are automatically removed from the group during sync.
- - No other SAML group links configured, users remain in the group during sync.
- Those users must be manually removed from the group.
-
-Prerequisites:
-
-- Self-managed GitLab instances must have configured SAML Group Sync. GitLab.com
- instances are already configured for SAML Group Sync, and require no extra configuration.
-
-To link the SAML groups:
-
-1. In **SAML Group Name**, enter the value of the relevant `saml:AttributeValue`. The value entered here must exactly match the value sent in the SAML response. For some IdPs, this may be a group ID or object ID (Azure AD) instead of a friendly group name.
-1. Choose the role in **Access Level**.
-1. Select **Save**.
-1. Repeat to add additional group links if required.
-
-
-
-If a user is a member of multiple SAML groups mapped to the same GitLab group,
-the user gets the highest role from the groups. For example, if one group
-is linked as Guest and another Maintainer, a user in both groups gets the Maintainer
-role.
-
-Users granted:
-
-- A higher role with Group Sync are displayed as having
- [direct membership](../../project/members/index.md#display-direct-members) of the group.
-- A lower or the same role with Group Sync are displayed as having
- [inherited membership](../../project/members/index.md#display-inherited-members) of the group.
-
-### Use the API
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3.
-
-You can use the GitLab API to [list, add, and delete](../../../api/groups.md#saml-group-links) SAML group links.
-
## Microsoft Azure Active Directory integration
> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10507) in GitLab 16.3.