Pricefx supports single sign-on (SSO) with SAML.

How It Works

In the SAML language, Pricefx acts as a "Service Provider" and can integrate with an "Identity Provider" for SAML requests, such as Active Directory, Okta or Salesforce. The whole authentication process is delegated to the “Identity Provider”, i.e. all password management (expiry, complexity, reuse, etc.). Access management is indirectly delegated too (by disabling the user on their end).

What is not part of this solution:

Authorization management (i.e. roles and groups must still be maintained in Pricefx; or possibly by a custom integration job which syncs with Active Directory or similar system).
User provisioning (a matching user object has to exist in Pricefx; the same synchronization option as above can be employed).

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.

Configure SAML

You can configure Pricefx for single sign-on using SAML 2.0.

Go to Configuration > External Systems > SAML Configuration and click Add to create a new configuration.
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).
Make the required settings:
- NameID Mapping – Select the attribute from the User Management which contains the user ID which is also used by the IdP. 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.
- 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 IdP side, all the different reply URLs still have to be specified.)
- ADFS/Azure/O365/Okta federation metadata URL – If the IdP 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 IdP Provider URL – Enter the web address of the SAML SSO page of the Identity Provider.
- IdP Certificate – Paste the public certificate of the Identity Provider. It can be found in the IdP metadata. It is used to check the digital signature of the authentication request. If needed (some federation metadata IdPs provide multiple certificates), you can concatenate several certificates here, separated by the BEGIN and END tags.
  Example Expand source
```
-----BEGIN CERTIFICATE-----
MIIErDCCA5SgAwIBAgIOAVJBxy7NAAAAAEW0CPwwDQYJKoZIhvcNAQELBQAwgZAx
KDAmBgNVBAMMH1NlbGZTaWduZWRDZXJ0XzE0SmFuMjAxNl8yMDE1MTgxGDAWBgNV
BAsMDzAwRDU4MDAwMDAwSjBpNzEXMBUGA1UECgwOU2FsZXNmb3JjZS5jb20xFjAU
BgNVBAcMDVNhbiBGcmFuY2lzY28xCzAJBgNVBAgMAkNBMQwwCgYDVQQGEwNVU0Ew
HhcNMTYwMTE0MjAxNTE4WhcNMTgwMTE0MTIwMDAwWjCBkDEoMCYGA1UEAwwfU2Vs
ZlNpZ25lZENlcnRfMTRKYW4yMDE2XzIwMTUxODEYMBYGA1UECwwPMDBENTgwMDAw
MDBKMGk3MRcwFQYDVQQKDA5TYWxlc2ZvcmNlLmNvbTEWMBQGA1UEBwwNU2FuIEZy
YW5jaXNjbzELMAkGA1UECAwCQ0ExDDAKBgNVBAYTA1VTQTCCASIwDQYJKoZIhvcN
AQEBBQADggEPADCCAQoCggEBAMwkls4jyq6+x7oy4YOhIy7S38qXvS1iqXDrm//P
XduiHBnuSGDCrp+BbIe5RVJa5V9oKUl8H+tORgygn6PRsWBUaT1XArZ17H2nlS7O
yD/KrfkIxnVOekTnDvpCj5pL99cxMJ2GwfEgvuGHzsNU6Q19r4XE9rSIIBz1o44j
vcTfe6723ZnxTqPHOrPcQ7G20TYY4w//hz4W0zk69aCBPNewy49OEIQFDgxYqw5L
VMx9plIwBkUImeIhH+kB87WQxNZsNiVZFpV2BMY3HfzDcXsWh2bF9acOyoYObUdH
w+HYgSpDW40Cp26b8bfuUCcbXzkp+Dpj8n0UQHu+YMh6FxUCAwEAAaOCAQAwgf0w
HQYDVR0OBBYEFEsMeamXkO+Ao8wTUFkfvXMBj63FMA8GA1UdEwEB/wQFMAMBAf8w
gcoGA1UdIwSBwjCBv4AUSwx5qZeQ74CjzBNQWR+9cwGPrcWhgZakgZMwgZAxKDAm
BgNVBAMMH1NlbGZTaWduZWRDZXJ0XzE0SmFuMjAxNl8yMDE1MTgxGDAWBgNVBAsM
DzAwRDU4MDAwMDAwSjBpNzEXMAUGB1UECgwOU2FsZXNmb3JjZS5jb20xFjAUBgNV
BAcMDVNhbiBGcmFuY2lzY28xCzAJBgNVBAgMAkNBMQwwCgYDVQQGEwNVU0GCDgFS
QccuzQAAAABFtAj8MA0GCSqGSIb3DQEBCwUAA4IBAQAQXbLnTnp39x6zgNVT6UoD
I86zLkCdpmEqigx3oqRlWABrNKv/1SAwC82qDbyIxPKpJvRK7SOlxSYgkcEwr/bA
2YqGSqtjRV6sFiH1PkK1UrwZyc6l99HcH1uzBw+LIOWdF2w3QOdW6EnhRZvt7l7r
WUrzmnUQku1hUoCnI4UVHdUzSCt0aCCYO52ctolnH3qW5sEnRvHujsb5lDazP5F6
2hV3fyPrP6obZQBlzRbO3fucw6ThZVPzVvcTuErkRWnMZMkP688yuejYnspYF1M7
TgoEerTPtl512RIarvDVXSEhoOoB1ZAY8eFRBXigT8vWBVjS5X2dF6xyee+AwbjK
-----END CERTIFICATE-----
```
- Service Provider request signing private key (X.509, Base64 – needs to be RSA) - You can enter here a private key which will be used to sign the SAML request.
  This option is meant only for special cases when the IdP explicitly requires it.
