authentik and Portainer SSO integration

How authentik signs Portainer users in with OAuth

A platform team running Portainer that wants one login and group-based access from authentik should use OAuth. The authentik integrations catalog documents Portainer's OAuth sign-in, and it states that team membership and admin access can be assigned from authentik group claims in Portainer Business Edition. Before you plan around group mapping, confirm with Portainer which edition your environment runs, because the group-based behavior is documented for Business Edition and the Community Edition scope must be verified directly with the vendor.

The authentik Portainer guide is the source for the exact settings, so work from it rather than from memory of older instructions. In practice, the build involves creating an OAuth provider and application in authentik, registering the redirect and client values in Portainer's authentication settings, and confirming that the claims authentik sends include the group names your mapping depends on. Decide early which authentik groups should become Portainer teams and which one should hold administrator rights, and keep at least one local Portainer administrator account in reserve so that a misconfigured claim or a provider outage does not lock every operator out of the console.

Test with a non-administrator account first, then with a user who belongs to each mapped group, and record what Portainer grants in each case. Check that automatic user creation produces the expected accounts, that users removed from an authentik group lose the matching Portainer team on their next sign-in, and that the administrator mapping only grants access to the intended group. Ask your Portainer contact to confirm the license tier, the supported Portainer version and any behavior around existing local accounts before you schedule a cutover.

What you need before configuring Portainer SSO with authentik

The OAuth link between authentik and Portainer depends on decisions made before anyone opens either admin console. Confirm the authentik version, the Portainer edition, the hostnames and certificates, the group design and a local recovery path first, because changing these later affects every user who signs in.

A supported authentik version

Check that your authentik deployment runs a version the project still patches. The security policy lists 2026.5.x and 2026.8.x as receiving security fixes, so a deployment on any other line should be planned for upgrade before the Portainer work starts. The project announces security releases at least 24 hours in advance, which gives you a window to schedule patching. Record the exact version you test against, because the provider settings screens can change between releases.

A Portainer edition with group mapping

Confirm that your Portainer edition includes the features you need. The authentik integration guide says Portainer Business Edition can configure automatic team membership and grant admin access from authentik group claims. If you run Community Edition, plan for manual team assignment or accept that SSO only creates accounts. Ask Portainer to confirm the current edition feature matrix for your version, since licensing terms are the vendor's to state.

A DNS name and trusted TLS certificate

Give Portainer and authentik stable hostnames that resolve from every browser that will sign in. The redirect URI registered in authentik must match the Portainer address exactly, including scheme and port. Both the browser and the Portainer server must trust the certificate chain used by the authentik endpoint, otherwise the OAuth token exchange fails on the server side even when the browser login looks correct. Confirm internal CA bundles are installed in the Portainer container.

A named group structure in authentik

Decide which authentik groups map to Portainer teams and which group grants administrator access before you configure the claim. Create these groups in authentik, add a deliberate test membership for each, and confirm the groups appear in the token claims your provider emits. Use names that describe the access rather than individuals, and keep the admin group small. Changing group names later means updating both the authentik scope mapping and the Portainer mapping together.

A break-glass local admin in Portainer

Before enabling OAuth, keep a local administrator account in Portainer that does not depend on authentik. If the OAuth provider is misconfigured, the authentik server is down, or a mapping removes every admin, this account is the only route back in. Store its credentials in your secrets system, test that it logs in, and document who may use it. Verify the account works after every change to the SSO settings.

Configuring the authentik provider and Portainer OAuth settings in order

This sequence connects Portainer to an authentik OAuth2/OIDC provider so users sign in with their directory accounts, get created on first login, and receive team and admin rights from authentik group claims. Each step closes with a check so you can confirm the link before moving on.

