External Identity Provider - CLI Reference

Overview

External Identity Provider (IdP) integration enables FreeIPA to federate authentication with cloud-based or external OAuth 2.0 and OpenID Connect (OIDC) identity providers. This allows organizations to implement hybrid authentication scenarios where users can authenticate to IPA using credentials managed by external providers like Google Workspace, Microsoft Azure AD, GitHub, Keycloak, or any OAuth2/OIDC-compliant identity system.

External IdP support is particularly valuable for:

Cloud-first organizations: Users with primary identities in cloud providers (Google, Microsoft) can access IPA-integrated resources without maintaining separate IPA passwords.

Contractor/partner access: External collaborators authenticate using their own organization’s identity provider rather than requiring dedicated IPA accounts.

Zero Trust architectures: Centralize authentication in a cloud IdP while using IPA for authorization and resource management.

Mobile device authentication: OAuth 2.0 Device Flow enables authentication on devices with limited input capabilities (IoT devices, kiosks, CLI tools on headless servers).

Single Sign-On (SSO): Users authenticate once to the external IdP and gain access to IPA-protected resources without re-authentication.

FreeIPA implements this integration using the OAuth 2.0 Device Authorization Grant (RFC 8628), also known as Device Flow. This flow is designed for scenarios where the authentication client (IPA-enrolled system) cannot easily display a web browser or capture user input, making it ideal for command-line authentication and headless systems.

OAuth 2.0 and OpenID Connect

OAuth 2.0

OAuth 2.0 is an authorization framework (RFC 6749) that enables applications to obtain limited access to user accounts. In IPA’s context:

Authorization Server: The external identity provider (Google, Azure AD, etc.) Client: FreeIPA server acting on behalf of the user Resource Owner: The user authenticating to IPA Grant Type: Device Authorization Grant (Device Flow)

OAuth 2.0 provides the access token that proves the user authenticated successfully with the external IdP.

OpenID Connect (OIDC)

OpenID Connect is an identity layer built on top of OAuth 2.0 (OIDC Core 1.0). It adds:

ID Token: A JWT (JSON Web Token) containing user identity claims UserInfo Endpoint: Retrieves additional user attributes Standardized Claims: Predefined user attributes (sub, email, name, etc.)

OIDC enables IPA to obtain user identity information from the external IdP, not just authorization.

Device Authorization Grant (Device Flow)

The Device Flow is optimized for devices with limited input/display capabilities:

Device requests authorization: IPA requests a device code from the IdP
User visits verification URL: User navigates to IdP’s verification page on a separate device (phone, workstation)
User enters code: User enters the device code displayed by IPA
User authenticates: User authenticates to the IdP and grants consent
Device polls for token: IPA polls the IdP until user completes authentication
Token issued: IdP issues access token and ID token to IPA
IPA validates: IPA validates tokens and issues Kerberos credentials

This flow separates the authentication UI (external IdP web interface) from the authentication client (IPA CLI or login prompt), making it suitable for servers, IoT devices, and CLI tools.

IdP Configuration Components

Required Parameters

Client ID (--client-id): OAuth 2.0 client identifier registered with the external IdP. This identifies the IPA server to the IdP.

Client Secret (--secret): OAuth 2.0 client secret (password) that authenticates the IPA client to the IdP. Stored encrypted in IPA LDAP.

Authorization Endpoint (--auth-uri): OAuth 2.0 authorization endpoint URL where users authenticate. Example: https://oauth2.googleapis.com/device/code

Token Endpoint (--token-uri): OAuth 2.0 token endpoint URL where IPA exchanges authorization codes for tokens. Example: https://oauth2.googleapis.com/token

Optional Parameters

Device Authorization Endpoint (--dev-auth-uri): Dedicated device authorization endpoint for Device Flow. If not specified, IPA uses --auth-uri.

UserInfo Endpoint (--userinfo-uri): OIDC UserInfo endpoint URL for retrieving user profile information. Example: https://www.googleapis.com/oauth2/v1/userinfo

JWKS Endpoint (--keys-uri): JSON Web Key Set endpoint URL for validating ID token signatures. Example: https://www.googleapis.com/oauth2/v3/certs

Issuer URL (--issuer-url): OIDC issuer identifier for token validation. Must match the iss claim in ID tokens.

Scope (--scope): OAuth 2.0 scopes requested from the IdP. Typical scopes: openid email profile. Multiple scopes separated by spaces.

IdP User ID Attribute (--idp-user-id): Attribute in the UserInfo response that uniquely identifies the user. Default: sub (OIDC subject identifier). Could be email, upn, or custom attribute depending on IdP.

Provider Templates

IPA includes predefined templates for popular identity providers:

github: GitHub OAuth google: Google OAuth 2.0 microsoft: Microsoft Azure AD / Entra ID keycloak: Red Hat Keycloak/RH-SSO okta: Okta oidc: Generic OIDC provider

Templates pre-configure endpoints and defaults for these providers, requiring only client ID, secret, and provider-specific parameters like organization or base URL.

Authentication Flow

User Perspective

sequenceDiagram
    participant User
    participant IPA as IPA Server
    participant Browser as Browser/Phone
    participant IdP as External IdP

    User->>IPA: 1. kinit alice
    Note over IPA: Initiate Device Flow
    IPA-->>User: 2. Device Flow prompt<br/>"Visit URL: ABCD-1234"

    User->>Browser: 3. Open browser & navigate to URL
    User->>Browser: 4. Enter code: ABCD-1234
    Browser->>IdP: 5. Redirect to IdP

    User->>IdP: 6. Authenticate<br/>(username + password, SSO, or biometric)
    User->>IdP: 7. Grant consent (if first time)

    IdP-->>Browser: 8. Success: "You may close this window"
    Note over Browser,IdP: User sees confirmation

    IdP->>IPA: (IdP notifies IPA via polling)
    Note over IPA: Generate Kerberos credentials
    IPA-->>User: 9. Kerberos TGT issued<br/>"Welcome alice@REALM"

Flow Steps:

User attempts to authenticate to IPA (e.g., kinit alice)
IPA prompts: “Visit https://oauth.provider.com/device and enter code: ABCD-1234”
User opens URL on phone/workstation, enters code
User authenticates to external IdP (Google, Azure AD, etc.)
User grants consent (if first time)
User sees “Success, you may close this window”
IPA receives token and issues Kerberos TGT to user

Technical Flow

