SAML Authentication

Learn about authenticating your users with a SAML provider. Authentication with SAML requires configuration prior to beginning the authentication flow.

ClosedPrerequisites for SAML Authentication

SAML authentication requires EMS Platform services.

EMS Web App

The minimum version of EMS Web App and EMS Platform Services for authentication through SAML 2.0 is Update 23.

To enable SAML 2.0 authentication for EMS Web App, Administrators must change the following parameter value to Yes in EMS Desktop Client:

  1. Navigate to System Administration > Settings > Parameters > Everyday User Applications tab > Authentication > Use SAML 2.0 Authentication for User Authentication Web App Only.
  2. Select Yes.

If set to No, EMS Web App uses SAML as configured through Portal Authentication methods.

EMS Mobile App

The minimum version of EMS Platform Services for SAML authentication in the EMS Mobile App is Update 9. There are breaking changes in Update 23 and customers must update SAML configuration settings.

ClosedSupported Identity Providers

  • ADFS
  • G Suite
  • Okta
  • Auth0
  • Azure AD
  • Shibboleth

Only Redirect HTTP Binding Type is supported.

ClosedUpdate SAML configuration (Versions prior to Update 35)

ClosedConfigure SAML Authentication for EMS Mobile App and EMS Web App

Prerequisite

Update the Encryption key in default.Json file.

The Encryption Key is used for encrypting and decrypting the Service Provider private key when stored in the database via the AuthKey API.

New Customers – The encryption key is provided in the default.json file.

Existing Customers – Generate the encryption key and add it to the default.json file before using the AuthKey API. To generate a 256-bit key that is Base64 encoded, run the following command in a terminal, openssl rand -Base64 32. The encryption key must be 256-bit and Base64 encoded. Restart EMS Platform Services after updating default.Json file.

  1. Login to EMS Platform Services.
  2. Navigate to the Integrations tab.
  3. Select EMS Mobile / EMS Web Application.
  4. Set Everyday User Authentication Method to SAML and save changes.
  5. Select SAML from the left navigation bar.
  6. Configure SAML authentication settings.

SAML settings are global and apply to all integrations that use SAML authentication.

ClosedIdentify Your Provider in Configuration

You are responsible for your chosen IdP configuration, with information relevant to EMS Platform Services acting as a Service Provider for SAML authentication. To configure your IdP, You might need the following EMS Platform Services-related settings.

The following fields are required to complete SAML authentication configuration: 

Field

Description

Request and Response Properties

Form Post Field Name

(Optional, default is SamlResponse). Attribute in which assertions are sent, within encoded <samlp:Response> document.

User Identity Field

Choice of assertion element containing user identity (Name ID or Attribute). If set to Attribute, then set the Identity Attribute Name to the expected assertion attribute name to use for user identity.

Identity Attribute Name

Assertion attribute name containing user identity. Attribute names can be identity provider-specific (for example, 'uid', 'mail'). This field gets ignored when User Identity Field is set to Name ID.

To find the correct value for this field, we recommend you do a SAML auth and use the example SAML response object . You can do this using a SAML tracer on your browser. Check the attributes/claims received by the response object. Find the attribute that has the correct mapped value. The configuration string to plug into the Identity Attribute Name is the Name attribute not the FriendlyName attribute. The Name looks like an ugly URL, URN, or OID identifier (series of numbers and periods), depending on your IDP.

Identity Provider Issuer

Used to verify expected issuer of assertions, included in SAMLResponse as <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion" >http://adfs.mycompany.net/adfs/services/trust</Issuer>.

Service Provider Issuer

Included by EMS Platform Services in AuthnRequest requests sent to Identify Provider. This is included in the SAMLRequest as <saml:Issuer>https://mycompany.com/EmsPlatform</saml:Issuer>

EMS Platform Services autogenerates the values for the Service Provider Issuer and the Service Provider Base URL for IdP Callback.

HTTP Binding Type

 

Specifies which SAML binding (HTTP Post or HTTP Redirect) EMS Platform Services uses to transmit SAML protocol messages. Currently only Redirect is supported.

URLs

Identity Provider URL for Service Provider Redirect

