☰ Close Navigation
How SAML Works

iCIMS Talent Platform provides Single Sign-On (SSO) service by acting as a service provider supporting basic SAML v2.0 Web Browser SSO Profile using HTTP Redirect or HTTP Post Bindings.  iCIMS SAML SSO offering is modeled after Google Apps SAML SSO service.

Note:

  • iCIMS does not support "Single Logout." When a user logs out, they are ending their iCIMS-specific session, but are not logged out of the client's network server.
  • iCIMS does not support encrypted assertions.

Disclaimer

This technical reference assumes the reader is generally knowledgeable with SAML and does not define any terminology unless specific to the iCIMS Talent Platform’s SAML SSO integration.

iCIMS Talent Platform (SP)

To enable SAML SSO in the iCIMS Platform, please contact iCIMS and provide the following three required pieces of information:

  1. Certificate: RSA or DSA Certificate containing the Public Key in PEM format (Base64 Encoded DER)

    • Note: Must contain "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" statements
  2. Sign-In Page URL or the Identity Provider (e.g., https://IDP.EXAMPLE.ORG/IDP/SAML2/Redirect/SSO)
  3. Name ID Format: Mapping information regarding the “Name ID Format” – email, login name (case sensitive), external id, or system id

Additional (Non-Required) Options:

  • Use a customer specific issuer – issuer value sent in the SAML request can be icims.com or CUSTOMER.icims.com
  • Enable SSO for specific Portals
  • Enable Deep Link SSO – SSO Variables available when composing email in the iCIMS Talent Platform
  • Sign-Out Page URL – URL to redirect users if they signed-in using SAML SSO

Note: Enabling SAML Deep Link SSO will replace existing URL variables with SAML SSO-appropriate URL variables (available when composing email in the iCIMS Talent Platform).

Web Browser SSO Profile

  • iCIMS Talent Platform (SP) uses the HTTP Redirect Binding to transmit the AuthnRequest to the IdP.
  • iCIMS Talent Platform (SP) supports the HTTP POST Binding when receiving the SAMLResponse from the IdP.
Deep Link

Note: iCIMS technical support does not have the ability to consult with the development team or IT staff in regard to updating servers due to the impact this may have on the client's current environment. Please consult with your Information technology team or vendor if you have questions about your version's compatibility.

Deep Link Variables

SSO deep link variables can be used in Compose Email. iForms also support SSO, but only via these variables.

SAML Portal SSO

Note: iCIMS technical support does not have the ability to consult with the development team or IT staff in regard to updating servers due to the impact this may have on the client's current environment. Please consult with your Information technology team or vendor if you have questions about your version's compatibility.

To SSO into an internal Career Portal, append a RelayState parameter to the URL that requests the creation of a security context at iCIMS. The RelayState parameter is the URL-encoded destination on the PORTALURL. iCIMS Portals support both SP (Service Provider) and IDP (Identity Provider) initiated SSO. However, IDP links are not built or maintained by iCIMS. All examples below are based on SP initiated links.

https://CUSTOMER.icims.com/icims2/servlet/icims2?module=Root&action=samlAuthnRequest&RelayState=PORTALURL

The RelayState parameter is the URL-encoded destination on the PORTALURL:

https://PORTAL-CUSTOMER.icims.com/r.jsp

Note: A setting must be enabled within the iCIMS Talent Platform in order to allow the ability to use SSO on the Portal. Contact iCIMS Technical Support for assistance. 

Two common use cases for Internal Career Portal SSO are described below.

SSO into the Dashboard on an Internal Career Portal

To create a link that will SSO an employee into their Dashboard on an Internal Career Portal, structure the URL as shown below. 

Generic URL Structure: https://CUSTOMER.icims.com/icims2/servlet/icims2?module=Root&action=samlAuthnRequest&RelayState=https%3A%2F%2FPORTAL-CUSTOMER.icims.com%2Fr.jsp%3Fredirect%3Ddashboard

  1. Replace "CUSTOMER" with the Platform Name (e.g., "TestPlatform")
  2. Replace "PORTAL-CUSTOMER" with the Portal Name and Platform Name (e.g., "CareersTest")

Final Result: https://TestPlatform.icims.com/icims2/servlet/icims2?module=Root&action=samlAuthnRequest&RelayState=https%3A%2F%2FCareersTest-TestPlatform.icims.com%2Fr.jsp%3Fredirect%3Ddashboard

SSO into a Specific Job on the Internal Career Portal

To create a link that will SSO an employee into a specific job on the Internal Career Portal, structure the URL as shown below. 

Generic URL Structure: https://CUSTOMER.icims.com/icims2/servlet/icims2?module=Root&action=samlAuthnRequest&RelayState=https%3A%2F%2FPORTAL-CUSTOMER.icims.com%2Fr.jsp%3Fjd%3DJOBSYSTEMID

  1. Replace "CUSTOMER" with the Platform Name (e.g., "TestPlatform")
  2. Replace "PORTAL-CUSTOMER" with the Portal Name and Platform Name (e.g., "CareersTest")
  3. Replace "JOBSYSTEMID" with the job's System ID (e.g., "1013")

Final Result: https://TestPlatform.icims.com/icims2/servlet/icims2?module=Root&action=samlAuthnRequest&RelayState=https%3A%2F%2FCareersTest-TestPlatform.icims.com%2Fr.jsp%3Fjd%3D1013

SAML SSO Flow

Note: iCIMS technical support does not have the ability to consult with the development team or IT staff in regard to updating servers due to the impact this may have on the client's current environment. Please consult with your Information technology team or vendor if you have questions about your version's compatibility.

SSO Flow

1. User's browser requests creation of a security context at iCIMS:

https://CUSTOMER.icims.com/icims2/servlet/icims2?module=Root&action=samlAssertionConsumerService

2. iCIMS redirects user's browser to the SSO Service at the IdP with a SAML Authentication Request and a Relay State URL (optional):

https://IDP.EXAMPLE.ORG/IDP/SAML2/Redirect/SSO?SAMLRequest=AUTHNREQUEST&RelayState=RELAYURL

The SAMLRequest parameter is the deflated, base64-encoded, and URL-encoded of the following <samlp:AuthnRequest> element:

<?xml version="1.0" encoding="UTF-8"?>

<samlp:AuthnRequest

                                        xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"

                                        ID="_6d8ba793be822fa138c821039b275636"

                                        Version="2.0"

                                        IssueInstant="2012-09-13T14:24:30.047-04:00"

                                        ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

                                        ProviderName="icims.com"

AssertionConsumerServiceURL="https://CUSTOMER.icims.com/icims2/servlet/icims2?module=Root&amp;action=samlAssertionConsumerService"

                                        IsPassive="true">

                    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">icims.com</saml:Issuer>

</samlp:AuthnRequest>

The SAMLRequest is unencrypted and not signed.

The RelayState token is an opaque reference to state information maintained at iCIMS.

3. IdP performs a security check.

4. IdP responds with a document containing an XHTML form:

<form method="post" action="https://CUSTOMER.icims.com/icims2/servlet/icims2?module=Root&amp;action=samlAssertionConsumerService" ...>

   <input type="hidden" name="SAMLResponse" value="SAMLRESPONSE" />

   <input type="hidden" name="RelayState" value="RELAYURL" />

   ...

   <input type="submit" value="Submit" />

 </form>

The value of the SAMLResponse parameter is the deflated, base64-encoded, and URL-encoded of the following <samlp:Response> element:

<?xml version="1.0" encoding="UTF-8"?>

<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"

                                        Destination="https://CUSTOMER.icims.com/icims2/servlet/icims2?module=Root&amp;action=samlAssertionConsumerService"

                                        ID="_b2e93a6db58d0402bb27e8e743ee8675" InResponseTo="_6d8ba793be822fa138c821039b275636" IssueInstant="2012-09-13T18:24:31.476Z" Version="2.0">

                    <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://IDP.EXAMPLE.ORG/IDP</saml2:Issuer>

                    <saml2p:Status><saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></saml2p:Status>

                    <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_302fd92335209a3c500c8172867d8938" IssueInstant="2012-09-13T18:24:31.476Z" Version="2.0">

                                        <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://IDP.EXAMPLE.ORG/IDP</saml2:Issuer>

                                        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

                                                            SIGNATURE INFORMATION

                                        </ds:Signature>

                                        <saml2:Subject>

                                                            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="https://IDP.EXAMPLE.ORG/IDP">NAMEID</saml2:NameID>

                                                            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">

                                                            <saml2:SubjectConfirmationData Address="10.0.0.5" InResponseTo="_6d8ba793be822fa138c821039b275636"

                                                                                                    NotOnOrAfter="2012-09-13T18:29:31.476Z" Recipient="https://CUSTOMER.icims.com/icims2/servlet/icims2?module=Root&amp;action=samlAssertionConsumerService"/>

                                                            </saml2:SubjectConfirmation>

                                        </saml2:Subject>

                                        <saml2:Conditions NotBefore="2012-09-13T18:24:31.476Z" NotOnOrAfter="2012-09-13T18:29:31.476Z">

                                                            <saml2:AudienceRestriction><saml2:Audience>icims.com</saml2:Audience></saml2:AudienceRestriction>

                                        </saml2:Conditions>

                                        <saml2:AuthnStatement AuthnInstant="2012-09-13T18:23:51.447Z" SessionIndex="5d27c3b79e585b2a20b75d7d9f0faa6fe0b927d3d8c24bcecfa84c098592add5">

                                                            <saml2:SubjectLocality Address="10.0.0.5"/>

                                                            <saml2:AuthnContext><saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocol</saml2:AuthnContextClassRef></saml2:AuthnContext>

                                        </saml2:AuthnStatement>

                    </saml2:Assertion>

</saml2p:Response>

The SAMLResponse must contain an unencrypted but signed assertion and must use UTF-8 encoding. The NAMEID in the payload above can be of type: Login Name, Email Address, Person System ID or Person External ID. The type for the NAMEID must be defined on the client platform and must match.

The value of the RelayState parameter is preserved from step 2.

5. The user's browser issues a POST request to the assertion consumer service at iCIMS.

6. iCIMS' assertion consumer service processes the response, creates a security context, and redirects the user's browser to the target resource:

https://CUSTOMER.icims.com/icims2/servlet/icims2?module=Root&action=showNavigator

Tools Available to Debug Issues:

Sample IdP Setup using ADFS 2.0 or 3.0

Before following the steps below, please ensure that your ADFS 2.0 or 3.0 installation has been validated. Review this article for information on setting up a test WIF application to validate your ADFS configuration. In addition, you must install all hotfixes and updates included in Rollup 2 to be fully compatible with iCIMS. This will be necessary for logging into portals using IDP Initiated RelayState. Please review this article for more information.

Note: iCIMS technical support does not have the ability to consult with the development team or IT staff in regard to updating servers due to the impact this may have on the client's current environment. Please consult with your Information technology team or vendor if you have questions about your version's compatibility.

Add iCIMS Metadata

The ADFS IdP must know some basic information about the iCIMS relying party, which is defined in SAML metadata. The easiest way to do this is to create a new IDP_HOME/metadata/icims-metadata.xml file with the following contents. There is much more information that could be added here, but this is the minimum required to get things working. Be sure to replace CUSTOMER with your database name.

<?xml version="1.0" encoding="UTF-8"?>

<EntityDescriptor entityID="icims.com" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">

    <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

        <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified</NameIDFormat>

        <AssertionConsumerService index="1" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

            Location="https://CUSTOMER.icims.com/icims2/servlet/icims2?module=Root&amp;action=samlAssertionConsumerService" />

    </SPSSODescriptor>

</EntityDescriptor>

Alternatively, instead of creating an XML file, you can manually configure the SAML values. The minimum required values for manual configuration are listed below. Note that the URL used for manual configuration is slightly different than the URL used in the XML file. 

Setup Relying Party Trust

  1. Right click on the relying party trust created and select Edit Claim Rules.

  2. Click Add Rule to create new claim rule.  When the wizard appears, select Send LDAP Attributes as Claims and select next.

  3. Give the claim rule a name (e.g., Email Address to Name ID) and select Active Directory as the attribute store.  In the LDAP Attribute tab, select Email Address to select the email address attribute for the user.  In the Outgoing Claim Type, select Name ID to send the attribute as the Name ID.  This attribute should match the Name ID format communicated as part of the original information provided to iCIMS.  Then select finish.

Sample IdP Setup Using Shibboleth

Note: iCIMS technical support does not have the ability to consult with the development team or IT staff in regard to updating servers due to the impact this may have on the client's current environment. Please consult with your Information technology team or vendor if you have questions about your version's compatibility.

Install Shibboleth

A wiki page on the installation of Shibboleth can be found at the following link: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPApacheTomcatPrepare

Add iCIMS Metadata

The Shibboleth IdP must know some basic information about the iCIMS relying party, which is defined in SAML metadata. The easiest way to do this is to create a new IDP_HOME/metadata/icims-metadata.xml file with the following contents. There is much more information that could be added here, but this is the minimum required to get things working. Be sure to replace CUSTOMER.

<?xml version="1.0" encoding="UTF-8"?>

<EntityDescriptor entityID="icims.com" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">

    <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

        <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified</NameIDFormat>

        <AssertionConsumerService index="1" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

            Location="https://CUSTOMER.icims.com/icims2/servlet/icims2?module=Root&amp;action=samlAssertionConsumerService" />

    </SPSSODescriptor>

</EntityDescriptor>

Configure Relying Party

Instruct Shibboleth how to behave when talking to iCIMS by defining a new RelyingParty element in IDP_HOME/conf/relying-party.xml. The following snippet should be added just after the DefaultRelyingParty element. Be sure to replace the provider attribute to include your entity ID (use whatever provider is configured in the DefaultRelyingParty, ex: https://CUSTOMER.icims.com/idp/shibboleth).

<rp:RelyingParty id="icims.com"

                    provider="YOUR-ENTITY-ID"

                    defaultSigningCredentialRef="IdPCredential">

    <rp:ProfileConfiguration xsi:type="saml:SAML2SSOProfile" encryptAssertions="never" encryptNameIds="never" />

</rp:RelyingParty>

Still in the IDP_HOME/conf/relying-party.xml file, configure Shibboleth to use the new metadata file you created earlier. Add the following MetadataProvider element next to the existing configured provider (it should have an id value of “FSMD”), making sure to replace IDP_HOME with your actual installation path.

<metadata:MetadataProvider id="IcimsSPMD" xsi:type="FilesystemMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"

                    metadataFile="IDP_HOME/metadata/icimssp-metadata.xml" maintainExpiredMetadata="true" />

Configure Attribute Resolve

iCIMS expects either login name, email, external id, or systemid of the user logging in to be passed as the SAML Name Identifier. Shibboleth’s attribute resolver must be configured to make this data available by modifying IDP_HOME/conf/attribute-resolver.xml. The following attribute definition provides a very basic method to do this by sending the principal name that was used to authenticate to the IdP.

Finally, configure the Shibboleth attribute filtering engine to release the principal attribute (encoded as a NameID) to iCIMS. Add the following XML snippet to IDP_HOME/conf/attribute-filter.xml alongside the existing policy elements.

Configure Login Handler

Shibboleth needs a login handler to perform a security check. Several authentication methods are supported.

See https://wiki.shibboleth.net/confluence/display/SHIB2/IdPUserAuthn.

A quick solution to test with is to use the IP address login handler. In IDP_HOME/conf/handler.xml, comment out all the other LoginHandlers and add the following XML snippet. This will allow anyone with an IP address between 10.50.0.0 and 10.50.255.255 to be authenticated as the user.  The username value is the Name ID sent back in the SAMLResponse that will be used to look up and validate the user. Replace NAMEID accordingly.

Configure Login Handler
Shibboleth needs a login handler to perform a security check. Several authentication methods are supported.

See https://wiki.shibboleth.net/confluence/display/SHIB2/IdPUserAuthn.

A quick solution to test with is to use the IP address login handler. In IDP_HOME/conf/handler.xml, comment out all the other LoginHandlers and add the following XML snippet. This will allow anyone with an IP address between 10.50.0.0 and 10.50.255.255 to be authenticated as the user.  The username value is the Name ID sent back in the SAMLResponse that will be used to look up and validate the user. Replace NAMEID accordingly.

Certificates

Shibboleth will generate a Private Key and Certificate (contains Public Key) during installation. The files are stored in IDP_HOME/credentials.

  • idp.key - Private Key used by Shibboleth to sign SAMLRequest.
  • idp.crt - Certificate containing Public Key.  Provide this to iCIMS.

To Generate New Keys Using OpenSSL:

      RSA Keys:

openssl genrsa -out rsaprivkey.pem 1024

openssl rsa -in rsaprivkey.pem -pubout -outform DER -out rsapubkey.der

openssl pkcs8 -topk8 -inform PEM -outform DER -in rsaprivkey.pem -out rsaprivkey.der -nocrypt

openssl req -new -x509 -key rsaprivkey.pem -out rsacert.pem

- rsaprivkey.pem becomes idp.key

- rsacert.pem becomes idp.crt

     DSA Keys:

openssl dsaparam -out dsaparam.pem 1024

openssl gendsa -out dsaprivkey.pem dsaparam.pem

openssl dsa -in dsaprivkey.pem -outform DER -pubout -out dsapubkey.der

openssl pkcs8 -topk8 -inform PEM -outform DER -in dsaprivkey.pem -out dsaprivkey.der -nocrypt

openssl req -new -x509 -key dsaprivkey.pem -out dsacert.pem

- rsaprivkey.pem becomes idp.key

- rsacert.pem becomes idp.crt