Step by Step Process

In order to configure SAML, you need to do it together with the customer’s IT department managing the identity provider (=IdP).

1. Go to Administration > Configuration > External Systems > SAML Configuration and click Add to create a new configuration.

2. An entry in the SAML Configuration section is created.
   You can have more SAML Configurations here if you need to connect to multiple identity providers at the same time. The SAML configuration name is then just appended in the signon URL.
   If you have just one SAML Configuration, it is named DEFAULT and does not have to be specified in the signon URL.
    You must keep the casing of the configuration name in any URLs where the name is used (even if it means to use all caps in the URL).

3. For start, fill in the Relay States parameter(s) (described in detail below). 
   The remaining mandatory fields can be filled in only after the setup at the identity provider side is done.
   Note: Relay States are optional. A relay state is just a transient piece of information that is passed along through the authentication process (i.e. not altered in any way by the IdP). In our case the information inside the relay state is then used to determine the target page that the user will be redirected to after the authentication process. Hence if no relay state is passed along, the system will use the default redirection target, which is the standard home page after login.

4. Save the configuration.

5. Provide the following details to the identity provider administrator:

   • Service Provider name / Identifier(EntityID) (depending on identity provider terminology)

     https://CustomerName.pricefx.eu/pricefx/PartitionName/saml/signon/

   • Signon URL

     https://CustomerName.pricefx.eu/pricefx/PartitionName/saml/signon/

   • Consume URL = Allowed reply URLs / AssertionConsumerService (ACS)

     https://CustomerName.pricefx.eu/pricefx/PartitionName/saml/consume/

6. Once the identity provider is configured, ask for Federation Metadata URL. If that cannot be provided, you ask for:

   • Identity provider URL

   • Identity provider certificate
     (both come in the federation metadata file, so that is why federation is preferred)

7. Add those values in Pricefx SAML Configuration. 

8. In the NameID Mapping field select which value is used to map to NameID (email, login name etc.).

9. Save the configuration. (Saved configuration is stored the Advanced Configuration Options.)

10. Log in using the signon URL from the previous steps to validate the SSO logon.

 Right from the beginning, agree on a certificate validity renewal process with the customer. Whenever the certificate expires and a new one is supplied, SAML configuration has to be adjusted. The aim is to have a certificate valid at any point of time, otherwise users will not be able to log in. 

Options Descriptions

Options marked * are mandatory. 

• NameID Mapping* – Select the attribute from the User Management which contains the user ID which is also used by the identity provider. This value is used to identify the user from the IdP. It must be unique per user – no two users can have the same value in that field, otherwise the login via SAML will fail. This is particularly important when you choose Email, as unique email addresses are not enforced on the Pricefx side.

• Name ID Format – You can specify the name identifier format that is used (unspecified, emailAddress, persistent, transient). Only set this field to a value if required.

• ADFS/Azure/O365/Okta federation metadata URL – If the identity provider gave you a federation metadata URL, enter it here. Click the Load metadata from URL button to get and apply all the necessary SAML configuration information from the URL. Once the metadata URL is set and saved here, the configuration will be automatically updated when the IdP changes it.

• SAML Identity Provider URL* – Enter the web address of the SAML SSO page of the Identity Provider.

• SAML base URL – Used only if the system should be accessed by a custom DNS name (but the cluster’s main/real DNS is a different one). Example: www.pricefx.eu for a customer on shared PROD using DNS some-customer.pricefx.eu.

• EntityID (optional, generated if not set explicitly) – Overrides the generated EntityID (signon URL). It can be used for setups with multiple systems/partitions to one IdP where you no longer need to create a separate SAML configuration for each partition. (But on the identity provider side, all the different reply URLs still have to be specified.)

• IdP Certificate* – Paste the public certificate of the identity provider. It can be found in the identity provider metadata. It is used to check the digital signature of the authentication request. Make sure you include the BEGIN and END tags. Multiple certificates can be added simply by pasting them one after the other (including the start/end tags).

  Example

• Auto Provisioning – In this section, you can enable and configure the auto-provisioning feature (described below).

