Configure SAML in xMatters

You must access xMatters as a Company Supervisor to configure these settings. For more information about obtaining the values for these settings, see SAML settings and requirements.

To configure SAML for xMatters:

1. Log on to xMatters as a Company Supervisor.
2. In the Admin menu, click Security Settings.
3. In the SAML section, under Single Sign-On, set the toggle button to Enabled to display the Configuration options.
4. Set the Identity Provider ID, Audience, and Single Sign-On URL fields, and Log Out Redirect (optional) to the values obtained by the identity provider. For more information on obtaining these values, see SAML settings and requirements.
   1. You can add a link to your company's SSO/SAML instructions or internal documentation in the Single Sign-On Help Link field. The link is added as a "Help" button to the error page that users see if they encounter an while error signing in.
5. Select the Log Out Redirect option to specify where users should be directed when logging out. If you don't select this option, users are automatically directed to the default xMatters logout page.
6. Set the Identifier Type to Web Login ID if the identity provider's user name maps to the xMatters Web Login ID and or set it to User ID if it matches the xMatters User ID.
7. Specify whether the user ID is defined in an attribute or in the NameID element.
   • If the user is specified in the NameID element set the value of Identifier Location to Subject NameID element.
   • If it is defined in an attribute, set the value of Identifier Location to Attribute Name Element and also specify the name of the attribute in the Attribute Name field.
8. Upload the certificate.
   • To upload a new certificate click Upload Certificate, locate and add the certificate, and click Open.
9. Click Save. Once SAML is enabled users are not able to log on to the xMatters web user interface and must log in through SSO (unless they have Enable Native Login enabled).

You may want to allow some users to bypass the Single Sign-On mechanism and log in to the xMatters web user interface using their Web Login ID and password. This can be useful to allow access to power users in the event that the Single Sign-On service becomes unavailable, or for accounts that don't belong to the authenticating system (such as users that access xMatters through APIs or data synchronization.)

To allow a user to log in natively after SSO has been configured, they must be a Company Supervisor or have a role that has been assigned the Enable native login for SAML function. As its name suggests, adding this function to a role allows any user with that role to log in to xMatters directly.

Once SAML SSO is enabled for your xMatters instance, users with permission to log in natively can do so by appending /sp/samlSignOn.do to the end of the company URL.

Example

https://myCompany.na1.xmatters.com/sp/samlSignOn.do

This example shows a sample configuration using the OneLogin identity provider. This OneLogin deployment identifies users by their email address. In this xMatters deployment, the Web Login ID contains the user's email address.

We've obtained the following settings from the identity provider. These settings are specific to the sample company and will be different than settings you receive from your identity provider.

Sample xMatters settings

In this example, we'll configure xMatters with the settings provided by the identity provider and set Identifier Type to Web Login ID, since both the IdP and the Web Login ID fields identify users by their email address.

Refer to the above table to see the complete text of the Identity Provider ID, Single Sign On URL, and Log Out Redirect fields, which are cut off in the following screenshot.

Sample OneLogin assertion

The following text shows a sample OneLogin assertion for this configuration. The Identity provider ID, the user ID in the NameID element, assertion claim url, and audience fields are displayed in bold.

<saml:Assertion xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Version="2.0" ID="Bc615070e3221e6c37cd065f640341282mom25907" IssueInstant="2014-06-16T17:27:29Z">
  <saml:Issuer>https://app.onelogin.com/saml/metadata/654321</saml:Issuer>
  <saml:Subject>
    <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">mmcbride@myco.com</saml:NameID>
    <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
    <saml:SubjectConfirmationData NotOnOrAfter="2014-06-16T17:30:29Z"
      Recipient="https://myco.na1.xmatters.com/sp/SSO.saml2"/>
    </saml:SubjectConfirmation>
  </saml:Subject>
<saml:Conditions NotBefore="2014-06-16T17:24:29Z" NotOnOrAfter="2014-06-16T17:30:29Z">
    <saml:AudienceRestriction>
      <saml:Audience>https://myco.na1.xmatters.com</saml:Audience>
    </saml:AudienceRestriction>
  </saml:Conditions>
  <saml:AuthnStatement AuthnInstant="2014-06-16T17:27:28Z" SessionNotOnOrAfter="2014-06-17Tau17:27:29Z" SessionIndex="_60d4d860-d7b0-0787-7d4e-782aea56fabb">
    <saml:AuthnContext>
      <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
    </saml:AuthnContext>
  </saml:AuthnStatement>
</saml:Assertion>

In this example the client is using the Ping Identity as the identity provider, which is installed on their own domain and identifies users by their first initial and last name. In our xMatters deployment, the User ID field also identifies users by first initial and last name.

We've obtained the following information from the identity provider. These settings are specific to the sample company and will be different than settings you receive from your identity provider.

Sample xMatters settings

In this case, we'll configure xMatters with the settings provided by the identity provider and set Identifier Type to User ID, since both the IdP and User ID fields identify users by first initial and last name. The following screenshot shows what this looks like in xMatters. Refer to the above table to see the complete text of the Identity Provider ID, Single Sign On URL, and Log Out Redirect fields.

Sample Ping Identity assertion

