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 OASISSecurity 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 in6.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).
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.
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.
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
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.
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.
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.
For question "Usually, only UI servers are configured with load balancer and load balancer URL is used for SSO. So, if a user tries to access load balancer URL, everything will work fine. But if the user tries to access one of the task servers URL, the user is directed to IdP for authentication and after authentication it throws 404. I believe 404 is thrown because load balancer is not aware of task server URL. Can you please advice how task servers can be accessed in this case? Do we need to configure task servers also at load balancer?"
I dont understand the answer can someone help me on its clarification.???
Azure configuration "App Registrations" Entity ID / Application ID URI = https://<IIQ host> Reply URL (ACS URL) / RedirectURI = https://<IIQ host>/identityiq/home.jsf Sign on URL = https://<IIQ host>/identityiq
IIQ IdP configuration Entity ID / Issuer = https://sts.windows.net/<tenant id> SSO Login URL = https://login.microsoftonline.com/<tenant id>/saml2 Public X.509 Certificate = <certificate provided by Azure admin>
IIQ SP configuration Entity ID / Issuer = https://<IIQ host> SAML URL (ACS) = https://<IIQ host>/identityiq/home.jsf SAML Binding = HTTP Post SAML Name ID Format = unspecified SAML Correlation Rule = Map the NameID ((String)assertionAttributes.get("nameId");) to identity. It must be "nameId". "NameId" or "NameID" does not work.
IIQ Objectbrowser -> Configuration Objects -> SAML Configuration Add the following line to <SAMLConfig ... (to solve AADSTS75011 issue)
"The Services team at SailPoint has a customization available for signing authn requests. Contact your Customer Success Manager for assistance with this customization."
Does anyone know if this is still the case in 2022? What was the justification that lead to authn request signing being left out?
IIQ IdP configuration Entity ID / Issuer = http://<ADFS server>/adfs/services/trust SSO Login URL = https://<ADFS server>/adfs/ls/ Public X.509 Certificate = <certificate provided by ADFS admin>
You find this information in the ADFS metadata (https://<ADFS server>/FederationMetadata/2007-06/FederationMetadata.xml)
IIQ SP configuration Entity ID / Issuer = https://<IIQ host> SAML URL (ACS) = https://<IIQ host>/identityiq/home.jsf SAML Binding = HTTP Post SAML Name ID Format = unspecified SAML Correlation Rule = Map the NameID ((String)assertionAttributes.get("nameId");) to identity. It must be "nameId". "NameId" or "NameID" does not work.
IIQ Objectbrowser -> Configuration Objects -> SAML Configuration Add the following line to <SAMLConfig ...
To enable SSO for IIQ 8.3 on IBM WebSphere Application Server or IBM WebSphere Liberty it might be necessary to add the following key to the System Configuration:
<entry key="noIdpSameSiteNone" value="true"/>
Without this key the user is redirected to the IdP and back and gets into a loop.
Is there a way to export SAML SP metadata from IIQ to import into an IDP? Currently trying to setup SAML for the first time and our IDP only has an option to import the SAML XML metadata file to configure the SP.
Hi @swilliams, unfortunately there is no option to generate metadata in IIQ. But you could generate a metadata file online. Search for "saml metadata generate", tehre are some tools. You could use some dummy data for the online form, if you don't want to provide the data from your system. Just change the values for your environment after you downloaded the file and send it to the IdP team.