This URL, (for example, https://idp.example.org/SAML2/SSO/Redirect), includes the authentication request details provided by EMS Platform Services and contains opaque data that it includes in the request. This enables the Identify Provider to include it as Relay State on the SAMLResponse.

If you have the identity provider metadata.xml file, you can upload it through the EMS Platform Services endpoint https://company.platform/api/v1/authentication/saml/metadata/idp. The identity provider certificate will be uploaded for you and Identity Provider Issuer. The Identity Provider URL for Service Provider Redirect fields will be populated for you.

Service Provider Base URL for IdP Callback

Set this URL to the base URL of the EMS Platform Services installation (for example, https://mycompany.com/EmsPlatform). EMS Platform Services will autogenerate the values for the Service Provider Issuer and the Service Provider Base URL for IdP Callback.

Certificate Paths

SAML Certificates are now Auth Keys. These fields are not editable.

Path to Identity Provider Public Certificate

Uploaded through Auth Keys.

Path to Service Provider Public Certificate

Optional. Uploaded through Auth Keys.

Path to Service Provider Private Certificate

Optional. Uploaded through Auth Keys.

ClosedSAML Configuration page after Update 35

The SAML Configuration page is divided into four panes: SP Metadata URL, Import Metadata, Service Provider Information, and Identity Provider Information. This enhancement gives the EMS Platform UI the ability to import Identity Provider metadata.

The Certificate Paths pane has been removed. That information is now found on the Auth Key page.

SP Metadata URL

This is populated by EMS Platform Services. If it isn't already populated it will be populated after you save the edits to the SAML Configuration page.

Import Metadata

You can import the Identity Provider from URL or file.

To import the Identity Provider metadata from URL:

  1. Enter the URL in From URL.
  2. Click Save Changes.

To import the Identity Provider metadata from file:

  1. To choose the import file, click Choose File.
  2. Click Save Changes.

You can use the SAML Metadata file to update the following fields:

  • Identity Provider Issuer
  • Identity Provider URL for Service Provider Redirect
  • Identity Provider URL for Service Provider POST
  • Sign Authn Requests Checkbox
  • Delete/Re-creates all IDP Certificate Records

Service Provider Information

This pane includes:

  • Service Provider Issuer – Auto generated by EMS Platform Services. Provided by EMS Platform Services in Authn Request requests that are sent to Identity Provider.
  • Service Provider Base URL for IdP Callback – Base URL of the EMS Platform Services installation (for example, https://mycompany.com/EmsPlatform). EMS Platform Services will auto generate this value.

  • HTTP Binding Type – Type of SAML binding. This is used to transmit SAML protocol messages. Not editable.

  • Sign Authn Requests – Check box to opt for Sign Authn requests.

  • Form Post Field Name – Attribute in which assertions are sent, with encoded <samlp:Response> document.

Identity Provider Information

This pane includes the following fields. All field values get filled in by the import:

  • User Identity Field – Field with choices of Name ID and Attribute. The choice depends on which assertion element contains the user identity. If you choose Attribute, then you must set the Identity Attribute Name to the expected assertion attribute name to be used.

  • Identity Attribute Name – Assertion attribute name containing user identity. Attribute names can be identity provider-specific (for example, 'uid', 'mail'). This field is ignored when User Identity Field is set to Name ID, but should correlate to the external reference or network ID of the Everyday User if used. This is often an OID number or URL, but varies from provider to provider

  • Identity Provider Issuer – User to specify expected issuer of assertions.

  • Identity Provider URL for Service Provider Redirect – Includes the authentication request details provided by EMS Platform Services and contains opaque data that it includes in the request. This enables the Identify Provider to include it as Relay State on the SAMLResponse.

  • Identity Provider URL for Service Provider POST – Destination users will reach when EMS initiates SAML authentication with the IDP using HTTP POST Binding

ClosedHow EMS Platform Services Supports SAML

No Two-Factor Authentication (2FA) support is provided with SAML authentication. 2FA is the responsibility of the Identity Provider (3rd-Party or Customer owned) and not the EMS Platform Services. Token expiration is configured and managed the same for SAML as for other authorization types, thus overriding any SAML Assertion Conditions that specify the assertion expiration time stamp.

Refer to Customize Your Mobile App Configuration Using config.json for details on building a configuration file for EMS Mobile App.

After creating your configuration file, proceed with one of the sections below, depending on whether you intend to host the file or preconfigure the application and redistribute it.

ClosedUsing Hosted Configuration (Public Deployment)

Host your configuration file from an applicable web server. Distribute the URL to your end users.

Important!

We don't recommend making this configuration file publicly available, since it will likely have URLs and/or other information in it that you do not want made available. Instead, host the file in a way such that it's only available internally to your organization. Users should only have to perform this import one time per installation of the application.

ClosedPre-Configure EMS Mobile App (Private Deployment)

If you want to preconfigure EMS Mobile App, refer to Configure and Re-Sign the EMS Mobile App.

SAML does not support the auto-creation of users or assignment of Process Templates to Everyday Users. Submit an enhancement request if interested.