SAML settings and requirements

xMatters supports IdP-initiated SSO with POST Binding.

All communication between the IdP and xMatters must be made over an encrypted channel (HTTPS) using HTTP POST.

Responses from the IdP must be Base-64 encoded, and responses and assertions must be signed. Individual elements within a SAML message must not be independently signed. xMatters expects the SAML response or assertion to have a nested signature section in the IdP's signature and certification information. xMatters compares this information to the certificate stored at xMatters to validate the authenticity of the message.

Encrypting Assertions

xMatters can accept encrypted or unencrypted assertions from the IdP. By default, xMatters accepts unencrypted assertions unless encryption assertion is explicitly enabled.

To configure encrypted assertions for SAML 2:

1. Contact your xMatters representative and ask them to enable encrypted assertions on your system. Once this feature is enabled, xMatters will accept both encrypted and unencrypted assertions so that it can continue to authenticate existing unencrypted requests from the IdP.
2. Once the encrypted assertions feature has been enabled, go to Admin > Company Details. In the SAML Configuration section, and click the View Metadata link.
3. Locate the certificate that is contained within the <ds:X509Certificate> tag, and send it to your IdP.

Once your IdP has successfully installed the certificate, it will begin to send encrypted assertions to xMatters.

You can access xMatters metadata by clicking the View metadata link on the Security Settings page in the Single Sign-On section, or by appending /saml/metadata to your company URL.

Example

If a company has the following URL:

https://mycompany.na1.xmatters.com

The SAML metadata can be located at this URL:

https://mycompany.na1.xmatters.com/saml/metadata. 

You must provide your IdP with the xMatters URL that consumes assertions sent from the IdP. You can obtain this URL by appending /sp/SSO.saml2 to the end of your xMatters URL.

If a company has the following URL:

https://mycompany.na1.xmatters.com

The assertion consumer URL can be located at this URL:

https://mycompany.na1.xmatters.com/sp/SSO.saml2

You can see the assertion claim URL in the SubjectConfirmationData element in SAML responses.

<saml:SubjectConfirmationData NotOnOrAfter="2014-06-16T17:30:29Z" Recipient="https://mycompany.na1.xmatters.com/sp/SSO.saml2"/>

This identifier is a unique representation of identity provider.

To locate this value in the SAML assertion file find the <Issuer>, <saml:Issuer>, or <saml2:Issuer> element.

Example

The following examples shows the identity provider ID within the <saml:Issuer> tag.

<saml:Issuer>https://app.onelogin.com/saml/metadata/654321</saml:Issuer>

<saml:Issuer>MyCo:SAML2.0:UAT</saml:Issuer>

The Audience is a unique identifier that the identity provider uses to identify xMatters. This value is often a URL but may be any unique identifier such as a name or numeric ID.

You can locate the Audience value in the SAML response in the <Audience>, <saml:Audience>, or <saml2:Audience> element.

Example

<saml:Audience>https://myco.na1.xmatters.com</saml:Audience>

This is the URL of the identity provider's Single Sign On (SSO) login page. Users must first log in here before they can access xMatters using SSO. xMatters redirects users to this page when they log out or when they attempt to access an xMatters page without having an active session.

Example 

https://app.onelogin.com/trust/saml2/http-post/sso/654321

If this value is configured, clicking the log out button in xMatters redirects the user to the user provided URL, bypassing the xMatters log out page. This value is optional.

Example 

https://app.onelogin.com/trust/saml2/http-redirect/slo/654321

Ask your identity provider to provide a public key certificate for each of your production and non-production instances.

xMatters uses this certificate to verify that SAML responses have been transmitted securely and originate from the identity provider. Once you obtain this certificate file, contact xMatters to install it on your system. SAML settings do not take effect until the certificate is installed.

Certificate requirements

xMatters supports X.509 certificates encodings:

• PEM-encoded
• DER-encoded
• CER-encoded

xMatters identifies who is being authenticated by matching the user names from the IdP to xMatters users. xMatters can map the user name from the IdP to either the Web Login ID or User ID. You'll need to find out how your IdP identifies users and see whether it matches the Web Login ID or the User ID.

If the user names of the IdP do not match either the Web Login ID or User ID, you'll need to adjust how you identify users in xMatters. The easiest way to do this is to set the Web Login ID field to match the user name provided by the IdP. The Web Login ID is not usually used when Single Sign-On is configured, because users do not log in through the xMatters web user interface (except those users who have permission to log in natively).

For more information about viewing User IDs and Web Login IDs, see User Profile.

Example

If the IdP identifies users by email address (for example, jdoe@example.com) and xMatters identifies users by employee ID (for example, 329992) in both the User ID and Web Login ID fields, set the Web Login ID to contain the user's email address.  You can then map identity provider user names to the Web Login ID field.

Some SAML implementations define the user name in the <NameID> element and others define the user in an attribute. You'll need to know whether your IdP specifies the user name in the <NameID> element or in an attribute, and if it defines the name in an attribute you also need to know the name of the attribute.

NameID

When the user is defined in the <NameID> element, it is located with in the <Subject> element in SAML assertions. (These elements may be named <saml:NameID> and <saml:Subject>, or <saml2:NameID> and <saml2:Subject>.)

Example

<Subject>
  <NameID>mmcbride@example.com</NameID>
</Subject>

Attribute

When the name is stored as an attribute, it is stored in the <Attribute> element of assertions. (This element may be named <saml:Attribute> or <saml2:Attribute>.)

Example

In this example the name is stored in an attribute named "uid".

<saml2:Attribute FriendlyName="uid"
    Name="urn:oid:1.3.6.4.1.5932.1.1.6"
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-fomrat:uri>
    <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs-string">       mmcbride@example.com
     </saml2:AttributeValue>
</saml2:Attribute>