Create the OAuth2/OIDC provider in authentik
An administrator signs in to the authentik admin interface and creates a new provider of type OAuth2/OIDC under the provider settings. Choose the authorization flow your organization uses for interactive sign-in, and keep the provider name clear enough that someone reading the audit trail will recognize it as the Portainer link. Set the signing key and the client type that the Portainer guide specifies. The step is done when the provider appears in the provider list with its status visible.
Create the application and bind the provider
In the applications section, create an application for Portainer and attach the provider from the previous step. Set the launch URL to the address users open in their browser, which should be the external URL of your Portainer instance. Restrict access with a policy or group binding if only certain users should be able to use Portainer. The step is done when the application appears in the application list and the provider shows as bound to it.
Set the redirect URI and scopes
Open the authentik integration guide for Portainer and copy the redirect URI and scope values exactly as written there, then enter them on the provider. A mismatch in the redirect URI is the most common reason for a failed sign-in, so compare the string character by character, including the trailing path and the scheme. Confirm that the scopes include the claims the group mapping depends on, such as the group claim. The step is done when the provider's saved values match the guide text.
Record the client ID and client secret
After saving the provider, copy the client ID and client secret from the provider details. Store the secret in your organization's approved secret store rather than in a ticket, chat message or shared document, and limit who can read it. Treat the secret as a credential that must be rotated if it is exposed. The step is done when both values are stored in the secret store and the person configuring Portainer can retrieve them from there.
Enter the OAuth client settings in Portainer
Sign in to Portainer as the existing local administrator and open the authentication settings. Select OAuth as the authentication method and enter the client ID, client secret, authorization URL, access token URL, resource URL and redirect URL taken from the authentik provider and the integration guide. Keep the local administrator account enabled so you have a recovery path if the OAuth settings fail. The step is done when Portainer saves the settings and the login page offers the OAuth sign-in option.
Enable automatic user creation and test a non-admin login
In the same OAuth settings, enable automatic user creation so that a user who signs in through authentik gets a Portainer account on first login. Sign out, then sign in as a test user from authentik who is not in any administrator group. Open the Portainer user list as the local administrator and confirm the new account exists and has no administrator rights. The step is done when the test user's account appears in the list with standard access only.
Map groups to teams and admin access in Business Edition
Portainer Business Edition can set team membership and admin access from group claims in the token that authentik sends. Confirm that your organization holds a Business Edition license before you start, because this mapping is not part of the standard setup. Enter the group claim names from authentik into the team and admin mapping fields, following the integration guide. Test with one user from each group, then confirm that each user lands in the expected team and that only the admin group receives administrator rights. The step is done when every test user's team and role match the group they belong to in authentik.

Which authentik groups map to Portainer teams and admin rights

This table pairs each authentik group with the Portainer team or admin grant it should trigger, and names who approves membership. Read it as a starting design: the group names are illustrative, and the exact claim names and mapping fields must be confirmed in the Portainer integration guide before you rely on them. The main takeaway is that admin rights should come from a small, explicitly approved group, and any user without a matching group should get no access or the default role your team has chosen.

authentik group	Claim value to confirm	Portainer target	Who approves membership
portainer-admins (illustrative)	Confirm exact value in the Portainer guide	Admin access grant	Platform lead and security owner, with a recorded reason
portainer-team-platform (illustrative)	Confirm exact value in the Portainer guide	Team: platform engineering	Platform team lead
portainer-team-apps (illustrative)	Confirm exact value in the Portainer guide	Team: application developers	Application owner for each environment
portainer-team-readonly (illustrative)	Confirm exact value in the Portainer guide	Team: auditors or read-only observers	Security or compliance lead
No matching portainer group	Not applicable	No team and no admin grant, or the default role your team has chosen	Not applicable; access requires a request to add a group
Multiple groups matching one user	Confirm how Portainer resolves overlapping teams and admin grants	Team memberships and admin status as Portainer evaluates them	Confirm the precedence rule with your own test accounts
Group removed in authentik	Confirm whether removal takes effect at next login	Team membership or admin status removed on next sync or login	Group owner in authentik, reviewed on a fixed schedule

Automatic user creation and team membership in Portainer Business Edition

