SPBroker

Note

This authenticator delegates the authentication to a trusted (internal or external) SAML IdP. It authenticates by sending a SAML AuthnRequest to that IdP and then validating the assertion.

Properties

Name	Description	Default value	Mandatory
sp	The internal ID of the Service provider. This value maps to a SAML SERVICE PROVIDER configured.	N/A	Yes
targetIDP	ID of SAMLMETA idp entity in store to use for authentication. This is the external IdP.	N/A	Yes
addsignature	Sign the authentication request (true/false).	true	No
pipeID	Id of the pipe used when consuming an incoming assertion	N/A	Yes
discoveryUrl	If using IDP discovery this should point to the location of the discovery service	N/A	No
cancelUrl	Where to redirect the browser after a cancelled authentication	N/A	No
requestedAuthnContext	Value of RequestedAuthnContext (AuthnContextClassRef) in the AuthnRequest (EXPANDABLE)	N/A	No
setAcsIndexBasedOnRequestIssuer	If the AttributeConsumingServiceIndex should be set according to the issuer mapping from the SP config	false	No
discoveryUrl	If using IDP discovery this should point to the location of the discovery service	N/A	No
acsUrlOverride	An obsolete option kept for backwards compatibility. Overrides the ACS URL to use. For automatic ACS handling, configure your SAML Service Provider to only use the ACS url `<your-domain>/authentication/samlsp/<your-sp-id>/acs`	N/A	No
signMessage	A SignMessage to include in the AuthnRequest. (EXPANDABLE)	N/A	No
principalSelection	PrincipalSelection to include in the authentication request. (EXPANDABLE)	N/A	No
enableLogout	Whether logout functionality should be enabled. If enabled, logging out at the entrypoint would also send a LogoutRequest to the external IDP (if they have SLO configured in their metadata). Enabling this also allows the IDP to send LogoutRequests to this SP, allowing SLO.	false	No

ACS / SLO Urls and automatic redirecting (and changes to previous behavior)

PAS 6.0 introduced an upgrade to the SPBroker that allows you to avoid configuring ACS URLs to fit your protocol entrypoint, meaning you may configure one static ACS URL that will work no matter where you use it. This ACS URL is automatically added when using the guide scenario, and will always be: <your-domain>/authentication/samlsp/<your-sp-id>/acs.

An SLO URL will also be added to the metadata to support logout functionality. This SLO URL is used so that the IdP can redirect the user back to PAS once the logout is complete, so that PAS may continue the logout flow. However, the SLO URL can also be used as a general single logout endpoint that the IdP may contact through interaction in other logout flows. This can be controlled via the setting allowIncomingLogoutRequests at the service provider, see example below.

If you do not wish to use any logout functionality, keep enableLogout as false in the SPBroker authenticator configuration, and set allowIncomingLogoutRequests to "false" at the service provider configuration. To remove the SLO URL from the SP Metadata, you can remove the URL from the sloUrls config property at the SAML Service Provider configuration. If you wish to manually add the SLO functionality to an existing SPBroker configuration, do so by adding the config property sloUrls with the value ["<your-domain>/authentication/samlsp/<your-sp-id>/slo"].

The SLO URL

Changes to previous behavior (before PAS 6.0)

Previous behavior required correct ACS URLs to be configured at the service provider in a way so the would fit your current URL when you use the authenticator. That behavior has now been changed, and works in the current way:

The SPBroker will look through your configured ACS URLs from your SP Metadata
If one of the ACS paths are equal to your current path, this ACS URL will be used in the outgoing AuthnRequest
If the generic ACS url has been configured (<your-domain>/authentication/samlsp/<your-sp-id>/acs), that will be used
If no suitable ACS URL has been found in the metadata, an error is thrown.
Note that the parameter acsUrlOverride is still available, and will override the above options and you may set the URL to what you wish, but it is no longer necessary to use and is not recommended.

Just running through the guide scenario will configure everything you need, so it is recommended to do that.

Example Configuration

{
    "id": "spbroker",
    "alias": "spbroker",
    "name": "SPBroker",
    "displayName": "Broker",
    "configuration": {
        "sp": "spbroker",
        "pipeID": "pipeAssertionConsumer",
        "enableLogout": "true",
        "targetIDP": "https://external_idp/idp",
        "addsignature": "false",
        "requestedAuthnContext" : "{{session.userSource}}",
        "principalSelection" : [ {
            "name" : "uid",
            "value" : "{{session.user_id}}"
        } ]
    }
}

Example Service Provider configuration

{
    "id" : "spbroker",
    "name" : "SAML Service provider",
    "keystoreSign" : "af8fedd2-7234-46bf-a254-b2568dfd3dc1",
    "keystoreEncrypt" : "af8fedd2-7234-46bf-a254-b2568dfd3dc1",
    "entityID" : "https://localhost:8443/samlsp/spbroker",
    "baseURL" : "https://localhost:8443",
    "allowIncomingLogoutRequests": "true",
    "wantsAuthnRequestsSigned" : "true",
    "sloUrls" : [ "https://localhost:8443/authentication/samlsp/spbroker/slo" ],
    "assertionConsumerServiceUrls" : [ "https://localhost:8443/authentication/samlsp/spbroker/acs" ],
    "attributeConsumingServices" : [ {
      "index" : "0",
      "default" : "true",
      "issuers" : [ "SPEntityId1", "SPEntityId2" ],
      "serviceNames" : [ {
        "name" : "TestSP utan HSA-uppslag",
        "lang" : "sv"
      } ],
      "requestedAttributes" : [ {
        "name" : "urn:sambi:names:attribute:levelOfAssurance",
        "nameFormat" : "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
        "friendlyName" : "levelOfAssurance"
      } ]
    }, {
      "index" : "1",
      "default" : "false",
      "issuers" : [ "broker", "TestSPEntityId4" ],
      "serviceNames" : [ {
        "name" : "TestSP med HSA-uppslag",
        "lang" : "sv"
      }, {
        "name" : "TestSP with HSA-query",
        "lang" : "en"
      } ],
      "requestedAttributes" : [ {
        "name" : "urn:sambi:names:attribute:levelOfAssurance",
        "nameFormat" : "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
        "friendlyName" : "levelOfAssurance"
      }, {
        "name" : "http://sambi.se/attributes/1/givenName",
        "nameFormat" : "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
        "friendlyName" : "givenName",
        "isRequired" : "true"
      }, {
        "name" : "http://sambi.se/attributes/1/systemRole",
        "nameFormat" : "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
        "friendlyName" : "systemRole"
      } ]
    } ],
    "created" : "2023-12-08T10:01:52.316Z"
  }

Requirements

A SAML Service Provider entity defined under Advanced->SAML Service Provider.

Table of Contents