The following text shows a sample Ping Identity assertion for this configuration. The identity provider ID, user ID, assertion claim URL, and audience fields are displayed in bold. This assertion sends the user ID in both the NameID element and in an attribute. We have configured xMatters to read it from the uid attribute.

<saml:Assertion ID="S79NIq9vRMDm-LRo6PujqfVJ4do" IssueInstant="2014-06-10T19:20:55.075Z" Version="2.0 xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
  <saml:Issuer>MyCo:SAML2.0:UAT</saml:Issuer>
  ...
  <saml:Subject>
    <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">mmcbride</saml:NameID>
    <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
      <saml:SubjectConfirmationData Recipient="https://myco.na1.xmatters.com/sp/SSO.saml2" NotOnOrAfter="2014-06-10T19:23:55.075Z"/>
    </saml:SubjectConfirmation>
  </saml:Subject>
  <saml:Conditions NotBefore="2014-06-10T19:17:55.075Z" NotOnOrAfter="2014-06-10T19:23:55.075Z">
    <saml:AudienceRestriction>
      <saml:Audience>sso.xMatters.com</saml:Audience>
    </saml:AudienceRestriction>
  </saml:Conditions>
  <saml:AuthnStatement SessionIndex="S79NIq9vRMDm-LRo6PujqfVJ4do" AuthnInstant="2014-06-10T19:20:55.075Z">
    <saml:AuthnContext>
      <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef>
    </saml:AuthnContext>
  </saml:AuthnStatement>
  <saml:AttributeStatement>
    <saml:Attribute Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
      <saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">mmcbride</saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
</saml:Assertion>

This example shows a sample configuration using the Active Directory Federation Services (AD FS or ADFS) identity provider. This ADFS deployment identifies users by their email address. In this xMatters deployment, the Web Login ID contains the user's email address.

We've obtained the following information from the identity provider. These settings are specific to the sample company and will be different than settings you receive from your identity provider.

Sample xMatters settings

The following screenshot shows what this looks like in xMatters. Refer to the above table to see the complete text of the Identity Provider ID and Single Sign On URL fields.

Sample ADFS assertion

The following text shows a sample ADFS assertion for this configuration. The identity provider ID, the user ID in the NameID element, assertion claim URL, and audience fields are displayed in bold.

<samlp:Response ID="_9248b737-0c14-43e2-9eaa-a0288574c52d"
Version="2.0"
IssueInstant="2015-10-07T20:29:55.460Z"
Destination="https://myco.na1.xmatters.com/sp/SSO.saml2"
Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
>
  <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://myco.na1.xmatters.com/adfs/services/trust</Issuer>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
  </samlp:Status>
  <Assertion ID="_107f96bf-a119-4016-b64c-e9bc8d0dd475"
  IssueInstant="2015-10-07T20:29:55.460Z"
  Version="2.0"
  xmlns="urn:oasis:names:tc:SAML:2.0:assertion"
  >
    <Issuer>http://myco.na1.xmatters.com/adfs/services/trust</Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:SignedInfo>
        <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
        <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
        <ds:Reference URI="#_107f96bf-a119-4016-b64c-e9bc8d0dd475">
          <ds:Transforms>
            <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
            <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
          </ds:Transforms>
          <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
          <ds:DigestValue>Y7//omR8UiAAGDLTDjrtjrIeyHnKT9hlADtQ/Pmkogg=</ds:DigestValue>
        </ds:Reference>
      </ds:SignedInfo>
      <ds:SignatureValue>S0f6KxavbuEXv7+fviVfm61QwJZL9yR ... 6wwmqlhZ8ksbiSXs9ZLhcg==</ds:SignatureValue>
      <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIIC7DCCAdCgAwIBAgIQVPBMuI8qAbxHIIlpXdg ... 7EP+Pd5a0gA6w==</ds:X509Certificate>
        </ds:X509Data>
      </KeyInfo>
    </ds:Signature>
    <Subject>
      <NameID>mmcbride@myco.com</NameID>
      <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <SubjectConfirmationData NotOnOrAfter="2015-10-07T20:34:55.460Z"
        Recipient="https://myco.na1.xmatters.com/sp/SSO.saml2"
        />
      </SubjectConfirmation>
    </Subject>
    <Conditions NotBefore="2015-10-07T20:29:55.457Z"
    NotOnOrAfter="2015-10-07T21:29:55.457Z"
    >
      <AudienceRestriction>
        <Audience>https://myco.na1.xmatters.com</Audience>
      </AudienceRestriction>
    </Conditions>
    <AuthnStatement AuthnInstant="2015-10-07T20:29:55.381Z"
    SessionIndex="_107f96bf-a119-4016-b64c-e9bc8d0dd475"
    >
      <AuthnContext>
        <AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</AuthnContextClassRef>
      </AuthnContext>
    </AuthnStatement>
  </Assertion>
</samlp:Response>

If you are having trouble with your SAML deployment, it can be helpful to inspect the SAML response and confirm that the settings in the response match the settings you have configured in xMatters. See SAML settings and requirements for more information about each setting.

You may also want to use one of the many SAML support tools available. To find an appropriate SAML troubleshooting tool, check the following resources:

• Your identity provider may provide SAML support and debugging tools.
• Web browsers offer extensions that allow you to view SAML responses.
• Some websites contain online tools that encode and decode SAML responses.