Register Sign in Need help? FAQ SailPoint directory
Help
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Show  only  | Search instead for 
Did you mean: 

IdentityIQ SAML support guide

IdentityIQ SAML support guide

 

Overview

From--https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language. 

Security Assertion Markup Language (SAML, pronounced sam-el) is an XML-based, open-standard data format for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider. The standard was developed by The OASIS Security Services Technical Committee (SSTC) in 2001. The current standard is SAML 2.0.

SAML identifies three entities—a principal, a service provider (SP) and an identity provider (IdP). The principal is the user who needs to access a service, the SP is the service the principal needs to access, and the IdP is the source for authentication.

The IdP is an application like Microsoft’s Active Directory Federation Service (ADFS), Shibboleth, Ping, or Okta. Two configurations are created and stored in the metadata on the IdP. The first is the configuration of the IdP. This includes information like the URL of the IdP’s single sign-on service (SSO), a private key, and a base 64 encoded x509 certificate. The second configuration is for each individual SP. This includes data like the Entity ID, the URL of the SP (called the assertion consumer service), and possibly a logout URL. 

SAML applications can be configured to receive a request for authentication from the principal or from the SP, to check the credentials provided against a directory service like Active Directory or LDAP and to generate and send a security token to the SP.  Two scenarios are typically configured on the IdP.

 

IdP initiated SAML

In IdP initiated SAML, the principal enters the IdP’s URL in a browser and is redirected to the IdP which prompts the principal for credentials. The IdP then verifies the credentials against a directory service like Active Directory. If the credentials can be validated successfully, the IdP generates a SAML assertion and encapsulates it in a SAML response and sends it to the SP using the information stored in the metadata for the SP. The SP validates the SAML assertion and provides access to hosted resources according to its own security policy.

 

SP initiated SAML

In SP initiated SAML, the principal enters the URL of a protected resource on the SP in the browser. The SP checks for a valid authentication session for the principal and if it does not find one, it creates an authn request, redirects the browser to the IdP and sends the authn request to the IdP. The IdP then attempts to validate the principal’s credentials against a directory service. If successful, the IdP will generate a SAML assertion, encapsulate it in a SAML response, and send the response to the SP. The SP validates the SAML assertion and redirects the user to the protected resource the principal originally requested.

 

Relay state

Relay state is an important concept in SP initiated SAML. It is a value stored on the SP when the authn request is created. It specifies the protected resource the principal originally requested. Relay state is also sent to the IdP with the authn request. When the IdP creates a SAML response and sends it to the SP’s assertion consumer service URL it will also redirect the user’s browser to the URL stored in the relay state.

 

Audience restriction