sequenceDiagram
    participant Client as Client<br/>(kinit)
    participant KDC as IPA KDC
    participant LDAP as LDAP<br/>Directory
    participant IdP as External IdP
    participant JWKS as IdP JWKS/<br/>UserInfo

    Client->>KDC: 1. AS-REQ (alice)
    Note over KDC: Authentication request received

    KDC->>LDAP: 2. Query user (find IdP link)
    LDAP-->>KDC: ipaidpsub: alice@example.com<br/>ipaidpconfiglink: cn=google-idp,...

    KDC->>IdP: 3. POST /device_authorization<br/>client_id, scope=openid profile email
    IdP-->>KDC: 4. Device codes response<br/>device_code=abc123<br/>user_code=ABCD-1234<br/>verification_uri=https://...

    KDC-->>Client: 5. KRB-ERROR OTP_DEVICE_FLOW<br/>"Visit URL and enter code..."
    Note over Client: User sees verification URL and code

    rect rgb(240, 240, 240)
        Note over Client,IdP: User authenticates on separate device
    end

    loop Polling (every 5 seconds)
        KDC->>IdP: 6. POST /token<br/>grant_type=device_code<br/>device_code=abc123
        IdP-->>KDC: authorization_pending
    end

    Note over IdP: User completes authentication

    KDC->>IdP: POST /token (polling continues)
    IdP-->>KDC: 7. Token response<br/>access_token=eyJ...<br/>id_token=eyJ... (JWT)

    KDC->>JWKS: 8. GET /.well-known/jwks.json
    JWKS-->>KDC: 9. JWKS response<br/>{keys: [{kid, kty, n, e}]}

    Note over KDC: 10. Verify ID token signature<br/>Check: iss, aud, exp, nbf<br/>Extract: sub (subject ID)

    KDC->>JWKS: 11. GET /userinfo<br/>Authorization: Bearer eyJ...
    JWKS-->>KDC: 12. UserInfo response<br/>{sub, email, name, ...}

    KDC->>LDAP: 13. Map IdP user<br/>Find: ipaidpsub=alice@example.com<br/>AND ipaidpconfiglink=cn=google-idp,...
    LDAP-->>KDC: alice (uid=1001)

    Note over KDC: 14. Generate TGT for alice@REALM<br/>(Kerberos ticket)

    KDC-->>Client: 15. AS-REP<br/>TGT + session key (encrypted)
    Note over Client: ✓ Authentication successful

Detailed Technical Steps:

IPA initiates Device Flow: Client sends AS-REQ, IPA calls IdP’s device authorization endpoint
IPA receives device codes: Gets device_code (for polling) and user_code (for user entry)
IPA displays verification URL: Returns KRB-ERROR to client with URL and user code
IPA polls token endpoint: Repeatedly POST to /token using device code (every 5 seconds)
User completes authentication: On separate device, authenticates to IdP and authorizes the device code
IdP issues tokens: Returns access_token (for API calls) and id_token (JWT for identity)
IPA validates ID token: Fetches JWKS (public keys), verifies JWT signature, checks issuer/audience/expiry
IPA retrieves user info: (Optional) Calls UserInfo endpoint with access token for additional claims
IPA maps to local user: Extracts the user identifier from the ID token (based on the attribute specified in the IdP configuration), searches LDAP for a user entry with matching ipaidpsub value and ipaidpconfiglink pointing to this IdP configuration
IPA issues Kerberos credentials: Generates TGT for the matched IPA user, returns AS-REP to client

User Mapping

For external IdP authentication to work, IPA users must be linked to their external IdP identities through the ipaIdpUser objectclass and related attributes.

IdP User Objectclass and Attributes

The ipaIdpUser objectclass enables external IdP authentication for a user entry. When this objectclass is added to a user, the following attributes are used:

ipaidpsub (required, single-value)

Contains the subject identifier (sub) from the IdP token
This is the unique user identifier issued by the external identity provider
Must match the sub claim in the ID token returned by the IdP during authentication
Example: alice@example.com, 123456789, github|12345

ipaidpconfiglink (required, single-value)

Points to the IdP configuration object (DN) that defines which external provider to use
Links the user to a specific IdP configuration created with ipa idp-add
Example: cn=google-idp,cn=idp,dc=example,dc=com

How Token Attribute Mapping Works: The IdP configuration object (pointed to by ipaidpconfiglink) defines which token attribute contains the user identifier via the --idp-user-id parameter. During authentication:

IPA receives the ID token from the external IdP
IPA extracts the value from the token attribute specified in the IdP configuration
IPA searches for a user entry where ipaidpsub matches this value and ipaidpconfiglink points to the same IdP configuration

Setting Up User Mapping

# Link IPA user alice to Google identity
# Assumes IdP configuration 'google-idp' exists and uses 'email' as the user ID attribute
$ ipa user-mod alice \
  --user-auth-type=idp \
  --idp=google-idp \
  --idp-user-id=alice@example.com

# This adds the ipaIdpUser objectclass and sets:
# - ipaidpsub: alice@example.com
# - ipaidpconfiglink: cn=google-idp,cn=idp,dc=example,dc=com

# Link user bob to GitHub identity
$ ipa user-mod bob \
  --user-auth-type=idp \
  --idp=github-idp \
  --idp-user-id=bob

# Note: Each user can only be linked to ONE external IdP
# The ipaidpsub attribute is single-value, not multi-value

Automatic User Provisioning

IPA does not automatically create users based on external IdP authentication. Users must exist in IPA first and be manually linked to external IdP identities. This ensures:

IPA maintains authoritative user records
Authorization policies (RBAC, HBAC, sudo) remain under IPA control
External IdP is used only for authentication, not user lifecycle

Examples

Add Google Identity Provider

# Register Google OAuth 2.0 configuration
$ ipa idp-add google-idp \
  --provider=google \
  --client-id="123456789-abc123def456.apps.googleusercontent.com" \
  --secret

  Enter client secret: ********

  IdP reference name: google-idp
  Provider: google
  Client identifier: 123456789-abc123def456.apps.googleusercontent.com
  Authorization URI: https://accounts.google.com/o/oauth2/v2/auth
  Device authorization URI: https://oauth2.googleapis.com/device/code
  Token URI: https://oauth2.googleapis.com/token
  User info URI: https://www.googleapis.com/oauth2/v1/userinfo

Add GitHub Identity Provider

# Register GitHub OAuth application
$ ipa idp-add github-idp \
  --provider=github \
  --client-id="Iv1.abcdef123456" \
  --secret

  Enter client secret: ********

  IdP reference name: github-idp
  Provider: github
  Authorization URI: https://github.com/login/oauth/authorize
  Token URI: https://github.com/login/oauth/access_token

Add Azure AD (Microsoft) Identity Provider

# Register Azure AD application
$ ipa idp-add azure-idp \
  --provider=microsoft \
  --organization="contoso.onmicrosoft.com" \
  --client-id="12345678-1234-1234-1234-123456789abc" \
  --secret

  Enter client secret: ********

  IdP reference name: azure-idp
  Provider: microsoft
  Organization: contoso.onmicrosoft.com

Add Keycloak Identity Provider

# Register Keycloak realm client
$ ipa idp-add keycloak-idp \
  --provider=keycloak \
  --organization="myrealm" \
  --base-url="https://keycloak.example.com" \
  --client-id="freeipa-client" \
  --secret

  Enter client secret: ********

Add Generic OIDC Provider

# Register custom OIDC provider with explicit endpoints
$ ipa idp-add custom-idp \
  --client-id="ipa-client-12345" \
  --auth-uri="https://idp.example.com/oauth2/authorize" \
  --dev-auth-uri="https://idp.example.com/oauth2/device/authorize" \
  --token-uri="https://idp.example.com/oauth2/token" \
  --userinfo-uri="https://idp.example.com/oauth2/userinfo" \
  --keys-uri="https://idp.example.com/oauth2/keys" \
  --issuer-url="https://idp.example.com" \
  --scope="openid email profile" \
  --idp-user-id="email" \
  --secret

  Enter client secret: ********

