Skip to main content

How to set up SAML Single-SignOn (SSO)

Documentation for Attest Admins to set up SSO

Updated today

This document provides instructions for setting up SAML-based Single Sign-On (SSO) for your Attest Organisation. It has been created to explain how SAML SSO allows your users to log into Attest using their existing corporate credentials

managed by your Identity Provider (IdP), such as Okta or Microsoft Entra ID.

Note: Only an Organisation Admin (Admin) can configure SAML SSO. If you have no Admins, please contact your Attest Account team to set this up.

Glossary of Terms

Here are some terms we may refer to in this setup guide:

  • SAML (Security Assertion Markup Language): An XML-based open standard for exchanging authentication and authorization data between an Identity Provider and a Service Provider. It's the technology that enables SSO.

  • SSO (Single Sign-On): An authentication process that allows a user to access multiple applications with one set of login credentials.

  • Identity Provider (IdP): The system that authenticates users and issues SAML assertions. In this context, your IdP will be Okta, Microsoft Entra ID, or another compatible system. The IdP "knows" who the user is.

  • Service Provider (SP): The application or service that relies on the IdP to authenticate users. In this case, Attest is the Service Provider. The SP "trusts" the IdP's assertion of identity.

  • SP-Initiated SSO: The user attempts to access Attest directly, is redirected to the IdP for authentication, and then redirected back to Attest upon successful login.

  • SAML Assertion: An XML document issued by the IdP to the SP that contains information about the authenticated user, including their identity and attributes.

  • SAML Metadata: An XML document that describes the configuration details of a SAML entity (either an IdP or an SP). It includes information such as endpoints, supported bindings, and public keys (certificates) used for signing and encryption. Exchanging metadata simplifies the configuration process.

  • Audience URI (also known as Audience Restriction or SP Entity ID): A unique identifier for the Service Provider (Attest) within the SAML configuration. It tells the IdP who the intended recipient of the SAML assertion is.

  • Single Sign-On URL (also known as ACS URL, Reply URL, or Assertion Consumer Service URL): The URL on the Service Provider (Attest) where the IdP sends the SAML assertion after successful authentication.

Attest SAML SSO Setup Steps

This guide outlines the necessary steps to configure SAML SSO for your Attest organisation. We confidently support Okta and Microsoft Entra ID as Identity Providers. If you use other IdPs, please do get in touch with us to discuss further.

Prerequisites:

  • You must be an Admin on Attest.

  • You have administrative privileges to configure enterprise applications within your chosen Identity Provider (Okta or Microsoft Entra ID).

  • Please note that Attest SAML SSO supports only one Identity Provider (IdP) per subscription.

Step 1: Obtain Attest (Service Provider) Configuration Details

As an Admin, you will need to retrieve specific information from your Attest account to configure your IdP.

1. Log in to your Attest account

2. Navigate to the SSO configuration section, which is on the Profile & Settings page. This is only visible to Admins:

3. Click ‘Setup single sign-on (SSO)’ and it will take you to the configuration page:

4. On this page, you will find the following details that you'll need to enter into your IdP:

  • Attest URL (Service Provider URL): This is the base URL for your Attest instance.

  • Audience URI (Service Provider Entity ID): This is the unique identifier for Attest that your IdP will use.

Action Required: Copy these values. You will paste them into your Okta or Entra ID application configuration.

Step 2: Configure Attest as an Application in Your Identity Provider

This step involves setting up Attest as an enterprise application within your chosen Identity Provider. The exact steps may vary slightly, but the core information required is the same.

Important: We will not have a primary test environment for your initial setup. You will be configuring directly within your production IdP environment.

Open each collapsible section depending on your IdP provider:

For Okta:

  1. Log in to your Okta administrator console.

  2. Navigate to Applications > Applications.

  3. Click Create App Integration.

  4. Select SAML 2.0 as the Sign-on method and click Next.

  5. General Settings:

    • App name: Attest (or a descriptive name of your choice).

    • (Optional) App logo and App visibility.

    • Click Next.

  6. Configure SAML:

    • Single sign-on URL: This is the URL provided by Attest in Step 1.

    • Audience URI (SP Entity ID): This is the Audience URI provided by Attest in Step 1.

    • Name ID format: Typically "EmailAddress".

    • Application username: Typically "Email".

    • Attribute Statements (it will say 'Optional' but these are Required):

      • Add Required attributes

        http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

        ,

        http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

        , and

        http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

        to ensure user information is passed correctly. The exact attribute names may vary based on your IdP's user profiles.

      • For example:

        • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname -> user.firstName

        • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname -> user.lastName

        • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress -> user.email

        • Click Next

  7. Feedback: Select the appropriate options and click Finish.

  8. Assignments: Assign relevant users or groups to the Attest application in Okta to grant them access.

For Microsoft Entra ID:

  1. Log in to the Entra portal

  2. Navigate to Microsoft Entra ID > Enterprise applications.

  3. Click New application.

  4. Click Create your own application.

    • What's the name of your app? Attest (or a descriptive name of your choice).

    • What are you doing with your application? Select "Integrate any other application you don't find in the gallery (Non-gallery)".

    • Click Create.

  5. From the left-hand menu, under Manage, select Single sign-on.

  6. Select SAML as the single sign-on method.

  7. Basic SAML Configuration: Click the Edit icon (pencil).

    • Identifier (Entity ID): Click "Add identifier" and enter the Audience URI provided by Attest in Step 1.

    • Reply URL (Assertion Consumer Service URL): Click "Add reply URL" and enter the Single Sign-On URL provided by Attest in Step 1.

    • Sign on URL (Optional): This is typically the Attest URL (from Step 1) if you want to support SP-initiated login.

    • Click Save.

  8. Attributes & Claims (Required): Click the Edit icon.

    • Modify the https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress field to user.userprincipalname.

    • Leave the other values as defaults (surname is user.surname, givenname is user.givenname).

    • Click Save.

  9. Users and groups: Assign relevant users or groups to the Attest application in Entra ID to grant them access.