When automatic user creation is enabled, the first successful OAuth login from authentik creates a Portainer user account without an administrator having to add it by hand. Team membership and admin access are then derived from the group claims authentik sends in the token. The integration guide in the authentik integrations catalog states that Portainer Business Edition can assign team membership and grant admin access from those claims. Before rollout, the team should confirm in the Portainer documentation which claim name and group values the edition expects, how the group-to-team mapping is entered, and whether an administrator must approve new accounts or whether the first login is enough to create one. Test with one user from each group that should map to a team and one from a group that should receive admin access, and record the Portainer team and role each lands in.

Membership is refreshed from claims at login, not continuously. A user who is removed from an authentik group keeps the Portainer team or admin role they received earlier until the next login recalculates it, and an existing Portainer session may stay valid for longer than that. Any account that is disabled in authentik still needs its Portainer access checked, since a local Portainer account created before SSO was enabled may not be affected by the authentik change at all. Ask the vendor how group changes are applied to active sessions, whether Portainer re-reads claims on each login or only on account creation, and whether an API token or access token created through Portainer survives an identity change. The answers decide whether the revocation procedure is a deactivation in authentik alone or also a removal in Portainer.

Plan the offboarding step as a two-system check rather than trusting one side. Write down the expected sync behavior, run a test where a user leaves a mapped group and then logs in again, and confirm the resulting Portainer role. Keep a documented local administrator path so that a mapping mistake cannot lock out every operator, and review the mapping whenever authentik group names change. The deployment-specific answers should come from the Portainer documentation for the version in use and from a test in your own environment, not from this page.

Hardening the Portainer OAuth connection

The OAuth connection between authentik and Portainer carries admin access, so each setting below is a place where a mistake grants more than it should. The cards cover where each control lives, in the authentik provider and application or in Portainer's authentication settings, and what to verify after the integration goes live.

Keep the client secret out of shared configuration

The OAuth client secret is generated on the authentik OAuth2/OIDC provider and entered in Portainer's OAuth settings. Store it in your secrets manager or the Portainer settings only, not in Compose files, Helm values committed to Git, or chat threads. Rotate it if anyone with admin access leaves or the value is exposed, and confirm that the old secret is rejected after rotation.

Pin redirect URIs to the exact Portainer URL

Set the redirect URI on the authentik provider to the exact callback address Portainer uses, including scheme, host and path. Avoid wildcards and avoid listing old hostnames from a previous deployment. A loose redirect URI lets an authorization response be sent somewhere other than your Portainer instance, so compare the configured value with the address users actually open.

Limit the admin group to a named set

The Portainer Business Edition mapping can grant admin access from an authentik group claim. Use a dedicated group, such as a Portainer administrators group, and keep its membership to a small named list reviewed by the platform owner. Do not map broad groups like all staff or every engineer to admin, and confirm in Portainer that a regular group member does not receive admin rights.

Enforce MFA on the Portainer application

Attach an authentication flow with a multi-factor stage to the Portainer application or its authorization policy in authentik, so that sign-in through this provider requires a second factor. Test with a user who has no enrolled factor to confirm that the policy blocks access instead of letting the user through. Portainer's own login behavior should be checked separately, since local logins can bypass the authentik flow.

Keep a local break-glass admin

Keep one local Portainer administrator account with a strong, stored password and document how to use it when authentik or the OAuth connection is down. Test the break-glass login before go-live and after any change to the OAuth settings. Limit who knows its credentials, and disable or rotate it under your own access review process if it is no longer needed.

Log sign-ins and reviews in authentik

Review authentik's event log for Portainer logins, failed authorizations and policy denials, and forward those events to your central log store if your operations model requires it. Confirm which fields identify the user and the application so reviewers can trace an admin session. Schedule a periodic review of who holds the admin group and compare it with the log of recent sign-ins.

Why Portainer SSO logins fail and how to fix them

This table lists the failures teams most often hit when wiring Portainer to authentik over OAuth, with the likely cause and the setting to check for each. Read it top to bottom when a login breaks, or use it as a checklist before go-live. Most failures trace back to a mismatched redirect URI, a client secret that was rotated on one side only, or group claims that do not reach Portainer's team and admin mapping.

