SAML - Federation Broker

Overview

This document provides a comprehensive guide on setting up PhenixID Authentication Services (PAS) to function as a federation broker in a SAML-based environment. Acting as an intermediary, PAS enables Single Sign-On (SSO) across different domains by managing authentication requests and responses between external SAML Service Providers (SPs) and external SAML Identity Providers (IdPs), such as Microsoft Entra ID, Okta, and Google Identity Platform.

As a federation broker, PAS streamlines user access to multiple resources by authenticating users through an external IdP, creating a seamless and secure session. This setup provides significant advantages for organizations that need to integrate with multiple identity sources or where applications are spread across different security domains. By handling SAML assertions and session management on behalf of the SP and IdP, PAS facilitates enhanced security and interoperability between applications and identity providers.

Full Authentication Flow

Below is a sequence diagram that highlights the key steps in the authentication process using PhenixID Authentication Services (PAS) as an Identity Broker:

sequenceDiagram
    participant User
    participant Browser
    participant SP as Service Provider (SP)
    participant PAS as PhenixID Authentication Services (Identity Broker)
    participant IdP as External SAML Identity Provider (IdP)

    User->>Browser: Access protected resource
    Browser->>SP: Request resource
    SP-->>Browser: Redirect to PAS (Identity Broker)
    Browser->>PAS: Authentication request
    PAS-->>Browser: Redirect to External IdP
    Browser->>IdP: Authenticate user
    IdP-->>Browser: SAML Response
    Browser->>PAS: Relay SAML Response
    PAS->>PAS: Validate SAML Response
    PAS-->>Browser: Redirect to SP with new SAML Response
    Browser->>SP: Send SAML Response from PAS
    SP->>SP: Validate SAML Response
    SP->>Browser: Grant access to resource

Simplified Flow Explanation in Identity Broker Context

User Accesses Protected Resource:
- The user attempts to access a protected resource on the Service Provider (SP) using a web browser.
SP Redirects to PAS (Identity Broker):
- The SP cannot authenticate the user directly and redirects the browser to PAS, which acts as an Identity Broker.
PAS Redirects to External IdP:
- PAS receives the authentication request and redirects the browser to the external SAML Identity Provider (IdP) for user authentication.
User Authenticates with External IdP:
- The user provides credentials and completes the authentication process with the external IdP.
IdP Sends SAML Response to PAS:
- The IdP sends a SAML assertion back to the browser, which forwards it to PAS.
PAS Validates SAML Response:
- PAS validates the SAML assertion received from the IdP to ensure it's authentic and hasn't been tampered with.
PAS Acts as IdP to SP:
- After validation, PAS creates a new SAML assertion based on the user's authentication and sends it back to the SP, effectively acting as the IdP for the SP.
SP Grants Access to Resource:
- The SP validates the SAML assertion from PAS.
- Upon successful validation, the SP grants the user access to the requested protected resource.

Technical flow on PAS server

This section outlines the internal operations that PhenixID Authentication Services (PAS) performs to facilitate authentication as a federation broker, based on the full authentication flow described above.

Validation of SP Authentication Request: PAS receives the authentication request from the external SAML Service Provider (SP) and validates it against the SP's metadata to ensure that the request is from a trusted source and meets security requirements.
Initiation of IdP Authentication Request: Upon successful validation, PAS generates a new authentication request targeting the configured external Identity Provider (IdP) and redirects the client to complete authentication.
Processing of SAML Response from IdP: Once the user authenticates on the external IdP and returns to PAS with a SAML assertion, PAS uses its consumer pipe to validate the assertion and extract user identity information. PAS establishes an authenticated session for the user, setting the NameID from the assertion as the user ID and saving any additional attributes in the flow.
Creation of SAML Assertion for SP: Using the data stored in the session, PAS generates a new SAML assertion through the assertion profile. The assertion profile retrieves session attributes, formats them according to the SP's requirements, and creates the final assertion to be sent back to the external SP.

Configuring PhenixID Authentication Services (PAS)

Establish Trust with External SAML IdP and SP

To establish trust with both the external Identity Provider (IdP) and Service Provider (SP), upload their respective metadata files. Detailed instructions can be found in this article: SAML SP Metadata Upload

Add SAML IdP and signing certificate

Follow this guide and add a SAML IdP that your SPs should trust: SAML Identity Provider

Add a suitable assertion profile for your SPs:

[{
      "id" : "my-profile",
      "useForEntityIDs" : [ "someSPEntityID", "someOtherSPEntityID" ],
      "nameIDAttribute": "uid"
      "additionalAttributes" : [ {
        "name" : "urn:oid:2.5.4.42",
        "friendlyName": "givenName",
        "itemAttribute" : "givenName"
      }]
}]

The entry point will be the SPBroker authenticator that we will create in the next step.

Add SAMLSPBroker authenticator

Add a SPBroker authenticator. See reference here.

SAMLSPBroker configuration

Example configuration below. Use this and change the references to suit your environment.

Execution flow on SPBroker

 {
    "id" : "pipeAssertionConsumer",
    "valves" : [{
      "name": "ItemCreateValve",
      "enabled": "true",
      "config": {
        "dest_id": "user"
  }
   },{
      "name" : "AssertionConsumer",
      "config" : {
        "clock_skew_minutes" : "10",
        "addAttributesTo": "item"
      }
    },{
      "name" : "FlowFailValve",
      "config" : {
        "message" : "User does not exist",
        "exec_if_expr" : "flow.items().isEmpty()"
      }
    } ]
  }

Verify

View SAML Broker SP Metadata: Open a web browser and navigate to /samlsp//meta (e.g., https://myserver/samlsp/spbroker/meta). Adjust the URL to match your configuration. The SAML SP metadata XML will be displayed, which should be shared with the external IdP(s).
View SAML IdP Metadata: In a web browser, go to /authentication/saml//meta (e.g., https://myserver/authentication/saml/broker_idp/meta). Update the URL as needed for your configuration. The SAML IdP metadata XML will appear, which should be shared with the external SP(s).
Test Your Configuration: Verify your setup by following the steps outlined in here

Table of Contents