Add Okta Identity Provider

# Register Okta application
$ ipa idp-add okta-idp \
  --provider=okta \
  --organization="dev-123456" \
  --base-url="https://dev-123456.okta.com" \
  --client-id="0oa123abc456DEF789" \
  --secret

List All Identity Providers

# View all configured external IdPs
$ ipa idp-find
  3 IdP references matched
  IdP reference name: google-idp
  Provider: google
  IdP reference name: azure-idp
  Provider: microsoft
  IdP reference name: github-idp
  Provider: github

Show IdP Details

# View specific IdP configuration
$ ipa idp-show google-idp
  IdP reference name: google-idp
  Provider: google
  Client identifier: 123456789-abc123def456.apps.googleusercontent.com
  Authorization URI: https://accounts.google.com/o/oauth2/v2/auth
  Device authorization URI: https://oauth2.googleapis.com/device/code
  Token URI: https://oauth2.googleapis.com/token
  User info URI: https://www.googleapis.com/oauth2/v1/userinfo
  Scope: openid email profile

Modify IdP (Update Secret)

# Update client secret (e.g., after rotation)
$ ipa idp-mod google-idp --secret
  Enter client secret: ********

  Updated IdP reference "google-idp"

Modify IdP (Update Scopes)

# Request additional scopes
$ ipa idp-mod google-idp --scope="openid email profile groups"

Delete Identity Provider

# Remove IdP configuration
$ ipa idp-del github-idp
  Deleted IdP reference "github-idp"

Link User to External IdP

# Associate IPA user with Google identity
$ ipa user-mod alice \
  --idp=google-idp \
  --idp-user-id="alice@example.com"

# Associate user with multiple IdPs
$ ipa user-mod bob \
  --idp=google-idp --idp-user-id="bob@example.com" \
  --idp=azure-idp --idp-user-id="bob@contoso.onmicrosoft.com"

Authenticate Using External IdP

# User authenticates via external IdP
$ kinit alice
  Please visit https://oauth2.googleapis.com/device
  And enter the code: ABCD-1234

  # User completes authentication on separate device

  # After user approves, kinit succeeds
  alice@EXAMPLE.COM's Kerberos credentials obtained

Best Practices

Security Configuration

Client secret protection: Store client secrets securely. IPA encrypts secrets in LDAP, but ensure IdP registration portals use strong access controls.

Scope minimization: Request only necessary OAuth scopes. Typical minimum: openid email profile. Avoid requesting excessive permissions from IdPs.

HTTPS required: All IdP endpoints must use HTTPS. OAuth/OIDC over HTTP is insecure and typically blocked by IdPs.

Token validation: Ensure JWKS endpoint (--keys-uri) and issuer URL (--issuer-url) are configured for proper ID token signature validation.

IdP registration best practices: When registering IPA as OAuth client with external IdPs, use organization-specific client names (e.g., “Acme Corp FreeIPA”) for audit trails.

User Management

Pre-create users: IPA users must exist before external IdP authentication. External IdP doesn’t trigger user provisioning.

Unique IdP user IDs: Ensure IdP user IDs (email, username, subject) are unique and stable. Changing IdP user IDs breaks authentication.

Multi-IdP support: Users can link to multiple IdPs (Google personal + work Azure AD). This supports BYOD and multi-tenant scenarios.

Document mappings: Maintain documentation of which IPA users are linked to which external IdPs for support and auditing.

Fallback authentication: Maintain IPA passwords for users with external IdP links to enable authentication if IdP is unavailable.

Operational Practices

IdP availability: External IdP authentication requires network connectivity to IdP endpoints. Plan for IdP outages.

Certificate validation: Ensure IPA servers trust the TLS certificates used by IdP endpoints. Add CA certificates to system trust if needed.

Monitoring: Monitor external IdP authentication success/failure rates. High failure rates may indicate IdP configuration issues.

Secret rotation: Periodically rotate OAuth client secrets. Update IPA IdP configuration with new secrets.

Provider templates vs manual: Use provider templates (--provider=google) when available for automatic endpoint configuration and future updates.

Testing

Test in non-production: Register test OAuth clients with IdPs and validate authentication flow before production deployment.

Multiple providers: If supporting multiple IdPs (Google, Azure AD, Keycloak), test each independently.

Error handling: Test error scenarios (wrong code, expired token, network timeout) to understand failure modes.

User experience: Have actual users test external IdP authentication and provide feedback on UX.

Integration Points

Users

Users must have IdP mappings configured:

Objectclass: ipaIdpUser - Enables external IdP authentication for the user Attributes:

ipaidpsub (single-value, required) - Contains the subject identifier from the IdP token
ipaidpconfiglink (single-value, required) - Points to the IdP configuration object DN

Configuration: Set via user-mod --user-auth-type=idp --idp=<name> --idp-user-id=<id> Limitation: Each user can only be linked to ONE external IdP (ipaidpsub is single-value)

Commands: user-mod, user-show

Kerberos

External IdP authentication integrates with Kerberos:

TGT issuance: Successful external IdP authentication results in Kerberos TGT Principal mapping: IdP user ID maps to IPA user, then to Kerberos principal SSO: TGT enables SSO to all Kerberos-integrated services

SSSD

SSSD on IPA clients handles OAuth Device Flow:

Client-side flow: SSSD initiates Device Flow, displays verification URL/code Token handling: SSSD manages token exchange with IdP Credential caching: SSSD caches Kerberos credentials obtained via IdP auth

OAuth Client Registration

Before configuring IdP in IPA, register IPA as OAuth client:

Google: Google Cloud Console → Credentials → OAuth 2.0 Client IDs Azure AD: Azure Portal → App Registrations → New registration GitHub: GitHub Settings → Developer settings → OAuth Apps Keycloak: Keycloak Admin → Clients → Create

Each provider requires:

Application name (e.g., “Acme Corp FreeIPA”)
Redirect URI: Typically not required for Device Flow
Requested scopes/permissions

Provider issues:

Client ID
Client Secret

These values are used in ipa idp-add.

External IdP Trust

Unlike Active Directory trusts (which are bidirectional Kerberos trusts), external IdP integration is unidirectional:

IPA trusts IdP: IPA accepts authentication from IdP IdP doesn’t trust IPA: IdP knows nothing about IPA (just another OAuth client) Authentication only: IdP provides authentication; IPA provides authorization

See trust topic for AD trust comparison.

Federation vs Trust

External IdP (federation): OAuth/OIDC authentication with cloud identity providers

Use for: Cloud identities, contractors, partners, Zero Trust architectures
Protocol: OAuth 2.0 / OpenID Connect
Direction: One-way (IPA trusts IdP)

Active Directory Trust: Kerberos cross-realm trust with on-premise AD

Use for: Hybrid on-premise/IPA environments
Protocol: Kerberos
Direction: Two-way or one-way Kerberos trusts

Both can coexist in same IPA deployment.

Troubleshooting

Common Issues

Device code not working: User may have mistyped code. Codes are case-sensitive and time-limited (typically 15 minutes).

Token validation failure: Check --issuer-url and --keys-uri configuration. ID token iss claim must match issuer URL.

