An external guide to help understand Halo's SAML 2.0 integration. This document focuses mainly on versions past 2.104.1 as many new features were added in this version. Some references to previous versions will be added.
Key Terms
Identity Provider (IdP) – a service that stores and verifies user identity. Examples of identity providers include Azure, Okta, Google, and Shibboleth.
Service Provider (SP) – receives and accepts authentication assertions from an IdP. Halo are an example of a service provider.
Assertion – an assertion is a message that is exchanged between the IdP and the SP. The assertion contains information allowing the service provider to identify the user that is trying to log in (such as the email address of the user). When configuring the IdP, many of the options you see will vary the format of the assertion and the data that is contained within it.
Metadata – metadata files are often exchanged between IdPs and SPs. A metadata file contains information that describes how each provider expects the data in requests to be transferred. For example, an IdP metadata file will contain information about the certificate that will be used to sign any SAML requests/assertions. The SP can consume this metadata file and from it deduce what certificate is going to be signing any requests sent to it via the IdP. If a request was ever then received that has been signed with a different certificate, the login request could be rejected.
Understanding the Login Flow
There are two different types of SAML login flow – an IdP-initiated flow and an SP-initiated flow. IdP-initiated flows are only supported on versions of Halo greater than 2.104.1.
SP-Initiated Flow
An SP-initiated flow means that the SP starts the login flow. This means the SP sends an initial request to the IdP. This request will contain a unique identifier which will be referred to later. The user then signs in using the IdP's authentication service. Once authenticated, the IdP sends a request back to the SP – this request contains an assertion. The SP then validates the assertion and decides whether or not to sign the user into the application.
One of the properties of the request sent from the IdP to the SP is an InResponseTo property. This value is equal to the unique identifier mentioned above that was included in the initial request sent from the SP to the IdP. The SP checks that the value of the InResponseTo property matches the unique value that was sent in the initial request to the IdP. If it doesn't match, then the SP will reject the login request.
There are multiple ways of getting the IdP to send back data to the SP, all of which can be configured within the IdP itself. In Halo, we ask that it is sent back via HTTP-POST. We do not support any other methods. If you ever see a message in Halo that refers to a missing or invalid InResponseTo property, then it is very likely the user has used an IdP-initiated flow instead of an SP-initiated flow.
IdP-Initiated Flow
An IdP-initiated flow is often referred to as click-to-access. It skips out the initial step of an SP sending a request to an IdP. Instead, the IdP will contain a list of applications that the user should be able to access. The user will navigate to the IdP rather than the SP to start the login flow. Once authenticated, they will select the application they wish to open, which will trigger the IdP to send the login request containing the assertion to the SP (hence the phrase click-to-access).
IdP-initiated flows are only supported in some identity providers. They are only supported in Halo in version 2.104.1 and above but require extra configuration to make it work. This will be covered later.
IdP-initiated flows are slightly less secure than SP-initiated flows because no InResponseTo value will be contained in the requests sent from the IdP to the SP.
Exchanging Metadata
As mentioned above, it is common practice for SPs and IdPs to exchange metadata files. The idea is that the SP can consume an IdPs metadata file, and the SAML implementation can be automatically configured in the SP, something that we're about to see. In versions before 2.104.1, we did not support uploading IdP metadata files, so the configuration had to be determined manually.
Not all IdPs support uploading SP metadata files, which is usually where the integration is configured incorrectly. An example of an IdP that does support uploading SP metadata files is Azure. Okta is an example that doesn't. We're going to focus on Okta as an example in this guide.
In Halo, there are three buttons at the top of the SAML configuration page.
Clicking the Upload IdP Metadata button will allow you to choose a metadata file downloaded from your IdP.
The login URL is the URL where we send our initial request in the SP-initiated flow. The logout URL is where we would send the user if they log out of Halo, but this field is not required.
The X509 Certificate for signature validation is the certificate that will be used to sign all SAML requests that are sent to us by the IdP. We will examine the requests they send and confirm that the thumbprint in this field matches the thumbprint of the certificate. If you ever see an error message saying that the thumbprint has not matched, then it means that the value stored in Halo is not correct and does not match the certificate used to sign the request from the IdP.
Clicking the Download Metadata button will generate a metadata file for Halo. The content of the metadata file will vary based on the options you have chosen in the Halo Configuration section of the setup screen. If you change any of these values, then a new metadata file must be generated.
Here is a brief overview of what each field does.
1. Assertion Endpoint – this is the endpoint where the IdP should send requests. /account/samlresponse and /account/saml2 should never be used, it is only available for those who implemented SAML with Halo a long time ago. /account/saml is the new preferred endpoint. This endpoint uses a new component to help us validate the assertion in a better way. It also provides much more detailed error messages, a full list of possible error messages is provided later in the guide.
2. Allow single sign-on for agents and/or users – this field determines whether login via SAML should be available on the agent application, or the end-user portal.
3. SAML User matching attribute – By changing the setting "SAML User matching attribute" to "Custom Attribute" you can specify an attribute other than NameId to match users on when logging in using SAML.
4. User/Contact Matching Field – this field determines which Halo field should be used to match the NameId property (or custom attribute) in the SAML assertion. You should always choose Email Address unless the customer wants to map a different field to the NameId property in the IdP. Every IdP will have a configuration option allowing you to choose this. Here is the example from Okta:
5. Login Button Colour and Logo – this determines the colour of the login button on the Halo login screen, and also the logo that shows on the button.
6. Automatically initiate the login flow without showing the Halo login screen – this means that when navigating to Halo, the user will automatically be redirected to the IdP. This redirect process sends a request from Halo to the IdP, starting the SP-initiated flow.
7. Sign AuthnRequests send to the identity provider – enabling this will sign any requests sent from Halo to the IdP using one of our certificates. The details of the certificate that is used will be included in the metadata file that can be generated. Enabling this setting also uses a new component to generate and send the request to the identity provider. We recommend that new SAML implementations use this.
8. Accept login requests that are initiated via the identity provider – enabling this setting allows IdP-initiated sign-in flows. The only change this makes in Halo is that we no longer check for the InResponseTo property when this feature is enabled.
To configure an IdP-initiated flow for the Halo agent application, the IdP must be configured so that an additional client_id query parameter is added to the end of the assertion URL (the URL of the SP where the IdP should send the login request).
If an IdP does not support uploading an SP's metadata file, then you can click the IdP Configuration button. This gives you a few of the basic values that must be added to the configuration in the IdP.
Configuring the IdP
The trickiest part of any SAML implementation is configuring the IdP. Every IdP has slightly different capabilities meaning the configuration and also the language used will also slightly vary between IdPs, although they all conform to the same standards. Using Okta, we will try to cover all of the common options that you may be asked to configure in an IdP. We have ignored settings that are Okta-specific or not important.
1. Single Sign-On URL (Assertion/Assertion Consumer Service URL) – this is the URL where the IdP sends data back to once the user has signed in using the IdP authentication service. It is always your Halo auth server URL followed by your chosen endpoint. If configuring an IdP-initiated flow, then there would be an additional query string on this.
2. SP Entity ID (Audience URL) – this is the URL of your Halo instance. It is NOT the URL for the auth server, just the instance.
3. Name ID Format – this is the value that will be mapped to the NameId property in any SAML assertions sent from the IdP. We always recommend choosing Email Address, as described above.
The following advanced settings are also important:
1. Response – this property is asking if the SP wants the response that is sent to it from the IdP to be signed with a certificate. The answer is always yes. It is a requirement of SAML that at least the response or the assertion is signed by the IdP.
2. Assertion Signature – same as above, but asking if we want the assertion to be signed. This should also always be yes – Halo code specifically checks to see if the assertion has been signed correctly.
3. Signature/Digest Algorithm – this should always be SHA-256.
4. Assertion Encryption – we do not currently support encrypted assertions. We will be adding support for this at a later date. Encrypting assertions adds an extra layer of security to the sign-in process by encrypting the request which is sent from the IdP to the SP as well as signing it.
5. Signature Certificate and Signed Requests – if you wanted to, you could upload the certificate that we use to sign our SAML requests and then enable Signed Requests. This means Okta would verify that our requests are being signed with the uploaded certificate, adding an additional layer of security. In many instances, this would be done by uploading our SP metadata into the identity provider. Unlike for IdPs, it is not a requirement for the SP to sign their SAML requests, so you do not need to do this. We recommend to make sure that the login process first works without the IdP checking for signed requests. Once you're happy it's working, you can then look to enable the feature.
Debugging a SAML Issue
Here are all of the possible errors and how to resolve them:
| Error Message | What is the resolution? |
| The SAML module has not been enabled. | Enable the module. |
| The SAML request was denied by the identity provider | This message will be followed by an error returned from the IdP. The error will indicate what part of the Halo SAML request the IdP does not like, which should direct the user to the appropriate invalid configuration in their IdP. |
| The SAML response is not signed. | Make sure SAML requests are being signed by the IdP. There should be a setting for this, or it will be done by default. |
| Encrypted assertions are not supported. | Disable encrypting of assertions in the IdP. |
| SAML response does not include an assertion property. | This means that the request from the IdP is not a valid SAML request. You should never see this error message. |
| Invalid certificate. | The SAML response from the IdP does not contain certificate data. Make sure that the IdP is signing both the SAML request and the assertion. It's unlikely you'll encounter this error. |
| Invalid signature. | The signature for the SAML request/assertion is not correct. This means the signature in the request has been signed using a different certificate than the one it says it's using in the request. Again, just make sure that the IdP is signing both the SAML request and the assertion. It's unlikely you'll encounter this error. |
| Invalid InResponseTo value. IdP-initiated sign-ins can be enabled in the SAML module. | The SAML assertion does not contain an InResponseTo value, and IdP-initiated flows have not been enabled in Halo. You need to either use an SP-initiated flow or correctly configure the IdP-initiated flow. This is the other common issue. |
| The assertion has expired. | You should never see this error. It is there to prevent old assertions from being used, which usually indicates a malicious request. |
| The audience condition has not been matched. | The entity ID configured in the IdP has been configured incorrectly. Make sure it is your Halo instance URL, not the auth server URL. Make sure this is all lower case, without a trailing slash on the end. |
| The assertion does not contain a valid NameId property. | This usually means the NameId property has not been configured at all in the IdP, or Unspecified may have been chosen as the NameId format. Make sure email address or another valid value is chosen. |
| Unable to find return URL. | This error indicates that the response does not contain an InResponseTo property, so an IdP-initiated flow has been used. However, the IdP-initiated flow has not been configured correctly – the client_id query parameter has not been added to the end of the assertion URL or the client_id is incorrect. Follow the section of this document on how to enable IdP-initiated flows. |
| Error in SAML configuration or user not found | This error should only show now when the user cannot be found in the Halo database using the NameId property of the SAML request. You should make sure the user does actually exist in the database. |
For further assistance please contact the halo support team.
