1. SAML 2.0 Fundamentals

SAML 2.0 (Security Assertion Markup Language 2.0) is an XML-based open standard that enables secure exchange of authentication and authorization data between organizations. In the context of iCIMS, SAML allows your organization’s identity provider (IdP) to authenticate users and pass their identity information to iCIMS securely.

Key SAML 2.0 Components

• Identity Provider (IdP): Your organization’s authentication system (Okta, Azure AD, OneLogin)
• Service Provider (SP): iCIMS application that relies on the IdP for authentication
• Assertion: XML message containing user identity and authentication data
• Metadata: XML configuration describing SAML endpoints and certificates
• Binding: HTTP mechanism for exchanging SAML messages (typically HTTP-POST or HTTP-Redirect)

SAML 2.0 Authentication Flow

1. User visits iCIMS login page and clicks “Login with SSO” 2. iCIMS redirects user to the identity provider’s login page 3. User authenticates with IdP (username/password or MFA) 4. IdP creates a SAML assertion containing user identity information 5. IdP redirects user back to iCIMS with signed SAML assertion 6. iCIMS validates the assertion and creates user session 7. User is logged in and can access iCIMS

2. Supported Identity Providers

iCIMS supports SAML 2.0 integration with any compliant identity provider. The most common implementations are:

Okta

Okta is an identity and access management platform that provides enterprise-grade SSO. The integration process involves creating a SAML 2.0 app in Okta, configuring assertion consumer service URL, attribute mappings, and then uploading the Okta metadata to iCIMS.

Azure Active Directory (Azure AD)

Azure AD is Microsoft’s cloud-based identity service integrated with Office 365 and other Microsoft services. Azure AD’s SAML integration requires configuring iCIMS as an Enterprise Application in Azure AD, setting up assertion consumer service URL, and mapping Azure AD attributes to iCIMS user attributes.

OneLogin

OneLogin is a unified access management platform supporting multiple authentication methods. OneLogin’s SAML configuration for iCIMS involves creating an iCIMS SAML application, configuring parameters like RelayState, and setting up attribute mappings for user synchronization.

3. Attribute Mapping Best Practices

Attribute mapping is crucial for successful SSO implementation. It determines how user data from your identity provider is mapped to iCIMS user profiles.

Essential Attributes

• Email (nameID): Unique identifier for user, must match iCIMS email
• First Name: User’s given name
• Last Name: User’s family name
• Display Name: User’s full name for display purposes

Custom Attributes

Many organizations use custom attributes for department, cost center, location, or role information. These custom attributes can be mapped to iCIMS user fields for automated profile updates and workflow routing.

Attribute Mapping Configuration

In your identity provider:

1. Navigate to SAML attribute mapping settings
2. Map IdP attributes to SAML assertion attribute names
3. Ensure email attribute is correctly mapped as nameID
4. Test attribute mapping before enabling production SSO
5. Document all custom attributes for troubleshooting

4. Certificate Rotation Procedures

SAML certificates are crucial for securing the authentication exchange. Regular certificate rotation maintains security and prevents login disruptions.

Certificate Rotation Best Practices

• Annual Rotation: Rotate certificates annually or per organizational security policy
• Advance Planning: Plan certificate rotation 30 days in advance
• Test Environment: Always test in non-production first
• Dual Certificates: Maintain both old and new certificates during transition period
• Communication: Notify users of any potential login disruptions

Certificate Rotation Steps

1. Generate new SAML certificate in your identity provider
2. Export the new certificate public key
3. Upload new certificate to iCIMS SSO configuration
4. Verify both old and new certificates are active
5. Test SSO login with new certificate in non-production environment
6. Monitor logs for any certificate-related errors
7. Once verified, deactivate the old certificate in IdP
8. Remove old certificate from iCIMS after transition period

5. Common SSO Errors and Solutions

Here are the 5 most common iCIMS SSO errors and how to resolve them:

Error 1: “SAML Response Signature Invalid”

Cause: The SAML assertion signature doesn’t match the IdP’s certificate.

Solution:

• Verify the IdP’s public certificate is correctly uploaded to iCIMS
• Ensure the certificate hasn’t expired
• Check that certificate format matches iCIMS requirements (typically PEM format)
• Confirm the IdP is signing SAML assertions with the correct certificate

Error 2: “User Not Found” or “Invalid User”

Cause: The email attribute in the SAML assertion doesn’t match an iCIMS user account.

Solution:

• Verify the email attribute is correctly mapped in the IdP
• Ensure the user exists in iCIMS with the exact email address
• Check for case sensitivity issues (email should be lowercase)
• Verify the email attribute name matches iCIMS configuration
• Check if user is in correct iCIMS tenant/account

Error 3: “SAML Response Expired”

Cause: The SAML response has an invalid or expired timestamp.

Solution:

• Sync system clocks between IdP server and iCIMS server
• Check time difference doesn’t exceed the NotOnOrAfter attribute (typically 5 minutes)
• Adjust clock skew tolerance in IdP configuration if necessary
• Verify both systems have correct timezone settings

Error 4: “Assertion Consumer Service URL Mismatch”

Cause: The ACS URL in SAML assertion doesn’t match iCIMS configuration.

Solution:

• Obtain the correct ACS URL from iCIMS SSO configuration
• Update the ACS URL in IdP to exactly match iCIMS configuration
• Ensure protocol (http vs https) matches exactly
• Verify trailing slashes and URL paths match precisely

Error 5: “Destination Attribute Missing or Invalid”

Cause: The SAML Destination attribute doesn’t match the iCIMS assertion consumer URL.

Solution:

• Verify Destination attribute is set in IdP SAML configuration
• Confirm Destination matches the ACS URL exactly
• Check that IdP is including Destination in all SAML assertions
• Review IdP logs to see what Destination is being sent

Frequently Asked Questions