User not found: IPA user must exist and have correct ipaidpsub and ipaidpconfiglink values. Verify with ipa user-show alice --all | grep ipaidp.

Network connectivity: Ensure IPA server can reach IdP endpoints (authorization, token, userinfo, keys). Check firewalls and DNS.

TLS certificate errors: IdP endpoints must have valid TLS certificates trusted by IPA server. Add IdP’s CA certificate to system trust if needed.

Scope issues: IdP may require specific scopes for Device Flow. Check IdP documentation for required scopes (typically openid email profile).

Client not authorized: Ensure OAuth client is properly registered with IdP and Device Flow grant type is enabled.

Use Cases

1. Enabling Google Workspace Authentication for Cloud-First Organization

Organization migrating to cloud-first infrastructure wants employees to authenticate to IPA-protected resources using their Google Workspace credentials.

# Register Google OAuth 2.0 client in Google Cloud Console
# Obtain client ID and secret

# Configure Google IdP in FreeIPA
ipa idp-add google-workspace \
  --provider=google \
  --client-id="987654321-xyz789abc123.apps.googleusercontent.com" \
  --secret

# Link existing IPA users to Google identities
ipa user-mod alice --idp=google-workspace --idp-user-id="alice@company.com"
ipa user-mod bob --idp=google-workspace --idp-user-id="bob@company.com"

# Users can now authenticate via Google
# On IPA client:
kinit alice
# Output: Please visit https://oauth2.googleapis.com/device
#         And enter the code: WXYZ-5678
# User opens URL on phone, logs into Google, approves
# kinit completes and issues Kerberos TGT

Result: Employees authenticate once to Google Workspace and gain access to all IPA-protected Linux servers, databases, and services without maintaining separate IPA passwords.

2. Contractor Access via GitHub Authentication

Development team needs to grant contractors access to IPA-managed development servers using their GitHub accounts rather than creating long-term IPA credentials.

# Register OAuth App in GitHub Developer Settings
# Enable Device Flow support

# Configure GitHub IdP
ipa idp-add github-contractors \
  --provider=github \
  --client-id="Iv1.abc123def456" \
  --secret

# Create IPA user for contractor (no password required)
ipa user-add contractor1 --first=Jane --last=Smith

# Link to GitHub identity
ipa user-mod contractor1 \
  --idp=github-contractors \
  --idp-user-id="janesmith"

# Configure HBAC to restrict access
ipa hbacrule-add contractor-devservers
ipa hbacrule-add-user contractor-devservers --users=contractor1
ipa hbacrule-add-host contractor-devservers --hostgroups=dev-servers
ipa hbacrule-add-service contractor-devservers --hbacsvcs=sshd

Result: Contractors authenticate using GitHub credentials (which they already manage with MFA). No shared passwords, easy revocation (delete IPA user or remove GitHub link), and external identity provider manages authentication security.

3. Multi-IdP Hybrid Identity for BYOD Users

Organization supports both corporate Azure AD and personal Google accounts for employees who use personal devices for work (BYOD scenario).

# Configure corporate Azure AD
ipa idp-add azure-corporate \
  --provider=microsoft \
  --organization="contoso.onmicrosoft.com" \
  --client-id="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \
  --secret

# Configure personal Google
ipa idp-add google-personal \
  --provider=google \
  --client-id="123456-personal.apps.googleusercontent.com" \
  --secret

# Link user to both IdPs
ipa user-mod alice \
  --idp=azure-corporate --idp-user-id="alice@contoso.com" \
  --idp=google-personal --idp-user-id="alice.personal@gmail.com"

# User can authenticate via either provider
# From corporate laptop:
kinit alice
# Uses Azure AD corporate identity

# From personal device:
kinit alice
# Uses Google personal identity

Result: Single IPA account supports multiple external identities, enabling flexible authentication from corporate or personal devices while maintaining unified authorization policies.

4. Zero Trust Architecture with Okta as Central IdP

Implementing Zero Trust security model where all authentication flows through Okta (including MFA), while IPA manages authorization and resource access.

# Register Native Application in Okta
# Enable Device Authorization Grant

# Configure Okta IdP
ipa idp-add okta-zerotrust \
  --provider=okta \
  --organization="dev-123456" \
  --base-url="https://dev-123456.okta.com" \
  --client-id="0oa9876xyz123ABC" \
  --secret

# Link all users to Okta
for user in $(ipa user-find --raw --pkey-only | grep 'uid:' | awk '{print $2}'); do
  ipa user-mod "$user" \
    --idp=okta-zerotrust \
    --idp-user-id="${user}@company.com"
done

# Disable IPA password authentication (optional, high-security)
# All users must authenticate via Okta which enforces MFA

Result: Centralized authentication through Okta with mandatory MFA, while IPA provides RBAC, HBAC, sudo rules, and Kerberos SSO to resources. Separates authentication (Okta) from authorization (IPA).

5. Keycloak Integration for Multi-Realm Federation

Organization uses Keycloak to federate multiple identity sources (LDAP, SAML, social logins) and wants IPA to accept authentication from any Keycloak-federated identity.

# Create client in Keycloak realm
# Client Protocol: openid-connect
# Access Type: confidential
# Enable: Direct Access Grants, Standard Flow, Device Flow

# Configure Keycloak IdP in FreeIPA
ipa idp-add keycloak-federation \
  --provider=keycloak \
  --organization="production-realm" \
  --base-url="https://sso.company.com" \
  --client-id="freeipa-client" \
  --scope="openid email profile groups" \
  --secret

# Map IPA users to Keycloak usernames
ipa user-mod alice --idp=keycloak-federation --idp-user-id="alice"
ipa user-mod bob --idp=keycloak-federation --idp-user-id="bob"

# Users authenticate through Keycloak, which federates to backend IdPs
kinit alice
# Keycloak may prompt for LDAP, Google, or GitHub depending on user preference

Result: IPA integrates with Keycloak’s identity brokering, supporting authentication from any identity source Keycloak federates (corporate LDAP, SAML IdPs, social logins) through a single IdP configuration.

6. Custom OIDC Provider Integration for Legacy System

Integrating IPA with a custom-built legacy OIDC provider that doesn’t match standard templates.

# Discover OIDC endpoints from provider's .well-known configuration
curl https://legacy-idp.company.com/.well-known/openid-configuration

# Configure custom IdP with explicit endpoints
ipa idp-add legacy-system \
  --client-id="ipa-production-12345" \
  --auth-uri="https://legacy-idp.company.com/oauth/authorize" \
  --dev-auth-uri="https://legacy-idp.company.com/oauth/device/authorize" \
  --token-uri="https://legacy-idp.company.com/oauth/token" \
  --userinfo-uri="https://legacy-idp.company.com/oauth/userinfo" \
  --keys-uri="https://legacy-idp.company.com/oauth/keys" \
  --issuer-url="https://legacy-idp.company.com" \
  --scope="openid email profile employee_id" \
  --idp-user-id="employee_id" \
  --secret

# Link users using employee ID from legacy system
ipa user-mod alice --idp=legacy-system --idp-user-id="EMP001234"

Result: Successfully integrates with non-standard OIDC provider by manually configuring all endpoints and using custom user ID attribute (employee_id) for user mapping.

