Service Provider Initiated

In this scenario

1. The principal requests a service from the service provider (e.g. access to a web resource within Product 360).

2. To provide this resource to the principal the service provider redirects user authentication (AuthRequest) to the identity provider.

3. In case the user is not yet authenticated at the Identity Provider, the IdP requests credentials from the user, e.g. by presenting a login form with username and password.

4. The IdP sends an identity assertion (SAML Assertion like a security token) for the principal. On basis of this assertion, the service provider can make a decision to provide the resource to the principal or not.

5. The SP ensures that the user is directed to the initially requested resource.

Identity Provider Initiated

In this scenario, there is no initial authentication request from the SP. Instead, the IdP provides links to the SP to certain SP resources. IdP initiated Single Sign On is started when clicking on such a link.

1. The user clicks on an IdP provided link to access a resource in the SP.

2. In case the user is not yet authenticated at the Identity Provider, the IdP requests credentials from the user, e.g. by presenting a login form with username and password.

3. The SP directly receives an identity assertion for the principal . On basis of this assertion, the service provider can make a decision to provide the resource to the principal or not.

4. The SP ensures that the user is directed to the resource given in the assertion information.

Create new certificate and keystore

To create a new JKS keystore from scratch, containing a single self-signed Certificate, execute the following from a terminal command line:

This command will create a new file under the specified (-keystore parameter) location. You will also need to reflect this new location in the Product 360 NetworkConfig.xml file in the <keystore> element.

After executing this command, you will first be prompted for the keystore password. You will also need to specify the custom password in the NetworkConfig.xml file, as described later.

Next, you will be prompted for general information about this Certificate, such as company, contact name, and so on. This information will be displayed to users who attempt to access a secure page in your application, so make sure that the information provided here matches what they will expect.

Finally, you will be prompted for the key password, which is the password specifically for this Certificate (as opposed to any other Certificates stored in the same keystore file). The key password as well as the specified alias (-alias parameter) you need to specify in the appropriate use case (HTTPS, SAML signing, SAML encryption) and there configuration files.

If everything was successful, you now have a keystore file with a Certificate that can be used by your Product 360 server.

Import existing certificate into keystore

If you already have a Certificate you can import it into your local keystore. First of all you have to import a so called Chain Certificate or Root Certificate into your keystore. After that you can proceed with importing your Certificate

Download a Chain Certificate from the Certificate Authority you obtained the Certificate from.

• For Verisign.com commercial certificates go to: http://www.verisign.com/support/install/intermediate.html

• For Verisign.com trial certificates go to: http://www.verisign.com/support/verisign-intermediate-ca/Trial_Secure_Server_Root/index.html

• For Trustcenter.de go to: http://www.trustcenter.de/certservices/cacerts/en/en.htm#server

• For Thawte.com go to: http://www.thawte.com/certs/trustmap.html

Import the Chain Certificate into your keystore

Finally you can import the CA certificate

Export existing certificates public keys for metadata usage

For the SAML metadata's you will need the public keys in a readable format, to get them execute the following commands from command line:

SAMLConfig.xml

In the configuration folder, there is a template for the SamlConfig.xml. Adapt it to fit to your needs, add the alias and password of your key and enable SAML:

If you want to use different keys for signing and encryption, you have to create multiple keys in the keystore. The following assumes the use of the same data for both actions.

entityId

assertionConsumerServiceLocation

signingKey

alias

password

encryptionKey

alias

password

wantAssertionsSigned

metadataLocation

disregardSslCertificate

forceAuthRequestsSigned

Microsoft AD FS

Shibboleth

OpenAM

Place your idp-metadata.xml into the subfolder saml of the Product 360 configuration folder or the defined location within your SamlConfig.xml.

In case your IdP does not provide any metadata you need to generate the idp-metadata.xml file from a template located in within the Product 360 configuration folder. The relevant information can alternatively be generated with the help of https://www.samltool.com/idp_metadata.php.

Within the metadata file you need to provide the URL to your IdPs SingleSignOnService location which accepts POST requests. (Example URL schema matches Shibboleth IdP)

Signing of AuthRequest (SP -> IdP)

If your IdP requires signed AuthRequest you need to enable this within Product 360. This can be done by setting the WantAuthRequestsSigned parameter within the idp-metadata.xml in the configuration folder to true.

While the SAML metadata specification does not require the WantAuthRequestSigned parameter within the IDPSSODescriptor some IdP Implementations might not set it explicitly, but nevertheless require a signature.

Additionally you need to provide an X509 certificate in your keystore and refer to it over the alias and password attribute in the <signingKey> element within the spMetadata section of your SamlConfig.xml

Signing of SAML Assertions (IdP -> SP)

The SAML metadata specification defines an parameter for requesting an IdP to sign the SAML Assertions this might not be enough for all IdPs and you might need to enable the signing of SAML assertions over another way, but to enable Product 360 to require signature validation on assertion level you need to set the WantAssertionsSigned parameter in SamlConfig.xml within you Product 360 configuration folder to true.

The signature of the assertion will be veryfied by Product 360 against the public key of the X509 certificate within your idp-metadata.xml

Encryption of SAML Assertions (IdP -> SP)

If your IdP supports assertion level encryption and the encryption is active, then you must provide your encryption public key X509 certificate within the metadata you provide to your IdP.
The IdP will use this public key to encrypt the SAML assertion and only the owner of the corresponding private key can encrypted the assertion. The best way of doing this is to get the metadata provided by Product 360 (see above).
This metadata already includes all certificates the IdP needs to know.

If Product 360 receives an encrypted assertion it will try to decrypted the assertion with the configured private key which is referenced by the <encryptionKey> in the SamlConfig.xml.

Signing of Provider Metadata

It is possible to sign the metadata itself to verify its validity. For that a

element is used. It contains information typically needed for signatures like digest and signature value, used algorithm and a certificate.
See https://www.w3.org/TR/xmldsig-core2/ for further detailed information.

In order for Supplier Portal to verify the signature of IdP metatadata, the corresponding certificate has to be

• provided by the IdP team

• added to the cacerts file of the Java used by Supplier Portal.

  keytool.exe -importcert -file "{cert}" -keystore "<JAVA_HOME>/jre/lib/security/cacerts" -alias "{alias}" -storepass {keystorePassword}

If during startup of the Supplier Portal server an error occurs while reading the metadata the cause can be outdated data inside the <ds:Signature> element or a wrong signature.
So ensure to get updated idp metadata and certificate from the IdP team.

In case the metadata is for an IdP and the IdP metadata is maintained as local metadata file on the Supplier Portal server, then the <ds:Signature> element provided by the IdP team can be completely commented out if not needed.
The local metadata file is unlikely to be tampered with and commenting out might comes in handy in case of signature deployment problems that could lead to errors mentioned before.

Configuration of the load balancer

Additionally to the default load balancing scenario (see Web Configuration), the module mod_rewrite has to be enabled.

For the usage of SSL (https) in your load balancer (Apache), stick to the official Apache documentation. The example below defines a virtual host supporting SSL and the additional directives necessary for SAML support.

The most important additional directives to be configured are listed below:

SSLProxyEngine On

ProxyPreserveHost On

RewriteEngine on    

RewriteCond %{REMOTE_HOST}  =server1  [OR]
RewriteCond %{REMOTE_HOST}  =server2
RewriteRule   "^/pim/(.+)"  "https://loadBalancer/pim/$1" 

IdP configuration