authentik/website/integrations/development/github-enterprise-server/index.md

title, sidebar_label, support_level

title	sidebar_label	support_level
Integrate with GitHub Enterprise Server	GitHub Enterprise Server	community

What is GitHub Enterprise Server

GitHub Enterprise Server is a self-hosted platform for software development within your enterprise. Your team can use GitHub Enterprise Server to build and ship software using Git version control, powerful APIs, productivity and collaboration tools, and integrations. Developers familiar with GitHub.com can onboard and contribute seamlessly using familiar features and workflows.

-- https://docs.github.com/en/enterprise-server@3.5/admin/overview/about-github-enterprise-server

Preparation

The following placeholders are used in this guide:

• https://github.company is your GitHub Enterprise Server installation
• authentik.company is the FQDN of the authentik installation.
• GitHub Users is an application entitlement used for standard GitHub Enterprise Server users.
• GitHub Admins is an application entitlement used for GitHub Enterprise Server administrators.

:::info This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application. :::

authentik configuration

To support the integration of GitHub Enterprise Server with authentik, you need to create an application/provider pair in authentik.

:::info In order to use GitHub Enterprise Server, SCIM must also be set up. :::

Create an application and provider in authentik

1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to Applications > Applications and click New Application to open the application wizard.

• Application: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings.
• Choose a Provider type: select SAML Provider as the provider type.
• Configure the Provider: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations.
  • Set the ACS URL to https://github.company/saml/consume.
  • Set the Audience and Issuer to https://github.company.
  • Set the Service Provider Binding to Post.
  • Under Advanced protocol settings, select an available Signing certificate. It is advised to download this certificate as it will be required later. It can be found under System > Certificates in the Admin Interface.
• Configure Bindings (optional): you can create a binding (policy, group, or user) to manage the listing and access to applications on a user's My applications page. If you add the SCIM provider as a backchannel provider later, only users who can view this application will be synchronized.

3. Click Submit to save the new application and provider.

Create the user and administrator entitlements

In the authentik Admin interface, open the GitHub Enterprise Server application that you just created, click the Application entitlements tab, and create two entitlements named GitHub Users and GitHub Admins.

After creating the entitlements, open each entitlement and bind the users or groups that should receive it.

SAML Configuration

If you plan to use SCIM (available from GHES 3.14.0), create a first administrator user on your instance and go to your personal access tokens at https://github.company/settings/tokens/new, click Generate new token, and then click Generate new token (classic). Your token should have a descriptive name and, ideally, no expiration date. For permission scopes, you need to select admin:enterprise. Click Generate token and store the resulting token in a safe location.

To enable SAML, navigate to your appliance maintenance settings. These are found at https://github.company:8443. Here, sign in with an administrator user and go to the Authentication section.

On this page:

• Select the SAML option.
• In Sign on URL, input your SSO URL (Redirect) from authentik.
• For Issuer, use the Audience you set in authentik.
• Verify that the Signature method and Digest method match your SAML provider settings in authentik.
• For Validation certificate, upload the signing certificate you downloaded after creating the provider.
• If you plan to enable SCIM, select Allow creation of accounts with built-in authentication and Disable administrator demotion/promotion options. These are selected so you can use your administrator user as an emergency non-SSO account, as well as create machine users, and to ensure users are not promoted outside your IdP.
• In the User attributes section, enter http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress in the Username field to ensure the emails become normalized into usernames in GitHub.
• Press Save settings on the left-hand side and wait for the changes to apply.

Once the appliance has saved the settings and reloaded the services, you should be able to navigate to your instance URL at https://github.company and sign in with SAML.

SCIM Configuration

This section only applies if you completed the steps above to prepare the instance for SCIM enablement.

After enabling SAML, log into your initial administrator account again. Click the user portrait in the top right, click Enterprise settings, click Settings in the left-hand sidebar, and then click Authentication security. On this page, check Enable SCIM configuration and press Save. After that, you should see a message reading SCIM Enabled.

Before we create a SCIM provider, we have to create a new Property Mapping. In authentik, go to Customization, then Property Mappings. Here, click Create, select SCIM Provider Mapping. Name the mapping something memorable and paste the following code in the Expression field:

entitlement_names = {
    entitlement.name
    for entitlement in request.user.app_entitlements(provider.application)
}

roles = []
# Edit this if statement if you need to add more GitHub roles.
# Valid roles include:
# user, guest_collaborator, enterprise_owner, billing_manager
if "GitHub Admins" in entitlement_names:
    roles.append({'value': 'enterprise_owner', 'primary': True})
elif "GitHub Users" in entitlement_names:
    roles.append({'value': 'user', 'primary': True})

return {
    "roles": roles,
}

If you renamed either entitlement, make sure that you update the code above to match.

Create a new SCIM provider with the following parameters:

• URL: https://github.company/api/v3/scim/v2
• Token: Paste the token you generated earlier here.
• In the Attribute mapping section, de-select the authentik default SCIM Mapping: User mapping from the User Property Mappings by selecting it on the right-hand side and clicking the left-facing single chevron.
• Select the property mapping you created in the previous step and add it by clicking the right-facing single chevron.
• Ensure that authentik default SCIM Mapping: Group is the only one active in the Group Property Mappings.
• Click Finish.

Go back to your GitHub Enterprise Server Application created in the first step and add your new SCIM provider in the Backchannel Providers field, then click the Update button.

You should now be ready to assign users or groups to your GitHub Users and GitHub Admins application entitlements. Use application bindings or policies to limit which users can view the application and are synchronized by SCIM, and use the entitlements to assign the corresponding GitHub SCIM role values. If you do not see your users being provisioned, go to your SCIM provider and click the Run sync again option. A few seconds later, you should see results of the SCIM sync.