SAML Servers

SAML stands for Security Assertion Markup Language, and is a single sign-on protocol. It is a standard method used to exchange authentication and authorization data between parties. SAML authentication allows your institution to provide SSO capability through your SAML Identity Provider (IdP). MAPS is added to the SAML IdP server as a service provider (SP).

SAML 2.0 can simplify access to applications for your users and eliminate the need to administer unique passwords and duplicate credentials for MAPS. Using SAML authentication with MAPS provides a unified user experience across the applications at your institution.

The SAML authentication feature for MAPS allows your users to authenticate to MAPS using the credentials from your SAML Identity Provider (IdP) server, which is also known simply as the IdP. During configuration, the SAML IdP server and the MAPS server (the service provider) exchange metadata files. These metadata files allow the SAML IdP to authenticate users who are members of the groups permitted to use the MAPS services.

Once the SAML authentication feature is installed and configured, users select a Use Single Sign-On button on the login dialog for the eLauncher. Users are redirected to your institution's SSO login page where they enter their credentials. When users are authenticated by the SAML server, they are granted access as usual.

SAML Server Configuration and Set Up

Prerequisites

• Your IdP server must support the SAML 2.0 protocol.
• You must be running MAPS version 6.3 or later.
• MAPS must be configured to run HTTPS (secure HTTP).

Configure SAML Single Sign-On Options

Before you can configure SAML authentication, gather the following information for your facility:

Option	Description	Examples
IdP Metadata URL	The URL of the metadata file (from the SAML IdP)	https://example.com/idp/metadata
Issuer	Domain name of the MAPS server	internal.myservers.com

Select Single Sign-On from the configuration menu to display the list of existing SSO servers.

Select a server from the list, or select Add Server to configure a new server. When the Edit Single Sign-On Server dialog box displays, select SAML as the server type from the first drop down.

Set the connection parameters as follows:

• Name: This is the name of the SSO server in MAPS, and will be used within connection messages and in logs.
• IdP Metadata URL: The location of the SAML IdP metadata file. You should be able to display the metadata file in your browser using this URL.
• Issuer: The domain name of MAPS. This domain must be accessible from the SAML IdP server. Otherwise, you need to use the fully qualified domain so that MAPS is accessible.
• Enabled: Use this check box to enable or disable use of the SAML IdP server. While you can configure multiple SAML IdP servers, you can have only one enabled at a time. When you enable a SAML IdP server, be sure to disable the others (un-check the Enabled box).
• Notes: Use this space to record any additional information.

Generate and Upload MAPS Metadata to the SAML IdP Server

1. Select the Download Service Provider Metadata button. This prepares the download of the MAPS metadata file so that it can be used by the SAML IdP server.
2. Name the file so that you can identify that it is associated with MAPS. (Use the MAPS server host name, for example.)
3. Save the file to a location where you can access it when you are ready to upload it to your SAML IdP server.
4. Upload the metadata file to the server. Refer to the documentation for your SAML IdP server for specific instructions.

Configure Users and Groups

When a user enters their username and password on the SAML login page, the SAML IdP server will return an assertion to MAPS if the user is validated. The response that the SAML IdP server sends to MAPS includes attributes that identify each LDAP and/or MAPS group that the user belongs to (within the IdP).

MAPS parses the assertion and examines each attribute with the value of memberOf for either the FriendlyName or Name.

If you are using LDAP groups, and the assertion provides the attributes in the format of a distinguished name (DN), MAPS parses each DN to determine if any LDAP groups in MAPS have a matching DN. If the LDAP group does include a matching DN, the user is granted the roles and permissions associated with that group. When there are multiple matching groups, the permissions associated with the roles in those groups accumulate.

If you only have MAPS groups, you must match the DN to a MAPS group. MAPS examines the assertion to see if the entire DN matches the name of a MAPS group. When the DN in the assertion returned for a user matches the name of the group defined in MAPS, the user is granted the roles and permissions associated with that group. When there are multiple matching groups, the permissions associated with the roles in those groups accumulate.

