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).
-
I. In versions prior to IIQ7.0, path is:
https://iiq.example.com/identityIQ/dashboard.jsf.
-
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:
-
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
-
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
-
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
-
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?
