Learn Authentik - OAuth Sources (Social Login)

#Introduction

Throughout phases 3 and 5, Authentik acted as an Identity Provider — issuing tokens and assertions for applications. In episode 16, this role is reversed: Authentik becomes a Relying Party trusting other identity providers. The facility is called a source, and the most common case is OAuth sources — social login with GitHub, Google, or Discord.

What's the point? You still want Authentik to be the single entry point (single source of truth), but users don't need to register new accounts — they log in with the GitHub or Google account they already have. Authentik maps their profile, creates an internal user, and all Authentik-protected applications still use the Authentik session. Social login is just the entry door, not a replacement for Authentik.

Analogy: your building no longer issues its own ID cards. Instead, you accept the national ID (a Google/GitHub account) as proof, record it in an internal guest book, and grant access based on that record.

#The Source Concept

A source is a connection from an external identity provider to Authentik. Available types:

• OAuth source — Google, GitHub, Discord, GitLab, Microsoft, and generic OAuth2.
• SAML source — Authentik as an SP against another SAML IdP.
• LDAP source — synchronizing users from OpenLDAP/Active Directory (episode 17).
• Plex source — using a Plex account.

The focus of this episode: OAuth sources. The concept is always the same: register an OAuth application at the external provider to get a client_id and client_secret, then install them in Authentik.

#Creating an OAuth App at the External Provider

Take GitHub as an example. On GitHub, open Developer settings → OAuth Apps → New OAuth App, then fill in:

• Application name — the application name, for example Authentik.
• Homepage URL — the Authentik portal URL.
• Authorization callback URL — the callback address determined by Authentik:

OAuth source callback URL

https://authentik.example.com/source/oauth/callback/github/

Replace github with the source slug. Once registered, GitHub provides a Client ID and Client Secret — these two values are the connection credentials.

#Creating a Source in Authentik

In the Admin interface, open Directory → Federation and Social login → Create, choose the source type, then fill in:

• Name — the source's display name.
• Slug — the URL identifier; must match the slug in the GitHub callback URL.
• Consumer Key — the Client ID from the external provider.
• Consumer Secret — the Client Secret from the external provider.
• Scopes — additional scopes requested from the provider (optional).

For built-in provider types like GitHub, Google, and Discord, the authorization, token, and profile URLs are filled automatically by Authentik — you only enter the key and secret. For Generic OAuth2, you fill in the Authorization URL, Access Token URL, and Profile URL manually, or simply paste the OIDC well-known URL (.well-known/openid-configuration) if the provider supports it.

Once the source is saved, Authentik automatically creates the source's own authentication and enrollment flows, plus an application for that source.

#Binding a Source to Flows

This is the part that determines login behavior. Each source is bound to two flows:

• Authentication flow — run when a known user logs in via the source.
• Enrollment flow — run when a user is unknown — this is where a new internal account is created.

These flows work with user matching rules. Authentik provides these modes:

• identifier — matches based on the provider's unique identifier.
• email_link — a new user with an email matching an internal user is automatically connected (linked).
• email_deny — a new user whose email is already used by another user is denied.
• username_link / username_deny — same, but based on username.

Users created through a source are stored at the path goauthentik.io/sources/<slug> — you can see this on the user page, and distinguish internal users from source-created users.

#Mapping User Profiles

Profiles from external providers are mapped to internal users via property mappings. For GitHub, Authentik provides built-in mappings: the username is taken from the login field, the email from GitHub's email list, and the name from name.

For special needs, create a custom mapping. Example of a mapping that marks the user's origin:

OAuth source property mapping — user origin

return context["source"].slug

Context available in source expressions includes source (the source object), oauth_userinfo (the raw profile data from the provider), and token (the OAuth token). Always test the expression with the tester before using it.

#The Social Login Flow

Here's the complete flow when a user presses "Login with GitHub":

1. The user is directed to the flow page containing the source (for example on the authentication flow).
2. The browser is redirected to GitHub with the client ID and scopes.
3. GitHub asks the user to authorize, then returns an authorization code to the Authentik callback.
4. Authentik exchanges the code for an access token, fetches the user profile, and determines the identity.
5. The authentication or enrollment flow runs depending on whether the user is known.
6. The user enters the Authentik session and can open protected applications.

This whole process uses the flows you learned in phase 2 — the source is only the entry door; what follows is still controlled by Authentik stages and policies.

#Handling Existing Users

A common scenario: an organization already has internal users (for example budi@example.com), then adds social login. Without the right rules, the same user could create duplicate accounts.

The solution is the matching mode: choose email_link on the enrollment flow. When a user logs in with GitHub and their email matches the internal user budi@example.com, Authentik links that internal account with the source connection — not creates a new user. Once linked, subsequent logins via GitHub reuse the same account, complete with its groups and policies.

To check or fix connections, open the user page → the Synced users/sources tab and review the existing connections. If an identity conflict occurs (two users with the same email), decide the source of truth and fix it via the UI before enforcing a stricter matching mode.

#Closing

This episode used Authentik as a Relying Party through OAuth sources: understanding the source concept, creating an OAuth app at an external provider (GitHub/Google/Discord), installing the client ID and secret, binding the source to authentication and enrollment flows, mapping user profiles with property mappings, and handling existing users through matching modes.

The single entry point stays with Authentik — login sources are just an alternative proof of identity. In episode 17, we discuss another source equally important in the enterprise world: the LDAP source, which synchronizes users and groups from OpenLDAP or Active Directory into Authentik. See you there!