- RelayStates – The RelayState parameter tells the Service Provider to which web page to redirect after a successful user login. By default, you are logged into Unity UI (with or without RelayState).
  - 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:
    /pricefx/martin/saml/signon?RelayState=MyRelayState--targetPage%3DpriceShopPage%26targetPageState%3D2147483799.Q
    The string right of the double dash delimiter will be appended to the relay state URL.
  - There are four placeholders supported in the RelayState parameter:
    - USERNAME
    - PARTITION
    - SSOSELECTOR – If the relay state URL is not the default URL, then the relay state URL should contain this placeholder – without that the auto-relogin will not work in the Classic UI.
    - 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 relay state called “PricefxStudio”. It does not redirect anywhere but emits an HTML response that allows the user to copy the JWT token into the clipboard easily. 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:
    https://qa.pricefx.eu/pricefx/mvich/saml/signon/?RelayState=URL--aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbQ==
    The part after the "URL--" prefix is a base64-encoded URL (https://www.google.com in this example).
    It can be a full URL or a relative one. Parameter substitution for USERNAME, PARTITION, SSOSELECTOR and LOCALE are still applied before sending the redirect.
  - Note that the parameter is case sensitive and must always be "RelayState".
  - See also /wiki/spaces/KB/pages/3380904153.
The customer (using Azure as ID provider) may ask you for the "Identifier (Entity ID)" and "Reply URL". In both cases, the URL https://www.pricefx.eu/pricefx/<partition>/saml/signon (provide the right DNS name and partition) should be used. In case you are using a dedicated instance with a hostname other than "www.pricefx.eu", use your hostname instead.
It is recommended to use a Pricefx metadata file which allows you to automatically configure SAML for Pricefx on the IdP side.
You can generate the metadata file via an API endpoint:
/pricefx/partition/admin.generateFederationMetaData
or
/pricefx/partition/admin.generateFederationMetaData/<SAML config name>
Log on using the URL from the previous step to validate the SSO logon.

If there are more SAML Configurations in one partition, e.g.
https://customer.pricefx.eu/pricefx/partition/saml/consume/DEFAULT?RelayState=quoteConfigurator
https://customer.pricefx.eu/pricefx/partition/saml/consume/IPSTAGE?RelayState=quoteConfigurator
then you need to add the configuration name, e.g. IPSTAGE to the URLs – then this configuration set is used. If you do not specify it, it means that the DEFAULT is used. (Also, pay attention to the configuration name casing – it must be kept in the URL.)

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 by adding the parameter "trailingIdSlash" : false.

Auto-provisioning

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

This is controlled via JSON tags in the standard samlConfiguration app property. The tags are:

JSON Tag	Values	Notes
`enableAutoProvisioning`	Boolean true/false	If this tag is not present in the config, false is used.
`defaultProvisioningBR`	String <role name>	Default business role to assign to the new user. If empty/null, no role is assigned.
`provisioningAttributeMappings`	Hashmap<String,String>	Info on how to extract user information from the SAML response AttributeStatement tags.

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.

Other Required Steps

Provide Specific URL

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 options 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: https://www.pricefx.eu/pricefx/<partition>/saml/signon

Configure IdP

In order to make the SSO configuration work, there is also configuration on the IdP side required. Pricefx needs to be defined there as a trusted/known service provider. The configuration procedure and terminology used there is different for every IdP provider and the information you have to enter in the SAML configuration section varies too. Please contact your IdP administrator to provide you with this information. At a minimum, you need the IdP URL and the IdP certificate.

Notes on AuthnContext

If you get an error during the login complaining about AuthnContext, for example AADSTS9002: One AuthnContextClassRef or AuthnContextDeclRef entry is expected in RequestedAuthnContext, add the following line in the Configuration > Advanced Configuration Options > samlConfiguration in the configuration (typically named DEFAULT):
```
"authnContexts": [
      "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
],
```
AuthnContexts is related to all messages related to the selected/used authentication method, for example AADSTS75011 Authentication method <Method used by ADFS user> by which the user authenticated with the service doesn't match requested authentication method <defined in SAML>.
To make it work, the supported one needs to match the used one, if possible. It seems that Azure's AD FS requires it in cases when they are different than the used FORM auth.
```
"authnContexts": [
	"urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified",
	"urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport",
	"urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos",
	"urn:federation:authentication:windows"
],
```

Configuration in Okta

When setting up Okta to integrate with Pricefx, you do not need to define Pricefx as a custom application – it is already included in the list of pre-integrated apps.

Pricefx Classic Documentation

SAML Configuration