The other day, I was working on enabling SAML on my test GitHub Enterprise Server (GHES) instance using Auth0 (one of many identity platforms out there). I wanted to create an administrators group so its members are automatically escalated to site administrators as soon as they authenticate with the SSO url.

This wasn’t straight forward, so here’s the outline of the steps you need to take in order to achieve that.

What is SAML?

SAML is quite popular in the enterprise world. It’s basically an open standard for exchanging encrypted authentication and authorization data between an identity provider (IdP) and a service provider (Sp). The most important feature is the fact that it addresses web-browser single sign-on (SSO). I’m not going to go deeper into discussing the details, here are some references to learn more about it:

• Wikipedia
• SAML Overview by F5 DevCenter

Setup

This guide assumes that you’ve already created an Auth0 account and you have an instance ready to go. The region of the instance does not matter much. You can sign-up here.

1. Create a new Application and enable SAML 2.0 addon in the Addons section by following this guide

    # Same configuration as provided in the reference in step #1
    {
      "audience": "https://<GITHUB_ENTERPRISE_SERVER_HOSTNAME_OR_IP>",
      "mappings": {
        "user_id": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
        "email": "emails",
        "name": "full_name"
      },
      "passthroughClaimsWithNoMapping": false,
      "mapIdentities": false,
      "signatureAlgorithm": "rsa-sha256",
      "digestAlgorithm": "sha256",
      "nameIdentifierProbes": [
        "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"
      ]
    }
   

   

2. Create a new test user in User Management > Users with the following attributes (you can change those to whatever you’d like):

    Username: Thanos
    Password: strong-secure-password
    Email: thanos@github.local
   

3. Create new roles (or just one) and make sure that one of those roles is: Administrators

4. Assign the Administrators role to the user we just created in step #2

   

Now, by default Auth0 does not map all the user attributes to the SAML assertions. In order to solve this problem and provide the administrator flag required by GHES (read more about it here) we need to intercept the authorization response before it goes back to GHES and inject that attribute.

For this, we use Auth0 Rules.

1. Create a new rule to check if the role Administrators is included in the roles array and add that to the SAML mappings
   • Create a new rule in Auth Pipeline > Rules with the following code (use this guide for further information):

    function (user, context, callback) {
      user.user_metadata = user.user_metadata || {};
      // Default the administrator flag to false we will use this flag
      // as the input to our SAML assertion attribute
      user.user_metadata.administrator = "false";
      // We need to make sure that the roles property is passed and that it is
      // an array
      if (Array.isArray(context.authorization.roles)) {
        // If the string 'Administrators' which is the name of the role
        // is included in the array then this user has the Administrator role assigned
        // to her
        if (context.authorization.roles.includes('Administrators')) {
          // Flip the flag to true. This will add the administrator
          // attribute to the SAML response
          user.user_metadata.administrator = "true";
          context.samlConfiguration.mappings = {
            "administrator": "user_metadata.administrator"
          };
        }
      }
      callback(null, user, context);
    }
   

   

2. Log in with that account in GHES and that particular user should be promoted to administrator post-login.

That’s it! Of course, this might not work the first time, so you will need to troubleshoot the requests/responses here are some tools that I found helpful:

1. SAML Chrome Panel - Chrome Extension
2. Auth0 Rules Debugging Guide

Disclaimer: The opinions shared are my own and do not represent my employers (current and former).