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
- Client (web browser) tries to access resource (external SAML SP)
- External SAML SP redirects client to configured IdP (PAS) with authentication request
- PAS receives authentication request.
- PAS redirects client to configured IdP (External SAML IdP) with authentication request
- User authenticates on external SAML IdP
- External SAML IdP redirects client to PAS with authentication response (saml assertion)
- PAS receives and validates response, create authenticated session for user
- PAS redirects client to external SAML SP with authentication response (saml assertion)
- 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
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
- 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).
- 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). - Test your setup by following the verifying the steps described above.