Enterprise SAML Identity Already Linked? Here’s What It Means 🔍

[github-staff]

A user is unable to accept an invitation to join a SAML-protected enterprise account as it reports that their SAML external identity is already linked to another account.

Symptoms

The invitation sent to a personal GitHub account to join a SAML-protected enterprise account fails and the user receives the following error:

There was an issue joining the enterprise: Your GitHub user account @USERNAME is currently unlinked. However, you are attempting to authenticate with your Identity Provider using the 'NAMEID' SAML identity which is already linked to a different GitHub user account in the organization. Please reach out to one of your GitHub organization owners for assistance.

🚨 If the error message starts with "There was an issue joining the organization" then the steps in this article do not apply, as this error message indicates organization-level, not enterprise-level, SAML has been configured.

What Can Cause This Behaviour

This issue can occur if a user has more than one account on GitHub.com.

When a user successfully SAML authenticates to an enterprise's /sso endpoint - usually in order to accept an invitation to join one of that enterprise's member organizations - we will bind their external ID (i.e. the NameId of their SAML account) to the personal GitHub account they are logged in as. If the same user were to later log in with a different GitHub account, and try to accept an invite to the same enterprise / organization, we will attempt to bind this second user account with the same external identity, but this does not work as only one user account can be bound to an identity at a time.

This linked identity can remain / exist even for accounts which are no longer enterprise members in certain circumstances.

Solution or Workaround

An enterprise owner can run the following GraphQL query to see linked SAML external identities in their enterprise:

{
  enterprise(slug: "ENTERPRISE_SLUG") {
    ownerInfo {
      samlIdentityProvider {
        externalIdentities(
          first: 5
          userName: "NAMEID"
        ) {
          edges {
            node {
              samlIdentity {
                idp_username: nameId
              }
              user {
                github_username: login
              }
            }
          }
        }
      }
    }
  }
}

Here's what that command would look like using curl:

curl -XPOST https://api.github.com/graphql -H 'authorization: bearer <TOKEN>' -d '{"query":"{enterprise(slug:\"ENTERPRISE_SLUG\"){ownerInfo{samlIdentityProvider{externalIdentities(first:5 userName:\"NAMEID\"){edges{node{samlIdentity{idp_username:nameId}user{github_username:login}}}}}}}}"}' --compressed

Replace ENTERPRISE_SLUG with your enterprise slug, and NAMEID with the external identity that is already linked.

You will need a personal access token with the admin:enterprise scope in order to execute the query. If using the curl method this would need to go in the place of <token>.

Then with the information the above query has returned do the following:

• Go https://github.com/enterprises/ENTERPRISE_SLUG/people/USERID/sso.
  • Replace ENTERPRISE_SLUG with the enterprise slug and USERID with the github_username value returned in the previous query.
• You should be able to see that there is a linked identity which matches the NAMEID value in the error the user was receiving when attempting to accept the invitation to join your enterprise.
• If this user is showing as Unaffiliated that means they are not an enterprise member, and you can click the Revoke button to remove this external identity from the enterprise.
  • If they show as anything else (e.g. an Organization member) then that means the external identity is linked to an existing enterprise member, so would need to be removed from the enterprise or overwrite their external identity with a different NameId.
• With the external identity revoked, please ask the user to attempt to accept the invitation again while logged into GitHub.com with the account they would like to use to join this organization.

Contact Support

If the above solution does not resolve the issue, please open a ticket at our Support page.

When doing so:

• Please open the ticket selecting the enterprise in question, while logged in as an enterprise owner.
• Provide a screenshot of the error the customer is receiving and the username of the account they are logged in as.
• List any previous changes made, and the full output of the GraphQL query listed above. 🔍