How authentik signs users into Forgejo or Gitea
The supported method for signing users into a self-hosted Git server with authentik is an OAuth2/OpenID Connect provider in authentik, and authentik publishes separate integration guides for Forgejo and Gitea. The work has three parts: registering authentik as an OpenID Connect authentication source in the Git server, mapping claims from authentik to admin and organization roles, and deciding how accounts that already exist locally will be linked to their central identity. Because Forgejo and Gitea are separate products with separate release lines, follow the guide that matches the server you run rather than adapting one to the other.
Start with the claim mapping, since it decides who becomes an administrator and who lands in which organization. Confirm the exact claim names, the group scopes requested from authentik, and the field names used for admin and organization mapping in the guide for your installed version, because these settings change between releases and are easy to get subtly wrong. Test the mapping with a few accounts from each group before opening sign-in to the whole user base. Also decide whether local password login stays enabled as a recovery path and who holds the local administrator account if authentik is unavailable.
Account linking is the step most likely to create duplicate users. Decide in advance whether existing local accounts should be matched to authentik users by a stable attribute such as the email address, or whether users will sign in once through the new source and claim their account. Inventory the local accounts, check for duplicate or unused entries, and confirm with the Forgejo or Gitea documentation for your version how linking behaves for an account that already exists. Plan a rollback for the first cutover, since moving a populated user table from local accounts to an external source is hard to undo cleanly.
What you need before configuring the Forgejo or Gitea SSO source
Four things have to be in place before you touch either side of the integration: a supported authentik release, a Forgejo or Gitea instance on a release line you have confirmed, a trusted HTTPS hostname for both systems, and an admin account on each. Each card below is a check you can complete before opening the authentik provider settings.
Supported authentik release
Run authentik on a release the security policy still covers. The policy lists 2026.5.x and 2026.8.x as the supported lines receiving security fixes, and the project announces security releases at least 24 hours in advance. Confirm the exact patch version on your server before you follow the OIDC steps, because provider fields and the discovery endpoint can change between releases. Plan your upgrade path if you are on an older line.
Confirmed Forgejo or Gitea release line
Identify the exact Forgejo or Gitea version you run and check it against the release pages before choosing a guide. Forgejo and Gitea publish different release lines, and Forgejo has an LTS line with a defined support window. Confirm that your version supports the OAuth2 authentication source settings you plan to use, and record the version so you can match the right documentation during later upgrades.
HTTPS hostnames with trusted certificates
Give authentik and Forgejo or Gitea each a stable HTTPS hostname. The browser redirect to authentik and the back-channel calls from the Forgejo or Gitea server both depend on these names, so the certificates must be trusted by the Forgejo or Gitea host itself, not only by users' browsers. If you use an internal certificate authority, install its root on the Forgejo or Gitea server and confirm the chain validates before you configure the source.
Admin accounts on both sides
You need an administrator in authentik who can create OAuth2/OpenID Connect providers and applications, and a site administrator in Forgejo or Gitea who can add authentication sources and edit user accounts. Keep the local Forgejo or Gitea admin password working and tested. If the SSO source misconfigures, that local login is your way back in to fix it.
Deployment footprint for authentik
The Docker Compose guide targets test setups and small-scale production and calls for at least 2 CPU cores and 2 GB of RAM. For production Kubernetes, the bundled PostgreSQL is intended for demonstration and test environments, so plan a separately managed PostgreSQL before go-live. Decide where authentik runs before you connect Forgejo or Gitea, because changing the authentik hostname later means updating the redirect URI and discovery URL on the Forgejo or Gitea side.
Group names agreed in advance
Decide which authentik groups will grant site admin rights and which will map to Forgejo or Gitea organizations before you write the group claim mapping. Group names in authentik should be stable and unambiguous, because the claim values are compared against them on every login. Write the list down with the owner of each group so that the admin mapping is reviewed, not improvised during setup.
Configuring authentik and Forgejo or Gitea in sequence
This sequence connects authentik to Forgejo or Gitea as an OpenID Connect sign-in source, so users can authenticate with their authentik identity and group membership can inform access inside the forge. The order matters because the redirect URI comes from the forge and the client credentials come from authentik.
Confirm the target versions and integration guide
The platform team confirms which Forgejo or Gitea version is running and which authentik version is deployed, then opens the matching authentik integration guide for Forgejo or Gitea. Check the guide against your installed versions before making changes, because setting names and screens can differ between releases. Confirm that your authentik version is one that receives security fixes under the authentik security policy. The step is done when the team has a written record of both versions and the guide it will follow.
Create the OAuth2 provider and application in authentik
An authentik administrator creates an OAuth2/OpenID Connect provider and a linked application for the forge, following the steps in the integration guide. Select the client type and signing settings the guide specifies, and keep the default scopes needed for the OpenID Connect login. Add a property mapping or scope mapping that emits group membership in the token or userinfo response, using the claim name the guide or your forge configuration expects. The step is done when the provider and application exist and the group mapping is attached to the provider.
Record the client ID and client secret
Copy the client ID and client secret generated for the provider and store them in your secret manager or another controlled location. Limit who can view the secret, because anyone holding it can impersonate the application to authentik. Do not paste the secret into tickets, chat or shared documents. The step is done when the values are stored and the administrator who will enter them in the forge can retrieve them through the approved channel.
Define the redirect URI from the forge
Open the OpenID Connect authentication source form in the Forgejo or Gitea administration panel, or follow the guide's instructions for generating the callback address. Copy the redirect URI the forge displays and enter it in the authentik provider so the two sides agree exactly on the callback path and host name. A mismatch in scheme, host or path is a common cause of failed logins, so compare the values character by character. The step is done when the redirect URI in authentik matches the one the forge shows.
Add the OpenID Connect source in the forge admin panel
A Forgejo or Gitea administrator adds an OpenID Connect authentication source in the admin panel. Enter the auto-discovery URL published by authentik for this provider, along with the client ID and client secret recorded earlier, then save the source. Set the group-related options as the guide describes so the forge reads the group claim for admin and organization decisions. The step is done when the source is saved and listed as enabled in the admin panel.
Check that the discovery document loads
Open the auto-discovery URL in a browser or with a command-line HTTP client and confirm that authentik returns a discovery document with the authorization, token and userinfo endpoints. Confirm that the issuer value matches the URL the forge expects. If the document does not load, fix the authentik host name, certificate trust or reverse proxy before going further. The step is done when the document loads without errors and the endpoints point to your authentik host.
Review the claims the forge receives
Sign in once as a test user and review the claims the forge received, either from its logs or from a test account's profile after login. Confirm that the subject, email and group claims contain the expected values for that user. Adjust the authentik mapping or the forge group settings if a group is missing or misnamed. The step is done when the test user's groups map to the intended forge permissions and no unexpected claims are present.
Test login from a private browser session
Open a private browser window, go to the forge sign-in page, choose the authentik source and complete the login with a test account. Confirm that you are redirected back to the forge, that the account is created or linked as the configuration expects, and that a second private session signs in without errors. Keep a local administrator account available until this test passes and recovery steps are documented. The step is done when the test login succeeds from a clean session.
Mapping authentik groups and claims to Forgejo or Gitea roles
This table maps each authentik claim to the Forgejo or Gitea account field or permission it controls. Read each row as a decision point: what the claim supplies, what the platform does with it, and where a mismatch causes silent access problems. Confirm the exact claim keys and mapping syntax in the authentik integration guide for your platform version before you write the expressions.
| Claim or attribute | Forgejo or Gitea effect | What to confirm | Common failure |
|---|---|---|---|
| Subject or username claim | Sets the local login name for the linked account | Which claim key the guide uses for the username and whether it must be unique and stable | Users with changed usernames in authentik get a second local account |
| Email claim | Sets the account email address | Whether the email is verified in authentik and whether the platform trusts it for account linking | Linking by an unverified email lets the wrong person claim an existing account |
| Group claim for admin status | Grants site administrator rights when the group matches the configured name | The exact group claim key, the admin group name setting and whether the check runs on every login | Broad groups such as all staff receive admin rights |
| Group claim for organization membership | Adds the user to organizations whose names match group names | That organization names must already exist and match group names exactly, including case | Groups with no matching organization are ignored without an error |
| Restricting admin to a named group | Limits site administration to members of one small, reviewed group in authentik | Who owns the group, how membership changes are approved and reviewed | Admin membership inherited through nested or default groups |
| Existing local accounts | Linking requires a deliberate step so the account is not taken over by a matching name or email | Whether the platform links by email or requires the user to confirm the link with their local password | Duplicate accounts appear when users sign in before the link is made |
| Group changes after login | Roles update at the next login if the platform re-reads claims on each sign-in | Whether removed groups revoke admin or organization access immediately or only after a new session | Former administrators keep access until their session expires |
Linking accounts that already exist in Forgejo or Gitea
The main risk when you add authentik as an OpenID Connect authentication source is that a local account already in Forgejo or Gitea shares a username or email address with an incoming OIDC identity. Linking that identity to the wrong local account would hand one person another person's repositories, organization memberships and admin rights, so decide before go-live how existing accounts will be matched. Linking happens when a user signs in through the new source for the first time: the platform asks them to confirm or link to an existing local account by signing in with that account's password. Treat that step as the control. Only users who can prove ownership of the local account should complete it, and any account you do not expect to be linked should be reviewed before users are invited to sign in.
Start with an inventory. Export the local user list from the administration panel or the database, and mark each account as a human user, a bot or CI account, a service account, or an admin. Decide which human accounts will be linked and which will be left for manual handling, such as accounts with no matching authentik user or accounts whose email address is out of date. Bot and service accounts that authenticate with tokens usually should not be linked at all. Confirm with your Forgejo or Gitea version's documentation which account-linking options it offers, since the wording of the prompt and the behavior of the first-sign-in screen can differ between releases.
Tell users the first sign-in step before the change goes live. They should expect a prompt to sign in through authentik, then a choice to link to an existing account or create a new one, and they should know to use their existing local password only when prompted to link. Keep at least one local administrator account that does not depend on the new source, and store its credentials where your recovery process can reach them. Before changing production users, repeat the full sequence on a copy of your instance: restore a recent backup, add the authentik source, sign in as a sample of ordinary, admin and bot users, and confirm that each account links to the intended user and keeps its repositories and permissions.
Hardening the SSO source and keeping an admin path
Once authentik signs users into Forgejo or Gitea, the OIDC source becomes a high-value path to admin rights. The cards below cover the settings that keep that path narrow, the controls on the authentik side, and the local access you keep for recovery. Check the audit and MFA features against your edition and license before you rely on them.
Keep the client secret in the forge only
Store the OAuth2 client secret only in the Forgejo or Gitea authentication source configuration, and in the authentik provider that issued it. Do not paste it into app.ini, repository files, CI variables or chat threads. Confirm who can open the admin settings page, because anyone who can read the source can copy the secret. Rotate it after staff changes or any suspected exposure, and update both sides in the same change window.
Use HTTPS for discovery and redirects
Both the auto-discovery URL and the redirect URI should use HTTPS with a certificate your forge hosts trust. Mismatched hostnames, plain HTTP discovery or a redirect URI that differs by a trailing slash will break sign-in or invite interception. Check that the forge's root URL and the redirect URI registered in authentik match exactly, and that the forge can reach the authentik discovery endpoint from its own network.
Limit admin mapping to one authentik group
Map forge administrator rights only from a dedicated authentik group, such as a group used only for forge administrators, and keep it out of general staff groups. If the group claim is broad, any user who joins a common group can become a forge admin on their next sign-in. Review membership of that group on a schedule, and confirm which claim name your forge version reads for groups before you write the mapping.
Enforce MFA for authentik administrators
Require a second factor for every authentik user who can change providers, flows or group membership, because those accounts control what the forge trusts. Set the MFA requirement in the authentik flow or policy that applies to administrators, not only in the user interface. Confirm which second factor types your authentik edition supports and whether your forge's own two-factor settings apply to SSO-created accounts.
Keep a local break-glass admin
Keep at least one local administrator account in Forgejo or Gitea that does not depend on authentik. Store its credentials offline, test that it can sign in, and document who may use it. Set local sign-in to remain available when the authentik source is disabled or unreachable. Without this account, a misconfigured group claim or an authentik outage can lock every administrator out of the forge.
Review audit logs after each change
After you change the authentication source, group mapping or admin rules, review the forge and authentik logs for the sign-ins and role changes that followed. Check that accounts gained only the rights you intended. Audit logging is listed as an Enterprise feature in authentik's pricing, and Gitea Enterprise lists audit logging and mandatory two-factor authentication, so confirm whether the logs you need are available in your edition before you plan the review.
Common failures when connecting authentik to Forgejo or Gitea
This table lists the failures most often seen when adding authentik as an OpenID Connect authentication source in Forgejo or Gitea, with the likely cause and fix for each. Check the Forgejo or Gitea server log and the authentik event log first, since the error text in those logs usually points to the row that applies. Work through the rows in order, because a discovery or redirect problem blocks every later step.
| Failure | Likely cause | Fix |
|---|---|---|
| Redirect URI mismatch after clicking sign-in | The callback URL registered in the authentik OAuth2/OIDC provider does not exactly match the callback URL Forgejo or Gitea sends, often because of the scheme, port, or a trailing path difference from the root URL setting. | Copy the callback URL shown in the Forgejo or Gitea authentication source settings into the provider's redirect URIs exactly, then confirm the server's public root URL matches the address users browse to. |
| Discovery URL unreachable or certificate not trusted | The auto-discovery URL points to a host the Forgejo or Gitea server cannot resolve or reach, or the authentik certificate is issued by an internal CA that the application host does not trust. | Fetch the discovery document from the Forgejo or Gitea host with curl, then add the internal CA to the host trust store and restart the service. Do not disable TLS verification as a fix. |
| Invalid client or token exchange error | The client secret in the Forgejo or Gitea source does not match the secret on the authentik provider, often after the secret was rotated in one place only. | Regenerate or re-enter the client secret on both sides, save each, and retry a fresh sign-in in a private browser window to avoid stale sessions. |
| Admin or organization mapping does not apply | The group claim is missing from the ID token or userinfo response because the scope or property mapping in authentik does not include the groups attribute, or the group names differ from the values Forgejo or Gitea expects. | Inspect the claims returned for a test user, add the groups scope and mapping on the authentik provider, and align group names with the configured admin and organization group settings. Users must sign in again for new claims to take effect. |
| Duplicate email blocks account linking | A local account already uses the same email address as the authentik user, so the sign-in cannot link automatically to a new external account. | Decide which account is authoritative, rename or remove the duplicate, or use the account linking step where the user confirms the local password. Confirm the address in authentik matches the one the user already holds before linking. |
| Users locked out after local login is disabled | Local password sign-in was turned off before the OIDC path was tested, or the group mapping denies admin access, leaving no account able to change settings. | Keep at least one local administrator until SSO is verified, and re-enable local login temporarily through the configuration file or command line on the server. Test SSO with a non-admin account before disabling local login for everyone. |
| Login works but user lacks expected permissions | The admin or organization group claim is absent or uses a different value for the same group, so users are created with default rights. | Compare the group claim from a test sign-in with the expected names, correct the mapping in Forgejo or Gitea or in the authentik group, and check the user's rights on the admin panel after the next sign-in. |
| Errors appear with no obvious cause | The failure happens inside the callback handling, and the browser shows only a generic error page. | Read the Forgejo or Gitea server log at the time of the attempt, then the authentik event log for the matching provider and user. Share both entries with the vendor or your partner before changing settings. |
Questions buyers ask before configuring Forgejo or Gitea SSO
What drives the cost of setting up authentik SSO for Forgejo or Gitea?
The cost follows the written scope, and the main drivers are the number of users, how many accounts already exist locally, how group claims should map to admin rights and organizations, and whether the Git server runs in more than one environment. A partner quote should separate the one-time build (authentik provider and application setup, Forgejo or Gitea authentication source configuration, account linking, testing and handover) from any recurring support or upgrade retainer. Ask for each line item, the assumptions behind the user count, and whether testing against a staging instance is included. Cost also rises when the group design is undecided at the start, because mapping changes ripple into both systems.
How long does an authentik and Forgejo or Gitea SSO integration take?
The duration depends less on the configuration itself than on the team's schedule, decisions and approvals. The technical steps are short once the group design is agreed, but a change window, a test group of users and sign-off from the people who own the Git server all add waiting time. Ask a partner to state the schedule as dependencies: when the authentik admin and Git server admin must be available, when the test group is needed, and which decisions must be closed before build starts. A fixed-scope agreement should put those dependencies in writing next to the milestones.
What access and people does the team need to provide?
Three things are needed before work starts: administrator access to authentik to create the OAuth2/OpenID Connect provider and application, administrator access to the Forgejo or Gitea instance to add the authentication source and manage existing accounts, and a small test group of real users who can sign in and confirm their roles. You also need a named owner who can approve the group-to-role mapping, because that mapping decides who becomes an instance admin or organization owner. Confirm with the partner whether they need a staging instance, a copy of the production database for account-linking tests, and how credentials for the OAuth client will be shared and rotated.
Can an internal team set up authentik SSO for Forgejo or Gitea without a partner?
Yes, an experienced internal team can follow the published authentik integration guides for Forgejo and Gitea, which both use an OAuth2/OpenID Connect provider. The guides cover the provider setup and the authentication source settings on the Git side. The harder parts are usually outside the guide: designing group claims that match your organization, deciding how existing local accounts will be linked without locking users out, keeping a local admin path for recovery, and testing failure cases before users depend on it. A partner is most useful when those design decisions are unclear or when the team has no time to test properly.
Does this integration require authentik Enterprise?
No. The Forgejo and Gitea integration uses the OAuth2/OpenID Connect provider type, which authentik documents as part of its provider set, and the open-source edition is listed as free on the pricing page. authentik's repository places most code under the MIT license, while code in the authentik/enterprise/ directory uses a separate enterprise license. The Enterprise features listed on the pricing page, such as Google Workspace and Microsoft Entra ID integrations, mTLS and enhanced audit logging, are not needed for this OIDC flow. Confirm the exact license terms in the LICENSE file and with your authentik contact before you deploy, and check whether your organization's own policy requires a support contract.
Does the Git server's own edition affect whether SSO works?
The Forgejo or Gitea edition you run matters more than the authentik edition. Forgejo uses an OpenID Connect authentication source configured by administrators, and Gitea offers SAML 2.0 service provider support only in Gitea Enterprise, which this OIDC setup does not need. Check the version you run against the release notes before you start, because the admin settings and upgrade rules change between major releases. Forgejo's upgrade documentation describes transparent upgrades from Gitea up to v1.22 in two steps, so a Gitea instance on an older line should be upgraded on that path first. Ask the partner to confirm the target version in writing.
What breaks after the switch, and how do we link existing accounts safely?
The most common problems are users who sign in with a local account that does not match the authentik username or email, duplicate accounts created at first SSO login, and admin rights that do not match the group claim after a role change. Plan the account linking step before go-live: decide which local accounts map to which authentik identities, test linking on a copy, and keep at least one local administrator who can sign in if the identity provider is down. Also confirm how authentik's group claims reach the Git server, since a missing or renamed claim can silently remove admin or organization access. Test each of these with the test group before the cutover.
What should we ask for in a written quote?
Ask for a fixed-scope statement that lists the systems in scope (authentik, the Forgejo or Gitea instance, and any staging copy), the group-to-role mapping as an agreed table, the account linking method and what happens to accounts that do not match, the test plan with the test group's involvement, and the handover documentation. Ask which items are one-time and which recur, such as upgrade support or ongoing maintenance. Also ask what the partner needs from your team and when, and how changes requested after sign-off will be priced and scheduled.
How DeployOpen scopes and delivers this integration
DeployOpen is a Chainscore Labs company that plans, implements, integrates and supports self-hosted open-source platforms in your own infrastructure, including the cloud accounts, data centers or air-gapped networks you already run. For this integration, that means the work happens where your authentik server, your Forgejo or Gitea instance and your identity data already live, and nothing is hosted on DeployOpen's side. DeployOpen does not hold itself out as an authentik vendor partner or a certified provider, and it does not issue certifications or audit reports for the systems it configures.
Most engagements are fixed-scope. Before work starts, the written scope sets out which Forgejo or Gitea instances, authentik applications and group claims are in scope, which accounts will be linked, what testing proves the sign-in path works, and what handover documentation you receive. DeployOpen does not publish a price list, so a quote follows from that written scope. To compare quotes, ask each provider to list the instances, environments, group mappings and account-linking steps it has priced, and to state which items are excluded. Ask whether a later change to the group model or a version upgrade of either side would be billed as a new change or covered by the original scope.
Ongoing support, upgrades and periodic testing are available as a retainer, which suits teams that change group mappings often or that must keep sign-in working through authentik and Forgejo or Gitea version changes. Confirm with the provider how the retainer handles security releases, since both sides publish them on their own schedules. Before you sign, decide who in your organization owns the group names that feed the admin and organization mappings, because that ownership decides who must approve each change once the integration is live.
