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"
  • 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 SAMLSPBroker

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 "SAMLSPBroker"

Configure the authenticator using the guidelines below.

Configuration

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

Example configuration

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

Authenticator

{

    "id": "broker",

    "alias": "broker",

    "name": "SAMLSPBroker",

    "displayName": "Broker",

    "configuration": {

        "sp": "https://myserver/saml/broker",

        "issueAsIDPID": "https://myserver/saml/idp",

        "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" : "assertionConsumer",

"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": "https://myserver/saml/idp",

                "nameIDAttribute": "mail",

                "additionalAttributes": "givenName,sn",

                "sourceID": "https://external_sp/sp"

            }

        }

    ]

}

Verify

  1. Display the SAML Broker SP Metadata using a web browser. Browse  to https://myserver/saml/authenticate/broker?getMeta (Change the URL to  suit your configuration). SAML SP Metadata XML should be displayed.
  2. Test your setup by following the verifying the steps described in above.