External Authentication Detail

In this overview, we will take Azure configuration as an explanation of how the Portainer External Authentication extension is configured and functions. Configuration guides for Azure, Google and Github are available as part of the extension. Custom configuration is also available.


Step 1, Login to your Azure Portal as an Admin

Step 2, Retrieve your Tenant ID / Directory ID;
Click on “Azure Active Directory”, and then Click on “Properties”, and then note your “Directory ID” for later use.

Step 3; Define your Portainer Instance
Still in Azure Active Directory, Click on App Registrations
Click on “+ New Application Registration”

Enter in a friendly name for the Portainer Instance
Keep the app type as Web App / API
In the “Sign-on URL” field, enter the FQDN or IP address that your Portainer instance listens on.

Step 4: Retrieve the Application ID
After creating the app, the screen below is displayed; record the application ID for later use.

Step 5: Create the application login key
Click on “Settings”, then “Keys”

Under the “Passwords” section, create a new key called “login”, set the duration to “never expires”, and then click save.
The key will then be generated for you. Note this key value for later use.

Step 6: Switch to your Portainer Instance and login as the local instance admin
Purchase the OAuth extension, and apply the license key (process not shown here).
Lets setup some basics, so that when user’s login for the first time, they can actually access Portainer resources:

Click on “Users” and then “Teams”, and create a team called “oauth” (or one of your choosing)

Click on “Endpoints” and then select the endpoints you would like to grant the OAuth users access to manage, and then click “Manage Access”. Assign the OAuth group you created to the authorised list.

Step 7: lets configure OAuth.
Click on “settings” and then “Authentication”
Select “OAuth” and then select “Microsoft”

Enable Automatic User Provisioning, and select the default team(OAuth or similar) that you created previously.
Enter in the Tenant ID (Directory ID) that you noted previously
Enter in the Application ID that you noted previously
Enter in the Application Key (Login key) that you noted previously.
Click Save.

Logout as the Admin

Step 8: Login using OAuth
At the Login Page, click the “Login with Microsoft” box for OAuth login.
Enter your Azure username and password where prompted (note you are redirected to Azure for Auth)

Accept the “Permissions Requested” box on behalf of your organisation (only occurs for the very first OAuth login to Portainer)

You are now logged into Portainer using OAuth from Microsoft.

Optionally, if you want your OAuth user to be a Portainer Admin, first login/logout as the OAuth user to create the Portainer record, then login as the Portainer local admin (or as another admin), and then edit the user to elevate them to an admin.