Another important concept in SAML is the Audience Restriction.  The Audience restriction is returned to the SP in the SAML response from the IdP, and the SP validates it. The value the IdP sends is not directly configurable.  It is derived from the EntityID, so best practice is to set the EntityID in the IdP and in IIQ to the domain of the IIQ servers (https://iiq.example.com).  During the SAML validation performed on the SAML response, IIQ matches the assertion consumer service to the audience restriction.  As long as the audience restriction is contained in the URL of the assertion consumer service, the audience restriction will be validated.

 

Multiple IdentityIQ UI/task servers

In the event that an environment has multiple IIQ UI/Task servers, the SAML configuration established on the first UI server is global.  SAML is enabled in the System Configuration object and the configuration is stored in a single SAML Configuration object that is used by all servers in the environment.

 

Digital signing in IdentityIQ SAML

As of version IIQ 7.0p4, it is possible to use out of the box functionality to sign SAML responses and assertions, but not authn requests sent from IIQ to the IdP. To sign the SAML responses or assertions, enable the functionality on the relying trust in the IdP. Then, use HTTP-Post in IIQ as the binding method. Signing is required by HTTP Post method.

 

IdentityIQ configuration parameters

**A SAML vulnerability exists in some IIQ versions.  The vulnerability is fixed in 6.3p8, 6.4p8, 7.0p4, 7.1

It is recommended to request a copy of the metadata in xml format from the IdP service administrator before configuring these values in IIQ. To access the SAML configuration page in IIQ, choose Global Settings>Login Configuration>SSO Configuration. Then enable SAML Based Single Sign-on (SSO).

Each of the parameters is described below:

 

SAML URL (Assertion Consumer Service) — The URL of the SSO service on the SP(IIQ).

  1. I.  In versions prior to IIQ7.0, path is:

    https://iiq.example.com/identityIQ/dashboard.jsf. 

  2. II.  In version IIQ7.0 and later, path is:

    https://iiq.example.com/identityIQ/home.jsf.

 

EntityID

The entityID is established in the IdP's trust metadata for the SP (IIQ).  The entityID from the IdP trust metadata should be entered in IIQ as the entityID. It is recommended (but not mandatory) that the IdP administrator use the IIQ server base URL (e.g., https://iiq.example.com) as the entityID when configuring the SP trust on the IdP.

 

Identity provider SSO service URL

URL to access the SP (IIQ) trust metadata on the IdP. This is often not the base URL of the IdP.  Consult the documentation for the IdP to determine the location of trust metadata on the IdP.

 

Identity provider issuer URL

This is the value sent in the SAML response that is used to identity the IdP to the SP (IIQ). If this value matches the idpService URL configured in IIQ, the Issuer field should be left blank. If the value returned to IIQ does not match the idpService URL entered in IIQ, the value that is contained in the SAML response should be entered in the Issuer field in IIQ.

 

Binding Method — the http method used by the SP to bind and send an authn request to the IdP and by the IdP to return a SAML response. The method is either Post or Redirect. For signed SAML responses or assertions, the HTTP Post method must be used. The value will be stored in the metadata from the IdP and must be the same on IIQ and the IdP.

 

Authentication match

Three new SAML configuration attributes will allow you to set authentication match, spNameQualifier, and class reference settings. The three string attribute names are authnContextClassRef, authnContextComparison, and spNameQualifier which should be set to strings. The permittable values for authnContextComparison are minimum, maximum, better, or exact. If no settings are provided for override, values default to exact, and urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport.

 

NameID format

The type of the subject identifier in the SAML assertion the SP (IIQ) will use to identify the Principal (IIQ identity) requesting access. In the authn request SP sends to the IdP, this value tells the IdP the type of subject identifier to send to SP in the SAML assertion returned by the IdP.

 

Four types are supported on the IdP:

  1. urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

  2. urn:oasis:names:tc:SAML:2.0:nameid-format:transient

  3. urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

  4. urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

 

Type 4 is the default value. When the SP declares the NameID Format to be unspecified, it is telling the IdP to decide which type of subject identifier will be used.  The DefaultNameIDFormat configuration parameter on the IdP is used by the IdP to determine which type to send.

 

Sample SAML configuration for ADFS

Entity ID=""https://yourhost.com" --URI for the IIQ Server
Identity Provider SSO Service URL="https://yourhost.com/adfs/ls"--URL for ADFS Service--replace domain but leave the path if using ADFS
Identity Provider Issuer URL (IIQ7.0p4 and later)="https://yourhost.com/adfs/services/trust-- URL for replying party trust
SAML URL (Assertion Consumer Service)="https://yourhost.com/identityiq/home.jsf" --Host for IIQ (path should end in dashboard.jsf for IIQ versions earlier than IIIQ7.0)

Binding Method=POST --Set on ADFS Server

NameId Format="unspecified" --Use samAccountName mapped to NameID in ADFS claim rule, unspecified on IIIQ

Public X.509 Certificate—the base 64 encoded certificate for the IdP.  The certificate is stored in the IdP metadata and can be copied and pasted into IIQ.

Correlation Rule--Supplied IDN Correlation Rule

 

Sample SAML configuration for Ping

Entity ID="https://iiq.example.com"--IIQ URL presented to IdP.  Should match SP trust metadata on IdP

Identity Provider SSO Service URL="https://idp.tokenservice.com/idp/startSSO.ping?PartnerSpId=https://iiq.example.com"--location of IIQ metadata on IdP

Identity Provider Issuer URL ="idp.tokenservice.com<https://IdP.tokenservice.com>:saml2:entityId"--Issuer value sent from IdP

SAML URL (Assertion Consumer Service)=" https://iiq.example.com.org/dashboard.jsf”--IIQ URL

Binding Method=POST --Set on ADFS Server

NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">-- type of subject identifier IIQ expects to receive from IdP

Public X.509 Certificate—the base 64 encoded certificate for the IdP.  The certificate is stored in the IdP metadata and can be copied and pasted into IIQ.

SAML Correlation Rule—a rule used to correlate accounts on the IdP with identities in IIQ.  A sample rule for Identity Now is provided, but can be altered for environmental requirements.

 

Sample SAML Configuration for Okta

Configure SAML based single sign on with IIQ using Okta

 

Troubleshooting

Logging

SAML errors are best logged by adding the following to the log4j.properties file:

log4j.logger.sailpoint.web.sso=all

 

Next reload logging configuration on the debug page.  Then, reproduce the error.

 

Authn Request and SAML Response

The most effective method for troubleshooting SAML issues is to obtain a copy of the the authn request sent by IIQ and the SAML response returned from the IdP. The SAML response will contain the SAML assertion. The values can then be compared and adjusted in the IIQ SAML configuration to resolve issues.

 

The autn request can be captured by enabling the tracing mentioned above. The SAML response can be captured by reproducing the error while using one of the tools listed below. The SAML response will be base 64 encoded and will need to be decoded before the values in the response can be examined.

 

X509 Error with Windows Hello

By default, the SAML library provided with the IdentityIQ supports Windows authentication.
So only the users authenticated by the Windows authentication method would be able to access the IdentityIQ URL.
Windows has other methods of authentication as well, like Windows Hello Pin which replaces passwords with strong two-factor authentication.

Users using the Windows Hello Pin authentication method would not be able to access the IdentityIQ URL, as there will be a conflict in the authentication method used to authenticate the user logging into Windows and accessing IdentityIQ URL and will see the X509 multifactor error.

 

Common Errors and Resolution

sailpoint.web.sso.SAMLSSOResponseValidator:163 - Issuer value: https://idp.example.com does not match issuer IDP:

The Issuer value is blank. Set the issuer parameter to the value contained in the SAML response.

 

sailpoint.web.sso.SAMLSSOResponseValidator:163 - Issuer value: https://idp.demo.com does not match issuer IDP: https://idp.example.com/sso/SSORedirect/metaAlias/demo/idp

The value in the issuer field is incorrect. Set the Issuer parameter to the URL displayed in the error.

 

sailpoint.web.sso.SAMLSSOResponseValidator:270 - Assertion does not contain unique subject provider identifier https://iiq.example.com in the audience restriction conditions

Audience is not directly configurable. It is derived from the Entity ID. Set the Entity ID in IIQ to match the audience restriction value in the SAML response.

 

Tracing the communication

Several tools are available to trace the SAML communication between IIQ and the IdP. The Developer Tools in Chrome (CNTRL/SHIFT/i), Network tab can be used to trace the communication. Fiddler is stand-alone application and SAML Tracer is a plug-in available for Firefox. Each of these can be used to capture a base64 encoded SAML response. Comparing the SAML response with the authn captured in the IIQ log using the traces above will help troubleshoot SAML failures.

 

References

IdentityNow SAML Integration to IdentityIQ

SAML Configuration Guide

How can I capture a SAML trace to troubleshoot SSO problems?

Labels (2)
Comments
tedfpt
‎Jun 07, 2023 01:53 AM
‎Jun 07, 2023 01:53 AM

Is there example configure SAML for Keycloak?
Thank you!

ssalens2
‎Sep 29, 2023 10:33 AM
‎Sep 29, 2023 10:33 AM

With the SAML correlation rule, how should we deal with null pointers? As in if there is truly not a federated user to match on? If I return null it throws exceptions.

gauravlohiya
‎Nov 08, 2023 05:54 AM
‎Nov 08, 2023 05:54 AM

The SSO error mentioned above for Windows Hello under section: "X509 Error with Windows Hello" can be resolved by adding the AuthnContextClassRef attribute to the SAML xml and setting the value of that attribute to urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified.

However, this is not exposed on the UI and need to be added in the XML manually.

Version history
Revision #:
9 of 9
Last update:
‎Sep 21, 2023 03:42 PM
Updated by:
Community Administrator
 
View Article History