Symptom	Likely cause	Fix
Redirect error after authentik sign-in	Redirect URI in the authentik OAuth2/OIDC provider does not exactly match the Portainer URL, including scheme, host, port and path	Copy the redirect URI shown in Portainer's OAuth settings into the authentik provider, matching https and the trailing path exactly, then save and retry
Token exchange fails or login loops back to the Portainer login page	Client secret in Portainer differs from the client secret on the authentik provider, often after a rotation on one side only	Regenerate or copy the client secret from the authentik provider, paste it into Portainer's OAuth client secret field, and confirm no stray spaces
TLS or certificate trust error when Portainer contacts authentik	Portainer host does not trust the certificate chain of the authentik server, typically an internal or private certificate authority	Install the internal CA certificate on the Portainer host and its container trust store, then confirm the authentik issuer URL resolves from inside the Portainer container
User signs in but lands with no team or no access	Group claims are not included in the token, or the group names in Portainer's team mapping do not match the authentik group names	Confirm the groups scope and group claim are returned by the authentik provider, then compare group names character for character with the Portainer team mapping
User signs in but has no administrator rights	Admin mapping in Portainer Business Edition is keyed to a group that the user is not in, or the user already exists locally with a lower role	Check the authentik group that Portainer's admin mapping expects, add the user to it, and confirm whether an existing local account is being reused
Users cannot sign in after authentik or the outpost goes down	Portainer depends on authentik for every OAuth login and the local admin path was not kept for recovery	Keep a local Portainer administrator account available for break-glass access and document how to use it before go-live
Automatic user creation does not happen	Automatic user provisioning is disabled in Portainer's OAuth settings, or the user lacks an authentik group or claim that Portainer requires	Enable automatic user creation in Portainer's OAuth settings and test with a user who has the expected authentik group membership

Choosing between Portainer editions for group-based access

Teams that only need people to sign in with their authentik accounts can work from the OAuth client settings in the authentik Portainer guide. authentik acts as the OAuth provider, Portainer handles the sign-in, and user accounts can be created on first login. Team and admin rights inside Portainer are then assigned by hand for each user, which is manageable for a small group of users and a small number of environments.

Client settings: Create the OAuth provider and application in authentik, then enter the matching client ID, client secret and redirect details in Portainer.
Automatic user creation: Confirm that first-login account creation is available in your Portainer version and edition before you rely on it.
Manual access control: Assign teams and admin rights inside Portainer for each user and record those assignments.
Offboarding: Disabling a user in authentik stops new sign-ins, but confirm how existing Portainer accounts and active sessions are handled.

Before you commit, confirm with Portainer which edition includes the OAuth login settings you plan to use, and test the full sign-in and sign-out path with a non-admin account.

What Portainer SSO with authentik costs and how long it takes

What drives the cost of setting up Portainer SSO with authentik?

The cost follows the written scope, and four inputs move it most: how complex your group model is, how many Portainer environments need the same sign-on, how mature your existing authentik deployment is, and how much testing you need before cutover. A single Portainer instance with a flat group list is a small job. Several environments with team membership and admin mapping across different groups takes more design and more verification. DeployOpen does not publish a price list, so a quote follows from the agreed scope in writing.

Can our own team set up Portainer SSO with authentik without outside help?

Yes, if you have two people: an authentik administrator who can create the OAuth2/OIDC provider, application, groups and claim mappings, and a Portainer administrator who can change its authentication settings and test sign-in. The integration is a standard OAuth setup, and the authentik integrations catalog describes the Portainer steps. Team members who already run authentik and Portainer in production will move faster. Hire help when nobody on the team has done an OIDC setup before, or when the group model needs design work first.

How long does the Portainer SSO work take?

Duration depends on the same inputs as cost: group design, the number of Portainer environments, authentik maturity and the test plan. A basic sign-in with automatic user creation can be configured quickly once the authentik provider exists. Group-based team membership and admin mapping take longer because each group must be agreed, tested and checked against real accounts. Ask for a timeline in the written scope that separates design, build, test and cutover, so you can see which step is driving the date.

