Skip to content

External Identity Provider Setup⚓︎

This guide explains how to configure external identity providers (IdPs) with prokube.

Overview⚓︎

prokube uses Keycloak as its identity broker. You can federate Keycloak with external identity providers to:

  • Allow users to sign in with their corporate credentials
  • Centralize user management in your existing IdP
  • Enable Single Sign-On (SSO) across your organization
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Browser   │────▶│  Keycloak   │────▶│ External IdP│
│             │     │  (broker)   │     │             │
└─────────────┘     └─────────────┘     └─────────────┘

Example: Microsoft Entra ID

This guide uses Microsoft Entra ID (Azure AD) as a detailed example. The same principles apply to other OIDC-compatible identity providers like Google Workspace, Okta, or any generic OIDC provider. See Other Identity Providers for brief setup notes on alternatives.

Microsoft Entra ID (Azure AD) Example⚓︎

Prerequisites⚓︎

  • Access to the Azure Portal with permissions to create App Registrations
  • Admin access to the Keycloak prokube realm
  • Your prokube domain (e.g., https://cluster.example.com)

Step 1: Create Azure App Registration⚓︎

  1. Go to the Azure Portal
  2. Navigate to Microsoft Entra ID → App registrations

  3. Click New registration

    Field Value
    Name prokube-sso (or your preferred name)
    Supported account types Choose based on your needs (single tenant recommended)
    Redirect URI Platform: Web
    URI: https://<your-domain>/auth/realms/prokube/broker/microsoft/endpoint

  4. Click Register

Step 2: Configure Azure App⚓︎

After registration, configure the app:

Client Secret⚓︎

  1. Go to Certificates & secrets → Client secrets
  2. Click New client secret
  3. Add a description and choose expiration
  4. Copy the secret value immediately (it won't be shown again)

API Permissions⚓︎

  1. Go to API permissions
  2. Click Add a permission → Microsoft Graph
  3. Select Delegated permissions
  4. Add these permissions:
  5. openid
  6. profile
  7. email
  8. User.Read (selected by default, for retrieving user info)
  9. Click Grant admin consent (if required by your organization)

Step 3: Configure Keycloak⚓︎

  1. Access Keycloak admin console at https://<your-domain>/auth/admin/prokube/console

  2. Go to Identity Providers → Add provider → Microsoft

  3. Configure the provider:

    Field Value
    Alias microsoft
    Display Name Microsoft (shown on login page)
    Client ID From Azure App Registration → Overview
    Client Secret From Step 2
    Prompt select_account
    (Important: Prevents "Admin Approval Needed" errors)
    Tenant ID From Azure App Registration → Overview (Directory ID)
    (Important: Required for Single-Tenant Accounts)

  4. Click Add

Advanced Settings⚓︎

After clicking Add the newly added provider will open in Provider details section.
Go to Advanced Settings section on the right and configure:

Field Value Notes
Scopes openid profile email User.Read Required for retrieving user profile and email from Entra ID
(Defaults to only openid)
Trust Email On Trust email verification from Entra ID
Sync mode import Creates Keycloak users on first login

Click Save.

Step 4: Test the Integration⚓︎

  1. Open a new incognito/private browser window (to avoid existing sessions)
  2. Go to https://<your-domain>/
  3. Click Microsoft on the login page
  4. Sign in with your Entra ID credentials
  5. Verify you can access the prokube dashboard

Note

Keycloak creates a corresponding new Keycloak user on first external IdP login.
The corresponding Keycloak user can be seen on Users page in Keycloak admin console.
The user automatically gets assigned to the pk-user group.
Further role/group assignments can be managed in Keycloak as needed.

Troubleshooting⚓︎

"Admin Approval Needed" Error⚓︎

Cause: Entra ID tenant requires admin consent for new apps.

Solution: 1. In Keycloak, go to Identity Providers → Microsoft → Advanced Settings 2. Set Prompt to select_account 3. Save and try again

Alternatively, have your Azure AD admin grant consent for the app.

User Not in pk-user Group⚓︎

Cause: Default group not configured or user created before configuration.

Solution: 1. Sign in as Keycloak master admin at https://<your-domain>/auth/admin/master/console. Only Keycloak master admins can manage the following realm settings. 2. Go to Manage realms → Select prokube realm 3. Go to Realm Settings → User registration -> Default groups 4. Verify pk-user is set as a default group 5. For existing users that are not in pk-user group, manually add them to pk-user: - Go to Users → Select user → Groups → Join Group → pk-user

"Email Not Verified" Error (500)⚓︎

Cause: Keycloak requires verified emails but Entra ID didn't provide verification status.

Solution: 1. In Keycloak, go to Identity Providers → Microsoft → Advanced Settings 2. Set Trust Email to On 3. Save and have the user try again

"Invalid redirect_uri" Error⚓︎

Cause: Redirect URI mismatch between Azure and Keycloak.

Solution: 1. In Azure Portal, go to App Registration → Authentication 2. Verify the redirect URI matches exactly: 

https://<your-domain>/auth/realms/prokube/broker/microsoft/endpoint
3. Check for trailing slashes or HTTP vs HTTPS mismatches

"AADSTS50194: Application 'xxxxxxxx' is not configured as a multi-tenant application" Azure Error⚓︎

Cause: Azure app is single-tenant but Keycloak is not configured with tenant ID.

Solution: 1. In Keycloak, go to Identity Providers → Microsoft -> General Settings (Opens as default tab) 2. Set Tenant ID to the Directory ID from Azure App Registration → Overview 3. Save and try again

Other Identity Providers⚓︎

Google Workspace⚓︎

Similar setup process:

  1. Create OAuth 2.0 credentials in Google Cloud Console
  2. Add Google identity provider in Keycloak
  3. Configure scopes: openid email profile
  4. Set up claim mappers

Okta⚓︎

  1. Create OIDC application in Okta
  2. Add OpenID Connect v1.0 identity provider in Keycloak
  3. Configure client ID, secret, and issuer URL
  4. Set up claim mappers

Generic OIDC⚓︎

For any OIDC-compliant provider:

  1. In Keycloak, go to Identity Providers → Add provider → OpenID Connect v1.0
  2. Configure:
  3. Authorization URL
  4. Token URL
  5. Client ID and Secret
  6. Default Scopes
  7. Add claim mappers as needed

Security Considerations⚓︎

  1. Use HTTPS everywhere - All redirect URIs must use HTTPS
  2. Rotate client secrets - Set calendar reminders before expiration
  3. Limit scopes - Only request necessary permissions
  4. Monitor logins - Enable Keycloak event logging
  5. Require 2FA - Configure in both Entra ID and Keycloak authentication flows