Introduction

The SAML Authentication Plugin allows users to login to CXO by using their Identity Provider authentication mechanism.

How to configure the SAML authentication adapter

Make sure the server can authenticate against the metadata URL (it should have internet access, or at least access to the microsoft URL)

SAML authentication adapter is configured in the CXO Configurator tool.

To enable the authentication adapter you have to set AuthenticationProvider setting to "SAML" and click "Save" button

SAML authentication settings can be set from "Authentication settings" action on "Maintenance" tab.

Below is detailed list of all available settings.

Identity Provider Metadata URL (required)
URL to the metadata of Identity Provider.
Identity Provider EntityId (required)
The EntityId parameter is the unique identifier of the identity provider. EntityId can be obtained from metadata file of the Identity Provider (entityID attribute)
Username claim (optional)
Claim name which will be used for mapping users authenticated by Identity Provider and CXO users. By default nameidentifier claim (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier) will be used. If you decide to use different claim, make sure that the claim is unique within your Identity Provider.
Note: nameidentifier claim should be always sent by Identity Provider even if "username claim" parameter is set to different value.
*Claimtypes that are often used:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
Signing Certificate Location Type (required)
Signing certificate is used for signing logout requests to the Identity Provider. The certificate can be loaded from either a file or from a certificate store.
It is recommended to use certificate store in production environment. The private key from the certificate will be used for signing messages send by Service Provider (CXO-Cockpit). The public key will be exposed in the metadata file of the Service Provider (CXO-COCKPIT) and should be used by Identity Provider to verify that messages were sent by Service Provider (CXO-Cockpit).
Signing certificate has to be a x509 certificate with a private key. If you are using x509 certificate for SSL, you can use the same certificate for signing SAML requests. Please contact your Identity Provider, in order to check requirements about signing certificate.
The Identity Provider should trust the Certificate Authority which issued signing certificate used by Service Provider (CXO-Cockpit).
Signing Certificate Path (required if Signing Certificate Location Type set to "File")
File Path to the signing certificate. The certificate should not be password protected
Signing Certificate Store Name (required if Signing Certificate Location Type set to "CertificateStore")
Specifies the X.509 store name to search for the certificate. For example, My includes personal certificates.
Signing Certificate Store Location
Specifies the location of the store to search for the certificate.
Signing Certificate x509FindType
Specifies the field that will be search for a match to the value in "Signing Certificate Find Value".
It is recommended to use "FindBySerialNumber" option.
Note: If you use "FindBySerialNumber" option make sure that copied serial number does not have spaces.
Make sure that there is no hidden character before the first hex digit (When copying a serial number from the certificate info it might happen that a hidden character will be added before the first hex digit)
Signing Certificate Find Value
Specifies a search term to use to find the certificate. The value will be searched for in the field specified by the "Signing Certificate x509FindType" attribute.

Important! Service account should have read access to the private key of the singing certificate. In order to check that:
- Find the singing certificate in the certificate store.
- Right click → All tasks → Manage Private Keys

- Add the user to the list. make sure that Read Permission is checked.

Outbound Signing Algorithm
- Specifies signing algorithm for outbound messages. The same value must be set on IDP side.

AuthnContext ClassRef
- Specifies URI reference identifying authentication context class.
- Can contain full URN (e.g. urn:oasis:names:tc:SAML:2.0:ac:classes:WindowsProtectedTransport) or only class name (e.g. WindowsProtectedTransport).
- Note: If not set, RequestedAuthnContext element will not be sent to IDP.
AuthnContext Comparison
- Specifies the comparison method used to evaluate the requested context class. If not set, ‘Exact’ value is used.
- Note: This setting is used only if AuthnContext ClassRef is not empty.
Use HTTP-POST binding for Authn request
- Enforces HTTP-POST authentication request binding for SAML.
- If this option is enabled the metadata will no longer be automatically (every hour) reloaded from IDP. In order to reload metadata (e.g. due to signing credentials change) CXO web application must be restarted.
- Note: this option should not be enabled unless HTTP-Redirect binding is not preferred on the client side (e.g. due to MS 208427 - maximum-url-length-is-2-083-characters-in-internet-explorer)

Please make sure that "CXO-Cockpit Dashboard Url" setting has correct value. CXO-Cockpit Dashboard Url setting is used for generating Service Provider (CXO-Cockpit) metadata file.

How to access Service Provider (CXO-Cockpit) metadata file

You can access CXO-Cockpit metadata by opening the link: {CXO-Cockpit-url}/AuthServices

The metadata file contains all the information which Identity Provider requires (e.g. AssertionConsumerService, SingleLogoutService, EntityId)

Note: This url is only accessible when the Authentication Provider is set to "SAML". The CXO-Cockpit webiste should be restarted after making any authentication configuration change. The website can be restarted on the Maintenance page of the Configurator

How login mechanism work

The login mechanism consists of two parts.

In order to login to the CXO-COCKPIT you have to first login to your identity provider and then be registered in CXO-COCKPIT.

If you are not registered in CXO-COCKPIT, but you are authorized by identity provider you will see message similar to the one displayed below:

If you didn't specify any "Username claim" in SAML authentication settings, then your "nameidentifier" claim will be displayed on the login screen.

Otherwise claim of type specified in the "Username claim" setting will be displayed.

In order to grant a user access to the CXO-COCKPIT, create a new user and set the username to the claim displayed on the login screen.

In order to add the first user to the system you have to first set authentication type to "Proprietary", add a user and then change

authentication type back to the "SAML".