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.

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

Add SAMLSPBroker authenticator

Add a SAMLSPBroker authenticator. See reference and example below. Change values to suit your environment.

SAMLSPBroker Configuration reference

Name Description Default value Mandatory
sp ID of SAMLSP entity in store that will be used for interaction with the external IdP. Yes
issueAsIDPID ID of SAMLIDP entity in store that will be used as issuer of the assertion to the external SP requesting authentication. Yes
pipeIDAssertionConsume Id of pipe used to validate assertion from external IdP and, if necessary, perform additional user lookups etc. Yes
pipeIDAssertionProduce Id of pipe used to create assertion which should be sent to external SP. Yes
targetIDP ID of SAMLMETA idp entity in store to use for authentication. This is the external IdP. Yes
acsURL The URL to receive the assertion. Should reference to same authenticator (/saml/authenticate/. Yes
addsignature Sign the authentication request (true/false). true No
entityID ID of SAMLSP entity in store that will be used for interaction with the external IdP. Yes

SAMLSPBroker example configuration

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

Authenticator

{
    "id": "broker",
    "alias": "broker",
    "name": "SAMLSPBroker",
    "displayName": "Federation Broker",
    "configuration": {
        "sp": "https://myserver/saml/broker",
        "issueAsIDPID": "dcb70f7a-8a18-4e47-a0f5-2369f1d45724",
        "pipeIDAssertionConsume": "pipeAssertionConsumer",
        "pipeIDAssertionProduce": "pipeAssertionProducer",
        "targetIDP": "https://external_idp/idp",
        "acsUrl": "https://myserver/saml/authenticate/broker",
        "entityID": "https://myserver/saml/broker",
        "addsignature": "false"
    }
}

Pls note that entityID and sp must have the same value 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": "pipeAssertionConsumer",
    "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": "dcb70f7a-8a18-4e47-a0f5-2369f1d45724",
                "nameIDAttribute": "mail",
                "additionalAttributes": "givenName,sn",
                "sourceID": "https://external_sp/sp"
            }
        }
    ]
} 

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.