GitHub

Allows users to authenticate using their GitHub credentials by configuring GitHub as a federated identity provider via OAuth2.

Preparation

The following placeholders are used in this guide:

• authentik.company is the FQDN of the authentik installation.
• www.my.company is the Homepage URL for your site

GitHub configuration

To integrate GitHub with authentik, you need to create an OAuth application in GitHub Developer Settings.

1. Log in to GitHub and open the Developer Settings menu.

2. Create an OAuth app by clicking on the Register a new application button and set the following values:

   • Application Name: authentik
   • Homepage URL: www.my.company
   • Authorization callback URL: https://authentik.company/source/oauth/callback/github

3. Click Register Application

4. Click Generate a new client secret and take note of the Client Secret and Client ID. These values will be required in the next section.

authentik configuration

To support the integration of GitHub with authentik, you need to create a GitHub OAuth source in authentik.

1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to Directory > Federation and Social login, click Create, and then configure the following settings:
   • Select type: select GitHub OAuth Source as the source type.
   • Create GitHub OAuth Source: provide a name, a slug which must match the slug used in the GitHub Authorization callback URL field (e.g. github), and set the following required configurations:
     • Protocol settings
       • Consumer Key: <client_ID>
       • Consumer Secret: <client_secret>
       • Scopes (optional): define any further access scopes.
3. Click Finish to save your settings.

:::info Display new source on login screen For instructions on how to display the new source on the authentik login page, refer to the Add sources to default login page documentation. :::

:::info Embed new source in flow :ak-enterprise For instructions on embedding the new source within a flow, such as an authorization flow, refer to the Source Stage documentation. :::

Optional additional configuration

Checking for membership of a GitHub Organization

:::info Ensure that the GitHub OAuth source in Federation & Social login has the additional read:org scope added under Protocol settings > Scopes. :::

To check if the user is a member of an organization, you can use the following policy on your flows.

1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to Customization > Policies.
3. Click Create, select Expression Policy and then Next.
4. Provide a name for the policy and set the following expression:

from authentik.sources.oauth.models import OAuthSource

# Set this value
accepted_org = "your_organization"

# Ensure flow is only run during OAuth logins via GitHub
if not isinstance(context['source'], OAuthSource) or context["source"].provider_type != "github":
    return True

# Get the user-source connection object from the context, and get the access token
connection = context["goauthentik.io/sources/connection"]
access_token = connection.access_token

# We also access the user info authentik already retrieved, to get the correct username
github_username = context["oauth_userinfo"]

# GitHub does not include organizations in the userinfo endpoint, so we have to call another URL
orgs_response = requests.get(
    "https://api.github.com/user/orgs",
    auth=(github_username["login"], access_token),
    headers={
        "accept": "application/vnd.github.v3+json"
    }
)
orgs_response.raise_for_status()
orgs = orgs_response.json()

# `orgs` will be formatted like this
# [
#     {
#         "login": "goauthentik",
#         [...]
#     }
# ]
user_matched = any(org['login'] == accepted_org for org in orgs)
if not user_matched:
    ak_message(f"User is not member of {accepted_org}.")
return user_matched

5. Click Finish. You can now bind this policy to the chosen enrollment and/or authentication flow of the GitHub OAuth source.
6. Navigate to Flows and Stages > Flows and click the name of the flow in question.
7. Open the Policy/Group/User Bindings tab and click Bind existing Policy/Group/User.
8. Select the policy that you previously created and click Create.
9. Optionally, repeat the process for any other flows that you want the policy applied to.

If a user is not a member of the chosen organization, they will see this message:

Source property mappings

Source property mappings allow you to modify or gather extra information from sources. See the overview for more information.

Resources