SAML - Federation Broker

The purpose of this document is to describe how to setup PhenixID Authentication Services as a federation broker.

Flow

Full authentication flow

  1. Client (web browser) tries to access resource (external SAML SP)
  2. External SAML SP redirects client to configured IdP (PAS) with authentication request
  3. PAS receives authentication request.
  4. PAS redirects client to configured IdP (External SAML IdP) with authentication request
  5. User authenticates on external SAML IdP
  6. External SAML IdP redirects client to PAS with authentication response (saml assertion)
  7. PAS receives and validates response, create authenticated session for user
  8. PAS redirects client to external SAML SP with authentication response (saml assertion)
  9. External SAML SP gives user access to resource

Technical flow on PAS server

Given the Full authentication flow above, this describes what happens on the PAS server:

3. Validate authentication request from SAML SP using SAML SP metadata

4. Create and send authentication request to configured IdP

7. Pipe (consumer pipe) process SAML response. Creates authenticated session. NameID of assertion is set as userid. Attributes in assertion is saved in session.

8. Pipe (assertion pipe) creates saml assertion to be sent from values in the session. The AssertionProvider valve only acts on an item so before executing the AssertionProvider, the session attributes must be copied to properties. See configuration example below.

Prerequisites

  • PhenixID Server configured according to this instruction: "Federation - Username and password". Make sure the alias on the authenticator URL is set to "broker_idp".
  • External SAML SP Metadata available (file or url)
  • External SAML IdP Metadata available (file or url)

Add trust to external SAML IdP

Add trust to the external IdP by following these instructions.

Add trust to external SAML SP

Add trust to the external SP by following this scenario.

Convert the Federation - Username and Password scenario to SAMLDataSave

Open the Advanced tab and locate the Authentication - HTTP entry that was configured in the previous "Federation - Username and password" scenario.

Change the value of the name parameter from "PostUidAndPasswordSAML" to "SAMLDataSave"

Configure the authenticator like this. Make sure the idpID value remains the same as the original value. 

{
    "alias" : "broker_idp",
    "id" : "broker_idp",
    "name" : "SAMLDataSave",
    "configuration" : {
      "nextAuthenticator" : "broker",
      "idpID" : "56cd9ef8-cc60-431f-bc5b-870a603c8c23"
    }
  }

 

Add broker SP configuration

- Open the Advanced tab. Click the SAMLIDP section. Locate the SAML IdP that was created by the federation guide in previous step. Copy the keystore value. See example below.

{
    "id" : "56cd9ef8-cc60-431f-bc5b-870a603c8c23",
    "name" : "SAML IDP",
    "keystore" : "dcb70f7a-8a18-4e47-a0f5-2369f1d45724",
    "entityID" : "https://myserver/saml/idp",
    "requireSigned" : "false",
    "postSSOURL" : "https://myserver/saml/authenticate/broker_idp",
    "created" : "2017-10-09T13:00:23.568Z"
  }

- Open the Advanced tab. Click the + next to SAMLSP. Add a SAML SP configuration. Use the keystore value fetched in previous step for keystoreSign and keystoreEncrypt.
Set ForceAuthn to true if you need authnRequests to include ForceAuthn=true, otherwise set to false or omit.

{
    "id" : "https://myserver/saml/broker",
    "keystoreSign" : "dcb70f7a-8a18-4e47-a0f5-2369f1d45724",
    "entityID" : "https://myserver/saml/broker",
    "ForceAuthn" : "false"
  }

Please add the property keystoreEncrypt if the SAML assertions should be encrypted.

Add SAMLSPBroker authenticator

Add a SAMLSPBroker authenticator. See reference here.

SAMLSPBroker configuration

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

Example 

{
    "id": "broker",
    "alias": "broker",
    "name": "SAMLSPBroker",
    "displayName": "Federation Broker",
    "configuration": {
        "sp": "https://myserver/saml/broker",
        "issueAsIDPID": "56cd9ef8-cc60-431f-bc5b-870a603c8c23",
        "pipeIDAssertionConsume": "pipeAssertionConsumer",
        "pipeIDAssertionProduce": "pipeAssertionProducer",
        "targetIDP": "https://external_idp/idp",
        "acsUrl": "https://myserver/saml/authenticate/broker",
        "entityID": "https://myserver/saml/broker",
        "addsignature": "true"
    }
}

Pls note that entityID and sp must have the same value configured. 
IssueAsIDPID is the ID of the internal IDP previously configured.

Assertion consumer pipe 

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

Assertion producer pipe 

{
    "id": "pipeAssertionProducer",
    "valves": [
        {
            "name": "SessionLoadValve",
            "config": {
                "id": "{{request.session_id}}"
            }
        },
        {
            "name": "ItemCreateValve",
            "config": {
                "dest_id": "{{request.username}}"
            }
        },
        {
            "name": "PropertyFromSessionToItem",
            "config": {
                "source": "givenName"
            }
        },
        {
            "name": "PropertyFromSessionToItem",
            "config": {
                "source": "sn"
            }
        },
        {
            "name": "PropertyFromSessionToItem",
            "config": {
                "source": "mail"
            }
        },
        {
            "name": "AssertionProvider",
            "config": {
                "targetEntityID": "56cd9ef8-cc60-431f-bc5b-870a603c8c23",
                "nameIDAttribute": "mail",
                "additionalAttributes": "givenName,sn",
                "sourceID": "https://external_sp/sp"
            }
        }
    ]
} 

Note, the targetEntityID in the AssertionProvider is the ID of the internal IDP created at the beginning.

Verify

  1. Display the SAML Broker SP Metadata using a web browser. Browse to <broker_acs_url>?getMeta. (Example https://myserver/saml/authenticate/broker?getMeta) (Change the URL to  suit your configuration). SAML SP Metadata XML should be displayed. This metadata should be distributed to the external idp(s).
  2. Display the SAML IdP Metadata using a web browser. Browse to <broker_idp_post_sso_url>?getIDPMeta. (Example: https://myserver/saml/authenticate/broker_idp?getIDPMeta)
    (Change the URL to  suit your configuration).
    SAML SP Metadata XML should be displayed. This metadata should be distributed to the external sp(s).
  3. Test your setup by following the verifying the steps described above.