Guide

Easily enable centralized Single Sign-On for your organisation with SAML 2.0 integration. Members of your organisation can sign-in to Ostorlab with their work email.

For a specific example, refer to one of our integration guides:

• Azure Active Directory
• Google Workspace
• Okta
• OneLogin

Terminology

• IdP stands for Identity Provider. An IdP is a service that acts as a user directory.
• SP stands for Service Provider. A service provider relies on an identity provider for authentication.
• IdP Metadata XML is the XML configuration document provided by your IdP. It contains public information about your user directory, which can be used by the service provider to make authentication requests.

Configuration Properties

The following are the only properties you will really be configuring when you set up SAML SSO with your IdP.

Name	Other Names	Required
Single sign on URL	AssertionConsumerService (ACS) URL	Yes
Entity ID	Metadata or Audience URL	Yes
Default relay state	Start or Application Start URL	No
Name identifier format	Name Identifier, Name, Name ID format	Yes

Entity ID

Required

The (SP) entity ID is a URL where a service provider publishes public information about its SAML configuration. The metadata document published by the service provider shows its public certificate that can be used to verify the signature of authentication requests initiated from the service itself.

Note: The IdP also has an entity ID. However, the IdP’s entity ID is used to uniquely identify the specific tenant/organization within that IdP. When you are configuring the SAML SSO, you are almost always asked to enter the SP entity ID, which will be specific to your organization in Ostorlab.

Assertion Consumer Service (ACS) URL / Single Sign On URL

Required

This is the URL where the IdP can POST SAML assertions.

Assertion Consumer Service Binding

Required

Identifies the protocol binding supported by the ACS. Bindings describe how the assertion and any enclosing content are packaged by the IdP (or by the browser in some cases) for consumption by the ACS

Name ID format

Required

The name ID format is one of the most important aspects of your SAML SSO configuration. It defines how an identity provider identifies a user on the downstream service. The value of the format defines what value would be used for the user’s Subject.

Important: Once your name ID format is configured and your users have started to use SSO, DO NOT change the name identifier. That will prevent your users from being able to sign in

(Default) Relay State

The relay state is a URL, which itself is passed as a query parameter in SSO requests initiated by the identity provider. This is an optional property. This is also known as deep-linking. This allows a user to directly navigate to a downstream service by launching the application from the identity provider itself.

Usage:

Configure your SAML integration:

1. Click on the side-bar button
2. Click on Library
3. Navigate to Integrations
4. Click on the SAML integration

From the Saml integrations menu, select the configuration tab and fill in the following values: 1. Idp Identifier : URI - Identifier of the IdP entity: e.g. https://your_domain.com/saml/metadata/connector_id 2. SAML 2.0 Endpoint : URL Target of the IdP where the Authentication Request Message will be sent; e.g., https://your_domain.com/saml2/http-post/sso/connector_id 3. X.509 Certificate : Public X.509 certificate of the IdP.

In your SAML identifier configuration, make sure to use the following settings for the Service provider of Ostorlab:

• Entity Id: https://api.ostorlab.co/saml/metadata/
• AssertionConsumerService URL: https://api.ostorlab.co/saml/acs/?org=<organisation_prefix>

  <organisation_prefix> in the URL is where your Ostorlab organisation’s prefix must be entered. You can find your org’s prefix in your organisation's settings page.

• Assertion Consumer Service Binding: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
• NameIDFormat: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

For existing accounts, users must whitelist the identity provider to enable logging using the SSO. To do so:

1. Go to the Account security menu.
2. In the Single Sign-On sub-menu, select the organisation from the list of supported identity providers.

New accesses without an existing account will automatically provision a new account with proper access to the SSO organization.

Troubleshooting

Validation error while trying to save an IdP-provided metadata XML

The IdP-provided metadata XML contains several XML elements, of which the is the element of concern to Ostorlab. In the IDPSSODescriptor, we expect to see a valid KeyDescriptor public key certificate, a NameIDFormat, an entity ID identifying your organization in the IdP, and an SSO binding.

The failure is typically due to one of the following reasons:

• Malformed XML
• KeyDescriptor public key certificate in the IDPSSODescriptor has expired
• KeyDescriptor public key certificate is missing n the IDPSSODescriptor
• NameIDFormat does not have the expected value or is completely missing. See the next troubleshooting topic for help on this.

  Tip: OneLogin has a suite of free SAML-related tools.

Name ID Format is invalid

As mentioned in the Name ID Format section, Ostorlab expects specific values in your IdP metadata XML. Use One Login’s XML Pretty Print to pretty print your XML and look for <NameIDFormat> under the <IDPSSODescriptor> XML element.

If you cannot find an element called NameIDFormat, add the following line immediately after the closing tag for KeyDescriptor:

<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>

Here’s a sample metadata XML. Note that some values were removed for brevity.

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="...">
  <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      ....
    </md:KeyDescriptor>
    <!--
        In this example, all elements have a namespace of `md`. This is why the NameIDFormat has a prefix of `md:`.
        If the elements in your XML don't have the prefix, then you may skip that.
    -->
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="..."/>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="..."/>
  </md:IDPSSODescriptor>
</md:EntityDescriptor>

An SSO binding was not found in the XML. Contact your SSO provider.

This error occurs when the metadata XML you are trying to save does not have any <SingleSignOnService> elements under the <IDPSSODescriptor>. The <SingleSignOnService> is used by the Ostorlab to determine the authentication mechanism supported by the IDP. Learn more about SAML 2.0 Bindings from Wikipedia. You must contact your IdP support or your system admin to fix the metadata XML.

Here’s an example of an SSO binding for HTTP-POST:

<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="..."/>

Note: The Location attribute is unique to each tenant in your IDP.