7. Rotating OAuth Client Secrets

Security policy requires rotating OAuth client secrets every 90 days across all external IdP integrations.

# Generate new client secret in Google Cloud Console
# Update secret in IPA
ipa idp-mod google-workspace --secret
# Enter client secret: ********

# Verify secret update
ipa idp-show google-workspace
# Client identifier shows but secret is not displayed (encrypted)

# Test authentication with new secret
kinit alice
# Should succeed with new secret

# Repeat for all configured IdPs
ipa idp-find --pkey-only
# For each IdP, regenerate secret in provider console and update in IPA

# Document rotation in security log
echo "$(date): Rotated OAuth secrets for all IdPs" >> /var/log/idp-secret-rotation.log

Result: OAuth client secrets rotated without service disruption. Users continue authenticating seamlessly with updated credentials.

8. Troubleshooting Failed Azure AD Authentication

User cannot authenticate via Azure AD IdP, receiving “User not found” errors despite correct IdP mapping.

# Verify IdP configuration
ipa idp-show azure-corporate --all
# Check authorization URI, token URI, userinfo URI

# Verify user mapping
ipa user-show alice --all | grep ipaidp
# Should show:
#   ipaidpsub: alice@contoso.onmicrosoft.com
#   ipaidpconfiglink: cn=azure-corporate,cn=idp,dc=example,dc=com

# Test network connectivity to Azure endpoints
curl -I https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration
# Should return 200 OK

# Check IdP user ID attribute configuration
ipa idp-show azure-corporate | grep "IdP user ID attribute"
# Default is 'sub', but Azure may use 'oid' or 'upn'

# If attribute mismatch, update IdP configuration
ipa idp-mod azure-corporate --idp-user-id="upn"

# Update user mapping to match Azure UPN
ipa user-mod alice --idp=azure-corporate --idp-user-id="alice@contoso.onmicrosoft.com"

# Test authentication again
kinit alice
# Should now succeed

Result: Identified IdP user ID attribute mismatch between FreeIPA configuration (expecting sub) and Azure AD (using upn). Corrected configuration enables successful authentication.

9. Implementing Scope-Based Access Control

Organization wants to request additional OAuth scopes from Google to obtain group memberships and use them for dynamic HBAC rule evaluation.

# Update Google IdP to request groups scope
ipa idp-mod google-workspace --scope="openid email profile groups"

# Verify Google Cloud Console OAuth consent screen includes groups scope

# Configure Google Workspace Admin to share group memberships
# (Required in Google Admin Console → Security → API Permissions)

# Test that groups are returned in UserInfo
kinit alice
# After successful authentication, check IPA logs for UserInfo response

# Note: Current FreeIPA version stores IdP groups in user attributes
# but does not automatically use them for HBAC evaluation
# Custom integration or future IPA versions may support this

# Alternative: Periodic sync from Google groups to IPA groups
# Use Google Directory API to sync groups to IPA

Result: Additional scopes requested from Google IdP. While FreeIPA currently stores this information, automatic group-based authorization requires custom integration or future IPA enhancements.

10. Emergency Fallback During IdP Outage

External Google IdP experiences an outage, and users cannot authenticate. Administrators need to enable emergency fallback authentication.

# Verify IdP is unreachable
curl -I https://oauth2.googleapis.com/device/code
# Connection timeout or error

# Users with IPA passwords can still authenticate
kinit alice
# If alice has IPA password set, authentication succeeds
# If alice only has IdP auth configured, authentication fails

# Emergency: Set temporary IPA passwords for critical users
ipa user-mod alice --password
# Enter password: ********
# User must change password on first login

# Notify users to use kinit with password
# Or SSH to IPA-enrolled systems (SSSD tries IPA password after IdP failure)

# Once IdP is restored, users can resume IdP authentication
# IPA password remains as fallback

# To enforce IdP-only after recovery (remove fallback):
ipa user-mod alice --password-expiration=$(date -d '+1 day' +%Y%m%d%H%M%SZ)
# Forces password expiration, requiring IdP authentication

Result: Emergency IPA password fallback enables critical users to authenticate during IdP outage. Dual authentication methods provide resilience against external provider unavailability.

Security Considerations

Client Secret Protection

OAuth client secrets are sensitive credentials that grant access to authenticate users via the external IdP. FreeIPA encrypts these secrets in LDAP using IPA’s secret encryption mechanism, but they remain visible to IPA administrators with appropriate privileges. Ensure IdP registration portals (Google Cloud Console, Azure Portal, etc.) use strong access controls and MFA to prevent unauthorized client creation or secret exposure. Rotate client secrets periodically (recommended: every 90 days) to limit exposure window if secrets are compromised. Never commit client secrets to version control or share them via unencrypted channels.

Scope Minimization and Over-Permissioning

Requesting excessive OAuth scopes grants IPA unnecessary access to user data from the external IdP. Follow principle of least privilege: request only scopes required for authentication and user identification. Typical minimum: openid email profile. Avoid scopes like https://www.googleapis.com/auth/admin.directory.user (full Google Workspace admin access) unless specifically required and approved by security review. Over-scoped clients create compliance risks (GDPR, HIPAA) if IPA gains access to sensitive user data from external IdPs without business justification.

IdP User ID Stability and Account Takeover

The IdP user ID attribute (--idp-user-id) permanently links the IPA user to the external identity. If this attribute changes (e.g., email address reassignment), a different external user could gain access to the original IPA account, leading to account takeover. Use immutable attributes when available: sub (OIDC subject identifier), oid (Azure object ID), user_id (GitHub user ID) rather than email which may be reassigned. Document the IdP user ID attribute choice and validate that the external IdP guarantees uniqueness and non-reusability for the chosen attribute.

Token Validation and Signature Verification

FreeIPA validates ID tokens by verifying JWT signatures using the IdP’s public keys from the JWKS endpoint (--keys-uri). If --keys-uri is not configured or points to an attacker-controlled endpoint, IPA may accept forged ID tokens, enabling authentication bypass. Always configure --keys-uri and --issuer-url for OIDC providers. Ensure these endpoints use HTTPS and valid TLS certificates. IPA validates the iss (issuer) and aud (audience) claims in ID tokens, preventing token substitution attacks where tokens from one IdP are used with a different IPA IdP configuration.

Man-in-the-Middle Attacks on IdP Endpoints

All communication between FreeIPA and external IdPs (authorization, token, userinfo, keys endpoints) occurs over HTTPS. If an attacker performs a man-in-the-middle (MITM) attack and IPA does not properly validate TLS certificates, the attacker can intercept OAuth authorization codes, access tokens, and client secrets. Ensure IPA servers trust the CA certificates for IdP endpoints (typically public CAs like DigiCert, Let’s Encrypt). For internal IdPs (Keycloak), add the internal CA to the system trust store (update-ca-trust on RHEL/CentOS). Monitor for TLS certificate validation errors in IPA logs, which may indicate MITM attempts or misconfigured certificates.

Device Flow Phishing and Code Interception