Step 3: Provide Identity Provider (IdP) Details to Attest

Once you have configured Attest as an application in your IdP, you will need to provide Attest with the necessary metadata from your IdP. This metadata allows Attest (the Service Provider) to trust and communicate with your IdP.

You will need to retrieve one of the following from your IdP configuration:

  • IdP Metadata URL: This is a URL that points to an XML file containing all the necessary IdP configuration details. This is the preferred method as it allows for automatic updates of certificate rollovers etc.

  • IdP Metadata XML Certificate: This is the actual XML file content that you can download from your IdP. Note that if you choose this option, you will be responsible for configuring the Attest platform with an updated XML file when you updated your certificate, otherwise SSO logins will stop working.

For Okta:

  1. From the Sign On tab of your Attest application in Okta, find the "SAML 2.0 is configured" section.

  2. Click View SAML Setup Instructions.

  3. On this page, locate and copy either:

    • Identity Provider metadata URL: This is the preferred option.

    • Or, the XML content: Scroll to the bottom and copy the entire XML content starting with <?xml version="1.0"... and save it to a file with an .xml extension.

For Microsoft Entra ID:

  1. From the Single sign-on blade of your Attest enterprise application in Entra ID, scroll down to SAML Certificates.

  2. Locate either:

    • App Federation Metadata Url: Copy this URL. This is the preferred option.

    • Or, Federation Metadata XML: Click the Download link next to "Federation Metadata XML" to download the file.

Provide either the IdP Metadata URL or upload the IdP Metadata XML Certificate file within the Attest form.

Step 4: Click ‘Activate single sign on’

This step needs to be done before the app will work within your IdP login flow.

Once all the information in the form is complete, and you’ve set up Attest in your IdP, select ‘Activate single sign on’.

You’ll be asked to confirm the activation.

Once activated, any Users in your organisation will remain logged in until their current password enabled session expires, or they logout. They will need to login via SSO at next login.

Note: it will be your (the organisation’s) responsibility to tell your company/team that they will now need to login via SSO at next login. They will no longer be able to login via email and password if they are a User. Only Admins will be able to continue to login via password as well as SSO.

Testing Your SAML SSO Configuration

After Attest confirms the SSO setup is complete, it's crucial to test the integration.

  1. Log out of your Attest account.

  2. SP-Initiated Test:

    • Go to the Attest login page https://dashboard.askattest.com/login/sso-saml.

    • You should be redirected to your IdP's login page for authentication once you have entered your work email address.

    • After successful authentication, you should be redirected back to Attest and logged in.

If you encounter any issues during testing, please make sure your set up is correct, and if no errors are found please capture screenshots of any error messages and contact your Attest Account team for assistance.

FAQs

Who can set up the SAML profile for my organisation?

Only Admins are able to enable SAML for your organisation. The first Admin will always need to be set up by Attest. You will then have the ability to invite and set permissions for others in your organisation

Which IdPs do you support?

We fully support Microsoft Entra ID and Okta. Other IdPs may also work but we haven’t tested against them and it will be up to your Org Admin/IT department to decide whether they want to enable for an unsupported IdP.

How do others in my organisation get invited to Attest if it is SAML SSO enabled?

As an Admin, you’ll be able to invite others to your organisation.

When the invites are sent out, they will get a link to their email that will direct them to their IdP, requiring them to authenticate with usual company login details, before being redirected to Attest.

Users within SAML enabled organisations will then always be required to login via the SSO at the login page.

A member of my team has left my organisation, what happens to their SAML SSO login?

It will be your (the organisation’s) responsibility to remove any team members from your IdP user group. Within Attest, the Admin will be able to delete the user from the ‘People’ page and choose where to assign their surveys. This action will not happen automatically.

Can I still login via email and password if my organisation is now SAML enabled?

If you are a User you will not be able to login via email and password once SAML is enabled. As an Admin however, you will be able to login via email and password as a back up option. Use the email and password option on the Login page to use your password credentials.

I am an Admin but I don’t have a password/haven’t created a password for my account

As an Admin you can login to Attest via SSO or via email and password (see above). If you do not have a password you can select ‘Forgot password’ from the Login screen which will enable you to set a password up if you are an Admin:

Can I set up contractors if I am a SAML enabled organisation?

Contractors can only be set up if they have an email address authenticated by your IdP. This is to say, if permitted you can set them up on your IdP with their own, domain accepted email address to access Attest. This means contractors not accepted by your IdP will not be able to access Attest if your organisation is SAML enabled.

What happens if I need to disable SAML SSO once it’s activated?

As an Admin, you will be able to disable SAML SSO once activated via ‘Profile & Settings’ page. Scroll down to SAML Single sign-on (SSO) and click ‘Edit settings’.

You will then see an option to ‘Turn off single sign-on’ - once you click this you will be asked to confirm this action. Any Users/Admins active on Attest at the time won’t be immediately removed from the app, but they will be required to enter email and password credentials at next login.

If the user does not have password credentials then they should follow the ‘Forgot password’ flow at the Login screen.

Do you have a guide for Users to explain how to login via SSO?

Yes! You can share the guide with your team here

Did this answer your question?