• RelayStates – The RelayState parameter tells the Service Provider to which web page to redirect after a successful user login. (Technically, it is just a URL parameter with a defined name which identity provider just passes it through.) By default, you are logged into Unity UI (with or without RelayState) and the module which is set as Home Page opens (if no targetPage and targetPageState parameters are specified).

  • If you want to create a deep link that directly opens an Agreement/Promotion, Quote or Rebate Agreement, append the relay state name in the link with parameters identifying the document. For example:

    The string right of the double dash delimiter will be appended to the relay state URL. The targetPage parameter is listed in AppPages in API and the targetPageState is the uniqueName.
     See more about configuring links with the RelayState parameter.

  • The RelayState parameter can be generated dynamically. There are the following placeholders supported:

    • USERNAME – Allows you to use the same URL for multiple usernames.

    • PARTITION – Allows you to use the same URL for multiple partitions. (As the whole SAML configuration is per partition only, this placeholder makes sense when reusing a configuration over more partitions.)

    • SSOSELECTOR – Allows you to use the same URL for multiple IdPs.

    • LOCALE – If you need to dynamically set/replace the configured locale of the user (as stored in emailLocale of the Pricefx user object) in the final redirect URL.

  • There is also a special built-in relay state named “PricefxStudio” which exists there by default. It does not redirect anywhere but emits an HTML response that returns the JWT token for Studio. The relay state can also be “PricefxStudio-Something”. The “Something” would be available in the HTML response template and is shown there as additional info (e.g., to identify Studio’s connection name).

  • Relay state can also contain an arbitrary/dynamic redirect URL. This can be useful to support e.g., SSO-enabled deep links in emails or an ad-hoc SSO round-trip when the user hits a deep link unauthorized. Redirect URL (after successful authorization roundtrip) can be set like this:

  • At your convenience, a relay state builder is available that helps you construct the URL with the correct syntax.

• Pricefx metadata – Copy and paste this metadata to create a file that can be used to automatically configure SAML for Pricefx on the IdP side.
  You can also generate the metadata file via an API endpoint:

  • /pricefx/<partition>/admin.generateFederationMetaData
    or

  • /pricefx/<partition>/admin.generateFederationMetaData/<SAML config name>

  • Note that the parameter is case sensitive and must always be "RelayState".
     See also How to Specify RelayState Parameter.

 Azure AD requires that the identifierUris do not have a trailing slash. Therefore the SSO identifier URL in Pricefx is configurable. By default the trailing slash is always added but it can be removed: go to Administration > Configuration > System Configuration > Advanced Configuration Options and adjust 'samlConfiguration' by adding the parameter "trailingIdSlash" : false.

 Tips:

• For security reasons, you may want to notify users after they log out that all browser windows must be closed to complete logging out when using SSO. To display a notification on the logout page, use the enableLogoutAlert feature flag.

• If you want your users to be redirected after logout to other page than the Pricefx login page, enable the feature flag useCustomLogoutURL and set the required URL in the customLogoutURL feature flag.
  Note that if a custom logout page is set, the logout security notification is not displayed.

Login URLs

Note that simply configuring SAML does not change the way users can log in right away. I.e., SAML SSO can by default be used in parallel with an existing password-based authentication. There is a configuration option on the user level to force SSO login. In order to use SSO login, the user also has to access the UI with a different URL. This URL is partition-specific (it contains the partition name) and looks like: 

Auto-Provisioning

Pricefx supports an auto-provisioning feature which creates a user account on the fly if the SAML authentication is valid but no corresponding user account is found.

You can enable and configure it either on the Configuration > External Systems > SAML Configuration page or in the standard samlConfiguration app property using JSON tags. The tags are:

When auto-provisioning is enabled, the following behavior applies if no corresponding active user is found:

• If the user does not exist at all, an account is created with the default business role.

• If the user is soft-deleted and not deactivated, the user account is resurrected with previous user roles and groups restored.

• If the user is deactivated, access is denied.

Defaults here are aligned to Azure:

• "firstName","http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"

• "lastName","http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"

• "email","http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email"

• "loginName","http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"

Other providers need different mappings here as there seems to be no standard. Keys should stay as described above.

Session Expiration

After the user session expires, reauthorization is performed automatically, however the application state is cleared, i.e., all open application tabs are closed, etc. If the user password is changed, all existing sessions (also e.g., in other browser windows) are immediately made invalid.