SAML SSO Configuration

Overview

App Manager supports SAML Single Sign-On (SSO), which allows users to log in to App Manager through your organization's Identity Provider (IdP) instead of a separate App Manager password. You configure SSO for each environment with the /saml API.

This guide walks through how to set up SSO using the /saml API, outlines the required SAML response structure, and explains session behavior and troubleshooting steps.

For API-specific guidance, refer to the App Manager SSO API Documentation.

IMPORTANT: Once SSO is enabled for an environment, every user in that environment must log in through SSO. Complete and test the setup in a test environment before enabling it in production.

Before You Begin

App Manager works with IdPs whose SAML assertions meet the requirements in SSO Configuration Requirements. Because IdP interfaces vary and change often, this guide does not include IdP-specific steps. Refer to your IdP's documentation for creating a custom SAML application, and use the table below to match its fields to App Manager's values. You need:

Administrator access to your IdP, with permission to create a custom SAML application
Access to the App Manager SSO API
A test environment in App Manager
A test user whose App Manager email address matches their IdP email address

Values to Exchange

Value	Common IdP Labels	Direction
SSO URL	Login URL, Sign-on URL, SSO endpoint	IdP to App Manager (`PUT /saml`)
Entity ID	IdP Entity ID, Issuer, Identifier	IdP to App Manager (`PUT /saml`)
Certificate	Signing certificate, X.509 certificate	IdP to App Manager (`PUT /saml`)
ACS URL	Reply URL, Single sign-on URL, Assertion Consumer Service URL	App Manager (`GET /saml`) to IdP
SP Entity ID	Audience URI, Identifier (Entity ID), Audience	App Manager (`GET /saml`) to IdP

Setting Up SSO

Step 1: Create a SAML Application in Your IdP

Create a custom SAML application in your IdP, then record its SSO URL, Entity ID, and signing certificate.

Download the certificate in PEM format, which some IdPs label Base64.

Step 2: Send the IdP Values to App Manager

Send a PUT request to /saml for your test environment with the following values:

enabled: false
SSO URL: The redirect or login URL from your IdP
Entity ID: Your IdP's unique identifier
Certificates: The signing certificate in PEM format, used to validate SAML responses

NOTE: Keep enabled set to false until Step 5. Users can continue to log in with their username and password while you finish the setup. Full validation rules for these fields are available in the API documentation.

Step 3: Retrieve the App Manager Values

Send a GET request to /saml for the same environment. The response includes:

ACS URL: The Assertion Consumer Service (ACS) URL, where your IdP sends SAML responses
SP Entity ID: The Service Provider (SP) identifier your IdP uses for App Manager

Step 4: Finish Configuring Your IdP

Enter the ACS URL and SP Entity ID from Step 3 in your SAML application.
Set the Name ID format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.
Map the Name ID to the user's email address.
Sign assertions with the certificate you sent in Step 2.
Assign the users or groups that need access to App Manager.

IMPORTANT: The email address in the Name ID must match the email address the user was invited to App Manager with. Assigning a user in your IdP does not create an App Manager account. Each user must also be invited through User Administration.

Step 5: Enable and Test SSO

Send a PUT request to /saml for your test environment with enabled set to true.
Log out of App Manager, then enter the email address of your test user on the login page.
Confirm App Manager redirects to your IdP's sign-in page.
Sign in and confirm App Manager opens.

Once SSO works in the test environment, repeat these steps for your production environment.

SSO Configuration Requirements

Each App Manager environment supports one IdP. The SAML assertion must include the following elements:

Email in NameID: The user's email address. Other identifier formats are not supported.
AuthnStatement: Most IdPs include this by default. Some require you to turn it on in their configuration.
Conditions: Must include NotBefore and NotOnOrAfter, as shown below.
Issuer: Must match the Entity ID you sent with PUT /saml.

<saml:Conditions NotBefore="{ConditionsNotBefore}" NotOnOrAfter="{ConditionsNotOnOrAfter}">
  <saml:AudienceRestriction>
    <saml:Audience>{Audience}</saml:Audience>
  </saml:AudienceRestriction>
</saml:Conditions>

After Enabling SSO

Once SSO is enabled for an environment, every user in that environment must log in through SSO. App Manager chooses the login method based on the environment a user was first invited to. When a user enters their email address on the login page, App Manager applies that environment's login method.

NOTE: This matters most for Division Administrators with access to multiple environments. They log in with the method of the environment they were first invited to.

Session Duration and Timeout

App Manager expires sessions automatically and requires users to authenticate through your IdP again.

Default Behavior

If the SAML response does not include the SessionNotOnOrAfter attribute, the session expires at midnight Eastern Time (ET) at the end of the day after login. This keeps users from being logged out during an active work session.

For example, a user who logs in at 10:00 AM ET on Monday stays logged in until midnight ET at the end of Tuesday, rather than until 10:00 AM Tuesday.

Custom Behavior

To set a custom session length, include the SessionNotOnOrAfter attribute in the SAML response. App Manager uses that value, but still moves the logout to midnight ET at the end of the expiration day.

Troubleshooting and Recovery

If your SAML configuration fails and prevents users from logging in, turn SSO off to restore username and password login:

Send a PUT request to /saml with enabled set to false. If you cannot send the request, contact support@eleostech.com, and Eleos turns off SSO for the environment.
Reset your App Manager password.
Log in to App Manager.
Fix your SAML configuration, then repeat Step 5 of Setting Up SSO.

IMPORTANT: App Manager does not support designated recovery accounts. If SSO is enabled and your configuration breaks, no one in that environment can log in until SSO is turned off.

Resources

API

App Manager SSO