There may be additional attributes included in the assertion that MAPS can use as a custom field. These are explained in Configuring Custom Fields.

For more information on configuring groups to work with SAML authentications, see Using Groups with Single Sign-On, in the help.

Note: SAML authentication is not supported for users who are members of nested LDAP groups.

Troubleshooting Tip: You can look at the debug log in MAPS while attempting to log in through SAML to verify that the response from the SAML server is in the correct format.

SAML Authentication Example

The example below shows a portion of an assertion that the SAML server returns to MAPS for an authenticated user:

<saml2:AttributeStatement>
  <saml2:Attribute FriendlyName="memberOf" Name="memberOf" 
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml2:AttributeValue>
CN=Report Writer,OU=Groups,DC=Evisions,DC=Example
    </saml2:AttributeValue>
    <saml2:AttributeValue>
      CN=Report Viewer,OU=Groups,DC=Evisions,DC=Example
    </saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

In this example, if you are using LDAP groups, the SAML response tells MAPS that the user is a member of the Report Writer LDAP group and the Report Viewer LDAP group. MAPS and associated applications grant this user the permissions defined for those two groups.

If you only using MAPS groups, the name of the MAPS group must be named CN=Report Writer,OU=Groups,DC=Evisions,DC=Example or CN=Report Viewer,OU=Groups,DC=Evisions,DC=Example.

Note: The assertion must include the value of "memberOf" for either the FriendlyName= or the Name= in the attribute statement. You may not be able to control the value for the Name statement that is sent from your server. If that is the case, edit the FriendlyName value so that it is memberOf which will allow it to be recognized by MAPS.

Note that the list of groups returned by the SAML server may include groups that are not defined in MAPS, but are used for other applications throughout the enterprise. MAPS ignores these attributes.

Configuring Custom Fields

Custom fields are used to map values from within the assertion sent from the IdP to variable values used by other applications such as Argos or proxy accounts (BANPROXY, for example).

To configure custom fields, select the Configure Custom Fields button on the Edit Single Sign-On Server dialog. This displays the Custom Fields dialog:

You can enter up to three values.

MAPS examines the assertion from the SAML server, looking for a FriendlyName or Name attribute that matches the value for one of the Custom Fields. In the following example, MAPS will be looking for FriendlyName or Name field matching the following:

• authenticationDate
• principalLdapDn
• uid

The snippet below is from an assertion returned by the SAML server. In this snippet, the second and third custom field values (uid and principalLdapDn) are used as values for the FriendlyName of an attribute.

<saml2:Attribute 
  FriendlyName="uid" Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
   <saml2:AttributeValue>
      Dex
   </saml2:AttributeValue>
</saml2:Attribute>

...

<saml2:Attribute 
  FriendlyName="principalLdapDn" Name="principalLdapDn" 
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
   <saml2:AttributeValue>
      CN=dex,CN=Users,DC=Test,DC=Local
   </saml2:AttributeValue>
</saml2:Attribute>

• The attribute value of principalLdapDn (which is CN=dex,CN=Users,DC=Test,DC=Local) will be passed as Custom Field 2
• The attribute value of uid (which is Dex) will be passed as Custom Field 3

If the assertion does not include an attribute for authenticationDate, nothing is returned, and the Custom Field value is ignored.

If there are multiple values for an attribute, then only the first one in the list is set as the value for the custom field.

How Users Log On with SAML Single Sign-on

Once the SAML server and the MAPS server are properly configured and communicating with each other, users who attempt to sign in using the eLauncher see the Use Single Sign-On button on the sign in dialog.

When users select this button, they are redirected to the institution's IdP sign in page where they enter their credentials. If the authentication is successful, the users are redirected to the eLauncher and granted access to the MAPs pages and applications that they are authorized to access.

Note that for some sensitive applications, such as IntelleCheck and MAPS Config, users may be prompted to re-enter credentials.