OAuth Device Flow displays a verification URL and user code to the user, who enters them in a web browser to authenticate. Attackers can exploit this by presenting fake verification URLs or intercepting user codes through social engineering (“Enter this code at fake-google.com”). Educate users to verify they’re visiting legitimate IdP domains (accounts.google.com, login.microsoftonline.com) before entering codes. IdP providers implement code expiration (typically 15 minutes) and rate limiting to mitigate abuse. Users should never share device codes via email, chat, or screenshots, as this enables code hijacking.

Lack of Automatic User Deprovisioning

FreeIPA does not automatically disable or delete IPA user accounts when the corresponding external IdP account is deactivated. If an employee leaves the company and their Google Workspace account is disabled, they cannot authenticate via Google IdP, but their IPA account remains active. If the user had an IPA password set as fallback, they can still authenticate. Organizations must implement external user lifecycle management: synchronize IdP account status to IPA or explicitly disable IPA accounts during offboarding. Alternatively, remove IPA password fallback for IdP-only users to ensure deactivation in the external IdP prevents all IPA access.

IdP Availability as Authentication Dependency

External IdP authentication creates a hard dependency on the availability of the external provider and network connectivity to IdP endpoints. If Google OAuth is unavailable (outage, network partition, firewall misconfiguration), users cannot authenticate even if FreeIPA servers are fully operational. This creates a single point of failure for authentication. Mitigation strategies: maintain IPA password fallback for critical administrators, implement monitoring for IdP endpoint reachability, and design runbooks for emergency password issuance during extended IdP outages. For high-availability environments, consider multi-IdP configurations where users can authenticate via multiple providers.

Authorization Endpoint Spoofing

The --auth-uri and --dev-auth-uri parameters define where users are directed to authenticate. If these URLs are modified by an attacker (requires IPA admin access), users could be redirected to phishing sites that mimic the legitimate IdP. The attacker captures credentials and then proxies authentication to the real IdP, appearing transparent to the user. Protect IdP configuration with strict RBAC: limit idp-mod permissions to senior administrators only. Use IPA’s delegated permission system to separate IdP configuration from general user management. Audit IdP modifications using ipa-audit logs to detect unauthorized configuration changes.

Client ID and Redirect URI Validation

OAuth 2.0 security depends on the IdP validating that authorization requests come from the registered client (identified by Client ID). For Device Flow, redirect URIs are not typically used, but some IdPs may require them for client registration. Ensure the OAuth client registered with the external IdP is configured with “Device Flow” grant type enabled and no redirect URIs (or appropriate redirect URIs if required). Misconfigured clients may allow authorization code interception if an attacker registers a malicious client with the same ID but different redirect URIs. Always register OAuth clients with organization-controlled accounts (not individual developer accounts) to prevent client ownership issues.

Multi-Tenant IdP Isolation

For multi-tenant IdPs like Azure AD or Keycloak, ensure the IdP configuration isolates authentication to the correct tenant/organization. Azure AD requires --organization parameter (tenant ID or domain) to prevent cross-tenant authentication where a user from TenantA could authenticate to IPA configured for TenantB if organization isolation is not enforced. Keycloak similarly requires --organization (realm name) to isolate authentication to specific realms. Misconfigured tenant settings may allow authentication from unintended organizations, bypassing intended access controls.

Insufficient Monitoring of IdP Authentication Events

External IdP authentication bypasses traditional IPA password authentication logging, potentially creating audit blind spots. Failed IdP authentication attempts may only be logged in the external IdP’s audit logs (Google Workspace audit, Azure AD sign-in logs), not in FreeIPA logs. Organizations must aggregate logs from both IPA and external IdPs to maintain comprehensive audit trails. Configure SIEM integration to correlate IPA Kerberos ticket issuance with external IdP authentication events. Monitor for anomalies: successful IdP authentication from unusual locations, multiple failed authentication attempts, or IdP authentication for users expected to use password authentication.

Troubleshooting

IdP Authentication Fails with “User not found”

Symptoms: User completes external IdP authentication successfully, but IPA returns “User not found” error. Kerberos TGT is not issued.

Diagnosis:

# Verify IPA user exists
ipa user-show alice

# Check IdP user mapping
ipa user-show alice --all | grep ipaidp
# Should show:
#   ipaidpsub: <user-identifier-from-token>
#   ipaidpconfiglink: cn=<idp-name>,cn=idp,dc=example,dc=com

# Verify objectclass is set
ipa user-show alice --all | grep objectClass
# Should include: ipaIdpUser

# Check IPA logs for user mapping failure
journalctl -u ipa -n 100 | grep -i "idp\|oauth"

Resolution: Ensure user has the ipaIdpUser objectclass and correct ipaidpsub value matching the user identifier from the IdP token. The ipaidpconfiglink must point to the correct IdP configuration DN. The ipaidpsub value must match the attribute specified in the IdP configuration’s --idp-user-id parameter (e.g., if IdP uses email, the token’s email claim must match ipaidpsub). Use ipa user-mod alice --user-auth-type=idp --idp=<idp-name> --idp-user-id=<id> to set correct mapping.

Device Code Expired During Authentication

Symptoms: User enters device code on IdP verification page, but receives “Code expired” error. IPA returns “Authorization pending” timeout.

Diagnosis:

# Device codes typically expire after 15 minutes
# Check if user delayed entering code

# Verify IdP code expiration settings
# (Check IdP provider documentation for code_lifetime)

# Retry authentication
kinit alice
# Note the timestamp when code is displayed
# Complete authentication within code lifetime

Resolution: Device codes are time-limited (typically 15 minutes). Ensure users enter codes promptly after receiving them. For automated systems, implement retry logic for expired codes. If codes consistently expire too quickly, check if IdP allows configuring longer expiration times.

TLS Certificate Validation Failure

Symptoms: IdP authentication fails with certificate validation errors. Logs show “SSL certificate problem” or “certificate verify failed”.

Diagnosis:

# Test TLS connection to IdP endpoints
openssl s_client -connect oauth2.googleapis.com:443 -showcerts

# Check if IPA server trusts IdP's CA
curl -v https://oauth2.googleapis.com/device/code
# Look for "SSL certificate verify ok" in output

# Check system trust store
trust list | grep -i "google\|microsoft\|github"

Resolution: IdP endpoints must use valid TLS certificates trusted by IPA server. For public IdPs (Google, Microsoft, GitHub), ensure system CA bundle is up-to-date: dnf update ca-certificates (RHEL/CentOS) or apt update ca-certificates (Debian/Ubuntu). For internal IdPs (Keycloak), add internal CA to system trust: cp internal-ca.crt /etc/pki/ca-trust/source/anchors/ && update-ca-trust.

Wrong IdP User ID Attribute

Symptoms: Authentication fails even with correct user mapping. UserInfo endpoint returns different attribute than configured.

Diagnosis:

# Check configured IdP user ID attribute
ipa idp-show google-idp | grep "IdP user ID attribute"
# Default: sub

# Test UserInfo endpoint response
# (Requires temporary access token - complex, use IdP testing tools)

# Common attributes by provider:
# Google: sub, email
# Azure AD: oid, upn, email
# GitHub: id, login
# Keycloak: sub, preferred_username, email

