Microsoft Entra ID SSO for Portainer

ThisPrerequisites: guide shows how to integrate Portainer with Microsoft Entra ID using the built-in Microsoft OAuth provider.

Important licensing note

SSO features depend on the Portainer edition and licensing model available for your deployment. Validate your current Portainer edition and entitlement before starting.

Why integrate Portainer with Entra ID

Benefits:

central authentication easier user lifecycle management optional automatic user provisioning team mapping based on group claims reduced password sprawl

Prerequisites

Portainer is reachable over HTTPS administrator access to Portainer permissionAbility to create an app registration with delegated standard rights. Portainer should be installed and administrator access to the web interface should be available.

This guide will take you through the various stages of installing SSO using Microsoft Entra tenantID. available

Unfortunately, it

Stepis 1:not Createpossible to add the appSSO registration

Recommended settings:

Platform: Web Redirect URI: https://<portainer-domain>:9443

Record the Tenant ID, Application ID and Client Secret.

Step 2: Configure permissions

Use standard delegated sign-in permissions:

openid profile email

If you plan to use group-based team membership, also configure group claimsfunctions in the token.

Portainer

StepCommunity 3:Edition Configure(CE). Accordingly, we have to purchase a free license of the Business Edition (BE) and upgrade the Portainer authentication

instance.

InYou Portainerwill gothen be able to Settingsmanage >the Authentication > OAuth > Microsoftlogins and configure:

authorizations

for Tenantthe IDweb Applicationinterface IDvia ApplicationMicrosoft keyEntra SSOID. Functions such as automatic user provisioning asor neededdefault permissions

are also supported by Portainer.

Create App Registration

WarningFirst, Doan notapp hideregistration including client secret must be created in Microsoft Entra ID. All settings can be left at the internaldefault authenticationvalues. promptImportant untilsettings are the Redirect URIs under the Authentication tab. Set these URIs to your external loginor internal domain on which Portainer is fullyavailable. tested.

These

URIs

Stepwill 4:be Optionalused team mapping

If you want automated authorization:

enable group claims in the Entra app use claim-based or regex-based mapping in Portainer for Entra groups, use the group Object ID, not the display name, where Portainer expects the claim value

Summary

Portainer and Microsoft Entra ID workto wellknow togetherwhere whento redirect the user in case of successful logins.

Authentication Type: Web
Redirect URIs: https://portainer.yourdomain.com

Add the corresponding permissions for OpenID Connect as delegated permissions and grant admin consent for your tenant.

Permissions: Delegated OpenId permissions (email, offline_access, openid, profile)

Create a client secret for the application and save the tenant ID, application ID and client secret in your password manager. You can find instructions for this information here: Get app details and grant permissions to app registration

Acquire Portainer License

To activate the SSO functionality, the Portainer Comunity Edition must be replaced by a Business Edition. Don't worry, it costs nothing. At least for a Homelab environment and installation with less than 3 environments. For business customer licensing in Portainer Business Edition is based on the number of nodes you combineare managing.

Create an account and follow the instructions on this page: Take 3 - Get your first 3 nodes free (portainer.io)

Upgrade Portainer instance

After you have received the license key via email you can start upgrading your Portainer CE to a cleanPortainer BE instance. Make sure to create a backup before you upgrade the instance.

When running portainer inside a single docker container, it is no simpler than changing the image from "portainer/portainer-ce" to "portainer/portainer-ee" and restart the stack or containers. You can find more in depth guides and version specific upgrade manuals here: Docker Standalone | Portainer Documentation

Check activation status

After installing the license, this can be checked in the web appinterface. registration,To standarddo delegatedthis, OIDCnavigate permissions,to optional group claims“Licenses” and carefulcheck fallbackwhether accessyour planning.license is installed and the limitation to 3 nodes is displayed. Then you are ready to add external authentication providers such as Microsoft Entra ID. Go to the next step.

Setup Microsoft Entra ID login provider

For the setup, log into the web interface with an administrator account. You can then select the “OAuth” option under Settings -> Authentication -> Authentication method. The following settings enable automatic user provision or a default group. Configure this as it suits you. Attention: It is recommended that the option “hide internal authentication prompt” is not activated so that the values can still be adjusted in the event of a misconfiguration of the OAuth provider settings. If this is activated, you can lock yourself out and have to rebuild the Portainer instance. 

You can then select the "Microsoft OAuth provider" under “Provider” and fill in the TenantID, ClientID and Client Secret options with the corresponding values from the app registration. After saving the settings, you can control who can connect to the web interface of the Portainer instance via the app registration members.