Skip to main content

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 will need to create an OAuth application in the Discord Developer Portal.

  1. Log in to the 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 an 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 Facebook 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.
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.

Embed new source in flow 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 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:
# 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 Organisations 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
  1. Click Finish. You can now bind this policy to the chosen enrollment and/or authentication flow of the GitHub OAuth source.
  2. Navigate to Flows and Stages > Flows and click the name of the flow in question.
  3. Open the Policy/Group/User Bindings tab and click Bind existing Policy/Group/User.
  4. Select the policy that you previously created and click Create.
  5. Optionally, repeat the process for any other flows that you want the policy applied to.

If a user is not 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​