Introduction
The SAML Authentication Plugin allows users to login to CXO-Cockpit by using their Identity Provider authentication mechanism.
How to configure the SAML authentication adapter
SAML authentication adapter is configured in CXO-Cockpit 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 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. - 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.
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".