|
| 1 | +--- |
| 2 | +title: 'Migrating from LDAP to SAML with SCIM' |
| 3 | +shortTitle: 'Migrate from LDAP' |
| 4 | +intro: 'Learn how to migrate your {% data variables.product.prodname_ghe_server %} instance from LDAP authentication to SAML single sign-on with SCIM provisioning for centralized user management.' |
| 5 | +permissions: 'Site administrators can migrate authentication methods on {% data variables.product.prodname_ghe_server %}.' |
| 6 | +versions: |
| 7 | + ghes: '>=3.17' |
| 8 | +type: how_to |
| 9 | +topics: |
| 10 | + - Accounts |
| 11 | + - Authentication |
| 12 | + - Enterprise |
| 13 | + - Identity |
| 14 | + - SSO |
| 15 | +--- |
| 16 | + |
| 17 | +## About migrating from LDAP to SAML and SCIM |
| 18 | + |
| 19 | +If your {% data variables.product.prodname_ghe_server %} instance currently uses LDAP authentication, you can migrate to SAML single sign-on (SSO) with SCIM provisioning for enhanced user lifecycle management capabilities. This migration allows you to automatically provision, update, and deprovision user accounts from your identity provider (IdP). |
| 20 | + |
| 21 | +{% data reusables.enterprise.saml-or-ldap %} |
| 22 | + |
| 23 | +**Prerequisites:** |
| 24 | + |
| 25 | +* You must be a site administrator on {% data variables.product.prodname_ghe_server %}. |
| 26 | +* You must have administrative access to your SAML identity provider. |
| 27 | +* Your IdP must support SAML 2.0 and SCIM 2.0 protocols. |
| 28 | +* You should complete a backup of your instance before beginning the migration. |
| 29 | + |
| 30 | +SCIM provisioning requires SAML authentication as a prerequisite, so this migration involves four distinct phases: |
| 31 | + |
| 32 | +1. **Migrate to SAML authentication**: Replace LDAP with SAML SSO. |
| 33 | +1. **Test and verify SAML**: Confirm authentication works and users link correctly. |
| 34 | +1. **Enable SCIM provisioning**: Add automated user management capabilities. |
| 35 | +1. **Test and verify SCIM**: Confirm provisioning links identities to existing accounts. |
| 36 | + |
| 37 | +This document assumes familiarity with SAML authentication and SCIM provisioning. For more information on these topics, please see [AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise) and [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes). |
| 38 | + |
| 39 | +## 1. Understand LDAP vs SCIM user creation patterns |
| 40 | + |
| 41 | +Before you begin the migration, it's important to understand the key differences between how LDAP and SCIM handle user management on {% data variables.product.prodname_ghe_server %}. |
| 42 | + |
| 43 | +| Attribute | LDAP | SCIM | |
| 44 | +| --- | --- | --- | |
| 45 | +| **Appliance configuration** | You configure the user ID attribute (default `uid`) and other LDAP settings in the management console. This configuration determines how to map between LDAP users and GitHub users. For more information about configuring LDAP, see [AUTOTITLE](/admin/managing-iam/using-ldap-for-enterprise-iam/using-ldap#ldap-attributes). | Enable SAML authentication first, then configure SCIM provisioning with an authentication token. | |
| 46 | +| **User creation timing** | Just-in-time: Users are created on first sign-in after successful LDAP authentication. | Pre-authentication: Users must be provisioned via SCIM before they can authenticate. | |
| 47 | +| **Initial username source** | GitHub username is based on the normalized LDAP identifier configured during setup. | GitHub username is based on the normalized SCIM `userName` value from your IdP. | |
| 48 | +| **Username management** | Flexible: Administrators can change GitHub usernames independently of LDAP. Usernames can drift from LDAP identifiers over time while maintaining authentication through LDAP mappings. See [AUTOTITLE](/account-and-profile/reference/username-reference#changing-your-username). | Strict: GitHub usernames always correspond to the normalized SCIM `userName` from your IdP. Username changes on the GitHub side are not allowed. | |
| 49 | +| **User attribute control** | Hybrid: Some attributes managed by LDAP, others can be managed on the appliance. | Full IdP control: All user attributes are managed through SCIM updates from your IdP. | |
| 50 | +| **Authentication flow** | {% data variables.product.prodname_ghe_server %} authenticates with your LDAP server and looks up the existing LDAP mapping to locate the user. | During SAML SSO, an external identity lookup is performed to locate the provisioned user for authentication. | |
| 51 | +| **Key characteristic** | Hybrid system where GitHub user data (especially usernames) can be partially managed on the appliance independently of the LDAP server. | Full identity provider control: The state of GitHub users depends entirely on what the IdP sends through SCIM, and usernames cannot drift from the source system. | |
| 52 | + |
| 53 | +### Username normalization and compatibility |
| 54 | + |
| 55 | +{% data variables.product.prodname_ghe_server %} normalizes usernames according to specific rules that apply consistently across LDAP, SAML, and SCIM. Understanding these rules is critical for successful migration. |
| 56 | + |
| 57 | +For more information about username normalization, see [AUTOTITLE](/admin/managing-iam/iam-configuration-reference/username-considerations-for-external-authentication#about-username-normalization). |
| 58 | + |
| 59 | +## 2. Plan your migration |
| 60 | + |
| 61 | +Before beginning the migration, you need to understand your current setup, prepare your identity provider, and establish backup access methods. The planning phase is critical to ensure a smooth transition. |
| 62 | + |
| 63 | +### Preparing to map from LDAP to SCIM |
| 64 | + |
| 65 | +The critical migration challenge is bridging between the LDAP and SCIM user management approaches: |
| 66 | + |
| 67 | +**LDAP users (existing state)**: |
| 68 | + |
| 69 | +* Have GitHub usernames that may have changed since initial creation |
| 70 | +* Retain authentication ability through LDAP mappings regardless of username changes |
| 71 | + |
| 72 | +**SCIM users (target state)**: |
| 73 | + |
| 74 | +* Must be provisioned before authentication |
| 75 | +* Must have GitHub usernames that match their normalized SCIM `userName` values |
| 76 | +* Can be linked to an external identity with their existing GitHub account during SCIM user provisioning, but only if the normalized SCIM `userName` matches their existing GitHub username |
| 77 | + |
| 78 | +### Migration mapping requirements |
| 79 | + |
| 80 | +To successfully link SCIM identities to existing LDAP users, you'll need to capture the current state of the users on your instance: |
| 81 | + |
| 82 | +1. **Export existing GitHub usernames**: Use the site admin interface, API, or CLI to get a complete list of current GitHub usernames on your instance. For more information about the users API, see [AUTOTITLE](/rest/users/users?apiVersion=2022-11-28#list-users). For more information about the command-line utility to export users, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-user-csv). |
| 83 | +1. **Map GitHub usernames to real users in your IdP**: Determine which identities correspond to each GitHub username in your enterprise. |
| 84 | +1. **Configure the SCIM `userName` attribute**: Ensure your IdP provisions SCIM users with `userName` values that match the existing GitHub usernames you would like to link. |
| 85 | + |
| 86 | +**Important**: The target for mapping is always the **current GitHub username** on your instance, not the original LDAP User ID or any other identifier. |
| 87 | + |
| 88 | +### Key planning considerations |
| 89 | + |
| 90 | +**Important considerations:** |
| 91 | + |
| 92 | +* **Downtime required**: This migration requires downtime during a maintenance window to change authentication settings. |
| 93 | +* **User impact**: After the migration, users will need to authenticate through your SAML IdP instead of LDAP credentials. |
| 94 | +* **Team membership**: LDAP team synchronization will be replaced by SCIM group provisioning if supported by your IdP. LDAP-mapped teams will need to be updated with an appropriate SCIM group where applicable. |
| 95 | + |
| 96 | +### Capture the state of your LDAP configuration |
| 97 | + |
| 98 | +Record your current LDAP setup to plan equivalent SAML/SCIM mappings: |
| 99 | + |
| 100 | +{% data reusables.enterprise_site_admin_settings.access-settings %} |
| 101 | +{% data reusables.enterprise_site_admin_settings.management-console %} |
| 102 | +{% data reusables.enterprise_management_console.authentication %} |
| 103 | +1. Document the following LDAP settings: |
| 104 | + * **Domain base** and restricted user groups |
| 105 | + * **User ID attribute** (this was used to create GitHub usernames) |
| 106 | + * **Profile name, email, and other attribute mappings** |
| 107 | + * **Administrators group configuration** |
| 108 | + * **Team synchronization settings** |
| 109 | +1. Ensure you have saved a list of existing users on your instance that you will be linking to a SCIM identity. |
| 110 | + |
| 111 | +## 3. Migrate to SAML and SCIM |
| 112 | + |
| 113 | +Once you've completed planning, you can begin migrating from LDAP to SAML authentication. This involves configuring SAML on both your identity provider and {% data variables.product.prodname_ghe_server %}, then carefully testing the configuration before proceeding to SCIM. |
| 114 | + |
| 115 | +**Important**: When configuring SAML, enable "Allow creation of accounts with built-in authentication" to reduce the number of steps required when enabling SCIM. |
| 116 | + |
| 117 | +### Enabling SAML authentication |
| 118 | + |
| 119 | +For detailed SAML configuration steps, see [AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). |
| 120 | + |
| 121 | +After enabling SAML, test the authentication system before proceeding to SCIM. With any IdP account assigned to the SAML application configured against your instance, verify that you are able to successfully perform an SSO login. |
| 122 | + |
| 123 | +**Do not proceed to SCIM until SAML authentication is working correctly.** |
| 124 | + |
| 125 | +### Enable SCIM provisioning |
| 126 | + |
| 127 | +After confirming SAML authentication works correctly, you can enable SCIM for automated user management. SCIM must be configured on both {% data variables.product.prodname_ghe_server %} and your identity provider. |
| 128 | + |
| 129 | +For detailed steps to enable SCIM, see [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users). |
| 130 | + |
| 131 | +#### Test SCIM provisioning |
| 132 | + |
| 133 | +Test SCIM provisioning to ensure the SCIM provisioned users are linked to existing user accounts correctly. |
| 134 | + |
| 135 | +For users who already have accounts from the LDAP/SAML migration: |
| 136 | + |
| 137 | +1. **Assign user to SCIM application** in your IdP. |
| 138 | +1. **Verify automatic linking**: Check that SCIM automatically links to the existing account: |
| 139 | + * Users retain same username and account data |
| 140 | + * No duplicate accounts are created |
| 141 | + * SCIM identity shows as linked in the enterprise settings, and site admin interfaces. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise#viewing-a-linked-identity). |
| 142 | +1. **Review audit logs**: Look for `external_identity.scim_api_success` and `external_identity.provision` events showing successful linking to existing users. |
| 143 | + |
| 144 | +For new users not previously in your instance: |
| 145 | + |
| 146 | +1. **Verify user creation**: Check that the user appears in {% data variables.product.prodname_ghe_server %} with correct attributes. |
| 147 | +1. **Test authentication**: Confirm the new user can authenticate via SAML. |
| 148 | +1. **Test attribute updates**: Update user information in IdP and confirm changes sync. |
| 149 | +1. **Test deprovisioning**: Remove user access and confirm they are suspended. |
| 150 | + |
| 151 | +### Roll out SCIM to all users |
| 152 | + |
| 153 | +For all remaining users who aren't yet provisioned via SCIM: |
| 154 | + |
| 155 | +1. **Gradually assign users** to the {% data variables.product.prodname_ghe_server %} application in your IdP. |
| 156 | +1. **Monitor linking process**: Watch for successful automatic linking based on username matching. |
| 157 | +1. **Track progress**: Use audit logs to monitor `external_identity` events for linking progress. |
| 158 | +1. **Address any conflicts**: Resolve username conflicts or mapping issues as they arise. |
| 159 | + |
| 160 | +## 4. Update team and organization membership |
| 161 | + |
| 162 | +After your migration, if you previously used LDAP group synchronization to control team memberships, you can replace those team mappings with SCIM groups. If reusing existing an team, you will need to remove all team members prior to linking an IdP group. |
| 163 | + |
| 164 | +For more information, see [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups). |
0 commit comments