What do we need to provide before the work starts?

Plan to provide three things. First, group owners who can confirm which authentik groups should map to Portainer teams and which should receive admin access. Second, a set of test users in authentik that cover each group, including at least one user who should not have admin rights, so you can prove the mapping works. Third, a change window in which Portainer's authentication settings can be switched and, if needed, rolled back. Also confirm who holds the Portainer admin account that stays local for recovery.

Is automatic team membership and admin mapping available in every Portainer edition?

No. The authentik integrations catalog says Portainer Business Edition can configure automatic team membership and grant admin access from authentik group claims. If you run a different Portainer edition, confirm the available options with Portainer before you design the group model, because the mapping approach depends on that choice. Automatic user creation and basic OAuth sign-in should be checked against your edition as well.

How are Portainer and authentik licensed, and are the costs separate?

Yes, they are separate. authentik's own pricing page lists an Open Source edition at no cost, with community support through Discord. Its Enterprise edition is listed at $5 per user per month billed annually, plus $0.02 per external user per month, and Enterprise Plus starts at $20k annually. The source describes the enterprise features as covered by a separate license in the enterprise directory. Portainer licensing is a separate agreement with Portainer. Confirm which authentik edition and which Portainer edition you need before you compare totals.

What recurring work comes after the initial setup?

Plan for ongoing work on both sides. authentik publishes security releases and lists 2026.5.x and 2026.8.x as the supported versions receiving security fixes, with security releases announced at least 24 hours in advance. Each authentik upgrade or Portainer upgrade can change claim behavior, so retest group mapping after each change. Ongoing support, upgrades and continuous testing are available as DeployOpen retainers, and the scope of any retainer is agreed in writing.

What does a Portainer SSO engagement not cover?

Confirm the boundaries in the written scope. A typical Portainer SSO scope covers the authentik provider and application, the Portainer OAuth settings, group claim mapping, user creation behavior and testing. It usually does not cover redesigning your directory, building wider authentik flows or policies, or changing Portainer's environment and endpoint configuration beyond what sign-in needs, unless you add those to the scope. Ask for an explicit list of in-scope and out-of-scope items before you sign.

How DeployOpen scopes and delivers Portainer SSO with authentik

DeployOpen plans, implements, tests and documents authentik and Portainer SSO integration inside your own infrastructure, as a fixed-scope engagement agreed in writing before work starts. We set up the authentik OAuth provider, the Portainer client settings and the group-to-team and admin mapping, then hand over a working configuration your team can run.

How we scope

Confirm which Portainer edition you run, since automatic team membership and admin mapping depend on Portainer Business Edition.
Define the authentik groups, the Portainer teams they map to, and which group grants administrator access.
Record the authentik and Portainer versions, hostnames, TLS setup and the local admin fallback in the written scope.
Agree whether ongoing support is needed afterward, which is available as a retainer.

How we build

Create the authentik OAuth2/OIDC provider and application for Portainer, with redirect URIs matching your Portainer hostname.
Configure Portainer OAuth settings, automatic user creation and group claim mapping in a non-production instance first.
Test sign-in for a standard user, a team member and an administrator, and confirm each lands with the expected access.
Confirm that the local admin account still works so a sign-in outage does not lock out the platform team.

How we hand over

Provide a written record of the authentik provider settings, Portainer client configuration and group mapping rules.
Document the test cases used, their results, and the steps to add or remove a user from a mapped group.
Walk your administrators through the break-glass procedure and where the recovery credentials are stored.
Deliver the configuration in the form your team can review, reproduce and change in later releases.

How we support

Review Portainer and authentik release notes before upgrades, so claim names and OAuth settings are rechecked.
Retest sign-in and group mapping after authentik or Portainer upgrades, using the documented test cases.
Offer ongoing support, upgrades and testing as a retainer if your team wants DeployOpen to keep the integration current.
Raise scope changes in writing, so any new teams, groups or edition changes are priced and timed before work begins.