Resolution: Verify the IdP user ID attribute configured in IPA matches the attribute returned by the IdP’s UserInfo endpoint. Update if needed: ipa idp-mod google-idp --idp-user-id=email. Update user mappings to match: ipa user-mod alice --idp=google-idp --idp-user-id=alice@example.com. Consult IdP provider documentation for correct attribute name.

Network Connectivity Issues to IdP Endpoints

Symptoms: Authentication hangs or times out. No verification URL displayed to user.

Diagnosis:

# Test connectivity to all IdP endpoints
curl -I https://accounts.google.com/o/oauth2/v2/auth
curl -I https://oauth2.googleapis.com/device/code
curl -I https://oauth2.googleapis.com/token
curl -I https://www.googleapis.com/oauth2/v1/userinfo
curl -I https://www.googleapis.com/oauth2/v3/certs

# Check firewall rules
firewall-cmd --list-all
# Ensure outbound HTTPS (443) is allowed

# Test DNS resolution
nslookup oauth2.googleapis.com

# Check proxy settings if applicable
echo $http_proxy $https_proxy

Resolution: Ensure IPA server has network connectivity to all IdP endpoints (auth-uri, dev-auth-uri, token-uri, userinfo-uri, keys-uri). Check firewall rules, proxy configuration, and DNS resolution. IdP endpoints require outbound HTTPS (port 443) access. For air-gapped environments, external IdP authentication is not feasible.

Client Not Authorized for Device Flow

Symptoms: IdP returns “unauthorized_client” error. Authentication fails immediately.

Diagnosis:

# Verify OAuth client registration in IdP console
# Google Cloud Console → Credentials
# Azure Portal → App Registrations
# GitHub → Settings → Developer settings → OAuth Apps

# Check grant type configuration
# Ensure "Device Authorization Grant" or "Device Flow" is enabled

# Verify client ID matches exactly
ipa idp-show google-idp | grep "Client identifier"
# Must match OAuth client ID in IdP console (case-sensitive)

Resolution: The OAuth client registered with the external IdP must have Device Flow grant type enabled. In Google Cloud Console, this is automatic for “Desktop” application type. In Azure AD, enable “Allow public client flows” in the Authentication settings. In Keycloak, ensure “OAuth 2.0 Device Authorization Grant” is enabled in client settings. Verify client ID matches exactly between IdP console and IPA configuration.

Secret Mismatch After Rotation

Symptoms: IdP authentication worked previously but now fails with “invalid_client” error after secret rotation.

Diagnosis:

# Verify secret was updated in IPA after rotation in IdP console
ipa idp-show google-idp
# Note: Secret is not displayed (encrypted)

# Check IPA logs for "invalid_client" errors
journalctl -u ipa -n 50 | grep "invalid_client"

# Confirm secret in IdP console matches what was entered in IPA
# (Cannot view IPA secret, must re-enter)

Resolution: After rotating OAuth client secret in IdP console, immediately update in IPA: ipa idp-mod google-idp --secret and enter new secret. If uncertain whether update succeeded, regenerate secret in IdP console and update IPA again. Ensure clipboard paste doesn’t introduce extra spaces or newlines when entering secret.

Scope Rejection by IdP

Symptoms: IdP returns “invalid_scope” error or authentication fails during consent screen.

Diagnosis:

# Check configured scopes
ipa idp-show google-idp | grep "Scope"

# Verify scopes are valid for the IdP provider
# Google: openid, email, profile
# Azure AD: openid, email, profile, offline_access
# GitHub: read:user, user:email

# Check IdP console for approved scopes
# Google: API & Services → Credentials → OAuth consent screen
# Azure: API Permissions

Resolution: Ensure requested scopes are valid for the IdP provider and approved in the OAuth client configuration. Remove invalid scopes: ipa idp-mod google-idp --scope="openid email profile". For Google Workspace, some scopes require domain-wide delegation or admin consent. For Azure AD, ensure API permissions are granted and admin consent is provided if required.

Issuer URL Mismatch in ID Token

Symptoms: ID token validation fails with “Issuer does not match” error.

Diagnosis:

# Check configured issuer URL
ipa idp-show google-idp | grep "Issuer URL"

# Expected issuer values:
# Google: https://accounts.google.com
# Azure AD: https://login.microsoftonline.com/<tenant-id>/v2.0
# Keycloak: https://keycloak.example.com/realms/<realm-name>

# Check IPA logs for actual issuer received in ID token
journalctl -u ipa | grep "issuer"

Resolution: The --issuer-url must match the iss claim in ID tokens issued by the IdP. Update if mismatch: ipa idp-mod google-idp --issuer-url="https://accounts.google.com". For Azure AD, ensure tenant ID in issuer URL matches the configured organization. For Keycloak, verify realm name is correct.

JWKS Endpoint Unavailable

Symptoms: ID token signature validation fails. Logs show “Unable to fetch keys” or “JWKS endpoint error”.

Diagnosis:

# Check configured JWKS endpoint
ipa idp-show google-idp | grep "JWKS endpoint"

# Test JWKS endpoint accessibility
curl https://www.googleapis.com/oauth2/v3/certs
# Should return JSON with public keys

# Check for network/firewall issues
curl -v https://www.googleapis.com/oauth2/v3/certs

Resolution: Ensure --keys-uri is correctly configured and the endpoint is accessible from IPA server. For Google: https://www.googleapis.com/oauth2/v3/certs. For Azure AD: https://login.microsoftonline.com/common/discovery/v2.0/keys. For Keycloak: https://keycloak.example.com/realms/<realm>/protocol/openid-connect/certs. Verify network connectivity and firewall rules.

User Already Linked to Different IdP

Symptoms: Attempting to link a user to an external IdP fails because the user is already linked to a different IdP configuration.

Diagnosis:

# Check user's current IdP mapping
ipa user-show alice --all | grep ipaidp
# Shows existing mapping:
#   ipaidpsub: alice@example.com
#   ipaidpconfiglink: cn=google-idp,cn=idp,dc=example,dc=com

# Attempting to link to a different IdP
ipa user-mod alice --user-auth-type=idp --idp=azure-idp --idp-user-id=alice@contoso.com
# Fails because ipaidpsub is single-value

Resolution: Each user can only be linked to ONE external IdP because ipaidpsub is a single-value attribute. To change a user’s IdP mapping, first remove the existing mapping, then add the new one:

# Remove existing IdP mapping
ipa user-mod alice --user-auth-type=password --delattr=ipaidpconfiglink --delattr=ipaidpsub

# Add new IdP mapping
ipa user-mod alice --user-auth-type=idp --idp=azure-idp --idp-user-id=alice@contoso.com

Note: Changing IdP mappings will affect the user’s authentication method. Ensure the user is aware of this change.

Permission Denied Modifying IdP Configuration

Symptoms: Non-admin users receive “Insufficient access” error when attempting to view or modify IdP configurations.

Diagnosis:

# Check user's permissions
ipa user-show currentuser --all | grep memberof
# Look for admin groups

# Check IdP configuration requires admin privileges
ipa permission-find --name="*idp*"

Resolution: IdP configuration (add, modify, delete) requires administrative privileges. Only users with admins group membership or delegated IdP management permissions can modify IdP configurations. Grant appropriate permissions: ipa group-add-member idp-admins --users=alice (after creating custom delegation if needed). For read-only access, IdP secrets are always hidden; only configuration metadata is visible.

