Skip to main content

Federated Identity Providers

Federated Identity Providers (IDPs) allow Identity Broker to delegate authentication to external identity systems such as Microsoft Entra ID, Google, Okta, and other OIDC-compliant or SAML 2.0-compliant providers.

This enables secure, scalable, multi-tenant authentication without coupling your application directly to upstream identity providers.

Overview​

The Federated IDPs screen is the control center for managing all external identity providers connected to Identity Broker. From this page, administrators can add new providers, manage domain-based routing (HRD), and configure attribute mapping.

Identity Broker supports two primary federation protocols:

  1. OpenID Connect (OIDC)
  2. SAML 2.0

OIDC Provider Configuration​

When adding an OIDC provider, you typically configure:

  • Issuer URL: The discovery endpoint for the IDP.
  • Client ID & Secret: Issued by the upstream IDP for Identity Broker.
  • Scopes: Requested user attributes (e.g., openid profile email).
  • Domain Hint: A keyword used for Home Realm Discovery.

SAML 2.0 Provider Configuration​

Identity Broker can act as a SAML 2.0 Service Provider (SP) to an upstream SAML Identity Provider.

Configuration Fields​

  • SAML IDP Entity ID: The unique identifier of the upstream IDP.
  • SAML SSO Service URL: The URL where Identity Broker will send authentication requests.
  • IDP Metadata: Upload the metadata XML file from your upstream IDP to automatically populate settings.
  • Service Provider (SP) Settings — the broker derives these per IdP config; register them in your upstream IdP:
    • ACS URL (Assertion Consumer Service): https://<broker>/saml2/acs/{idpConfigId} — where the IdP POSTs the signed SAMLResponse.
    • Audience / SP Entity ID: https://<broker>/saml2/service-provider-metadata/{idpConfigId}.
  • Binding Type: Choose between HTTP-Redirect or HTTP-POST (POST is most common).
  • Signature & Encryption: Upload the upstream IdP's signing certificate; the broker verifies the assertion/response signature against it.

Setting up a SAML IdP (step by step)​

  1. Create the IdP config in the admin console (/admin/idp-configs) with protocol = SAML, the IdP's Entity ID, SSO Service URL, signing certificate, and a domain hint.
  2. Register the broker as an SP in your upstream IdP using the ACS URL and SP Entity ID above (for the just-created {idpConfigId}). Enable signed assertions/response; the broker sends unsigned AuthnRequests by default.
  3. Route to it — add a domain mapping (or domain_hint) so an RP authorize reaches this IdP. The broker then SP-initiates the SAML flow, the user authenticates at the IdP, and the signed SAMLResponse is consumed at the ACS.
Production cross-site SAML requires secure cookies

A real SAML IdP on a different site POSTs the SAMLResponse to the broker's ACS as a cross-site top-level POST. The broker's IdP-correlation cookie is only sent on that POST when it is SameSite=None; Secure, which the broker applies only when secure cookies are enabled (server.servlet.session.cookie.secure=true, i.e. behind HTTPS). Set this in production or SP-initiated SAML login will fail to correlate the broker session (the broker logs a startup warning when a SAML IdP is configured but secure cookies are off).

Domain Mapping & HRD​

Every Federated IDP can be mapped to one or more Email Domains. This is the core of Identity Broker's Home Realm Discovery (HRD) system.

  • Wildcard Domains: Support for *@company.com or specific domains like acme.corp.
  • Domain Hints: Allow applications to skip the discovery screen by providing a domain_hint parameter in the login request.

Attribute Mapping (Claims)​

Identity Broker provides a flexible system for mapping upstream claims (from OIDC or SAML) into normalized internal claims.

  • Standard Claims: Email, Name, Given Name, Family Name, Profile Picture.
  • Custom Claims: Map any proprietary claim from the IDP into your application's tokens.
  • Claim Transformation: Use rules to modify or combine claims during the authentication flow.

Best Practices​

  • Use OIDC when possible: It is generally easier to configure and maintain than SAML.
  • Metadata Exchange: Always use metadata XML files for SAML configurations to avoid manual entry errors.
  • Encryption: Enable assertion encryption for SAML providers when sensitive data is being transmitted.
  • Domain Isolation: Ensure that domains are unique across different IDP configurations to prevent discovery conflicts.
  • Monitoring: Regularly check the Sign-In Logs for any "Provider Error" messages related to specific IDPs.