Provider Template Not Working

Symptoms: Using --provider=google or other template results in errors or incorrect endpoint configuration.

Diagnosis:

# Verify provider template is supported
ipa idp-add test --provider=invalid
# Should list supported templates: github, google, microsoft, keycloak, okta, oidc

# Check if additional parameters are required
# Microsoft requires: --organization
# Keycloak requires: --organization, --base-url
# Okta requires: --organization, --base-url

# Verify FreeIPA version supports the provider template
ipa --version

Resolution: Ensure provider name is spelled correctly and supported by your FreeIPA version. Some templates require additional parameters: ipa idp-add azure --provider=microsoft --organization="contoso.onmicrosoft.com" --client-id=... --secret. If template is not available, configure manually with explicit endpoints using no --provider parameter or --provider=oidc.

Authentication Succeeds but No Kerberos Ticket Issued

Symptoms: User completes external IdP authentication, sees success message, but klist shows no Kerberos credentials.

Diagnosis:

# Check if TGT was actually issued
klist -A
# May show tickets in different cache

# Check SSSD logs for Kerberos credential issuance
journalctl -u sssd -n 100 | grep -i "idp\|tgt\|ticket"

# Verify user has proper Kerberos principal
ipa user-show alice | grep "Principal"

Resolution: External IdP authentication must successfully map to IPA user and issue Kerberos TGT. Check IPA KDC logs: journalctl -u krb5kdc for ticket issuance. Ensure SSSD on client is properly configured for IdP authentication and Kerberos credential caching. If using custom credential cache: export KRB5CCNAME=/tmp/krb5cc_$(id -u) and retry kinit.

IdP Configuration Cannot Be Deleted

Symptoms: ipa idp-del fails with “This entry is being referenced by other entries”.

Diagnosis:

# Check which users are linked to this IdP
ipa user-find --all | grep "ipaidpconfiglink.*<idp-name>"

# List all user mappings for the IdP (replace with actual DN)
IdP_DN="cn=google-idp,cn=idp,dc=example,dc=com"
for user in $(ipa user-find --pkey-only | grep 'User login:' | awk '{print $3}'); do
  ipa user-show "$user" --all | grep -q "ipaidpconfiglink: $IdP_DN" && echo "User: $user"
done

Resolution: Remove IdP linkage from all users before deleting IdP configuration. For each user linked to the IdP:

# Remove IdP authentication and mappings
ipa user-mod alice --user-auth-type=password --delattr=ipaidpconfiglink --delattr=ipaidpsub

# After all users are unlinked, delete the IdP
ipa idp-del google-idp

Alternatively, use --force if available in your FreeIPA version (may orphan user mappings, requiring manual cleanup).

Commands

idp-add

Usage: ipa [global-options] idp-add NAME [options]

Add a new Identity Provider reference.

Arguments

Argument	Required	Description
`NAME`	yes	Identity Provider reference name

Options

Option	Description
`--auth-uri AUTH-URI`	OAuth 2.0 authorization endpoint
`--dev-auth-uri DEV-AUTH-URI`	Device authorization endpoint
`--token-uri TOKEN-URI`	Token endpoint
`--userinfo-uri USERINFO-URI`	User information endpoint
`--keys-uri KEYS-URI`	JWKS endpoint
`--issuer-url ISSUER-URL`	The Identity Provider OIDC URL
`--client-id CLIENT-ID`	OAuth 2.0 client identifier
`--secret SECRET`	OAuth 2.0 client secret
`--scope SCOPE`	OAuth 2.0 scope. Multiple scopes separated by space
`--idp-user-id IDP-USER-ID`	Attribute for user identity in OAuth 2.0 userinfo
`--setattr SETATTR`	Set an attribute to a name/value pair. Format is attr=value.
`--addattr ADDATTR`	Add an attribute/value pair. Format is attr=value. The attribute
`--provider PROVIDER`	Choose a pre-defined template to use
`--organization ORGANIZATION`	Organization ID or Realm name for IdP provider templates
`--base-url BASE-URL`	Base URL for IdP provider templates
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.

idp-del

Usage: ipa [global-options] idp-del NAME [options]

Delete an Identity Provider reference.

Arguments

Argument	Required	Description
`NAME`	yes	Identity Provider reference name

Options

Option	Description
`--continue`	Continuous mode: Don’t stop on errors.

idp-find

Usage: ipa [global-options] idp-find [CRITERIA] [options]

Search for Identity Provider references.

Arguments

Argument Required Description

CRITERIA no A string searched in all relevant object attributes

Options

Option	Description
`--name NAME`	Identity Provider reference name
`--auth-uri AUTH-URI`	OAuth 2.0 authorization endpoint
`--dev-auth-uri DEV-AUTH-URI`	Device authorization endpoint
`--token-uri TOKEN-URI`	Token endpoint
`--userinfo-uri USERINFO-URI`	User information endpoint
`--keys-uri KEYS-URI`	JWKS endpoint
`--issuer-url ISSUER-URL`	The Identity Provider OIDC URL
`--scope SCOPE`	OAuth 2.0 scope. Multiple scopes separated by space
`--idp-user-id IDP-USER-ID`	Attribute for user identity in OAuth 2.0 userinfo
`--timelimit TIMELIMIT`	Time limit of search in seconds (0 is unlimited)
`--sizelimit SIZELIMIT`	Maximum number of entries returned (0 is unlimited)
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.
`--pkey-only`	Results should contain primary key attribute only (“name”)

idp-mod

Usage: ipa [global-options] idp-mod NAME [options]

Modify an Identity Provider reference.

Arguments

Argument	Required	Description
`NAME`	yes	Identity Provider reference name

Options

Option	Description
`--auth-uri AUTH-URI`	OAuth 2.0 authorization endpoint
`--dev-auth-uri DEV-AUTH-URI`	Device authorization endpoint
`--token-uri TOKEN-URI`	Token endpoint
`--userinfo-uri USERINFO-URI`	User information endpoint
`--keys-uri KEYS-URI`	JWKS endpoint
`--issuer-url ISSUER-URL`	The Identity Provider OIDC URL
`--client-id CLIENT-ID`	OAuth 2.0 client identifier
`--secret SECRET`	OAuth 2.0 client secret
`--scope SCOPE`	OAuth 2.0 scope. Multiple scopes separated by space
`--idp-user-id IDP-USER-ID`	Attribute for user identity in OAuth 2.0 userinfo
`--setattr SETATTR`	Set an attribute to a name/value pair. Format is attr=value.
`--addattr ADDATTR`	Add an attribute/value pair. Format is attr=value. The attribute
`--delattr DELATTR`	Delete an attribute/value pair. The option will be evaluated
`--rights`	Display the access rights of this entry (requires —all). See ipa man page for details.
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.
`--rename RENAME`	Rename the Identity Provider reference object

idp-show

Usage: ipa [global-options] idp-show NAME [options]

Display information about an Identity Provider reference.

Arguments

Argument	Required	Description
`NAME`	yes	Identity Provider reference name

Options

Option	Description
`--rights`	Display the access rights of this entry (requires —all). See ipa man page for details.
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.