SAML Integration for Service Providers – Support Center

This article assumes the reader has a decent understanding of the SAML 2.0 open standards.

Links to the standards and other resources can be found here:
Additional SAML 2.0 Resources

Security Requirements

The following requirements are consistent with the SAML specification and ensure full security during federated data exchange. All interactions must conform to the SAML specifications.

All network traffic must go over TLS/SSL.
SAML 2.0 assertions must be signed.
SAML 2.0 assertions must be encrypted in order to not leave Personally Identifiable Information (PII) data in plaintext on the browser.
The Identity Provider and Service Provider exchange public certificates to support digital signing and encryption of the SAML assertions and attributes.

System Requirements

System time of the partner SAML server is accurate (updated through time protocol). This will ensure correct SAML semantics for timestamp validation.
Security algorithms for encryption and digital signature. Reference: Supported Algorithms

Supported Features & Limitations

Our Identity Providers support both IdP and SP initiated login flows.
Our Identity Providers support AuthnRequests, for SP initiated flows, via both HTTP Redirect and HTTP POST bindings.
SAML Responses are only sent to the Service provider via HTTP POST binding. MANTL does not implement the HTTP Artifact Binding.
MANTL supports multiple SAML Service Providers per tenant.
By default, our SAML Responses use a message signing order of sign-then-encrypt.

Required Data from the Service Provider

Before MANTL can operate as an Identity Provider, a few pieces of information will need to be sent to your Implementations or CSM Manager about your Service Provider being configured.

A URL to or the raw XML of the Entity Descriptor metadata for your service provider.

How to choose a good Entity ID.
Because we require encrypted assertions, the SPSSODescriptor must contain both signing and encryption certificates. They can be the same certificate.

Example SP Metadata

<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:assertion="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://sp.example.org">
    <SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>MIICUDCCAbmgAwIBAgIBADANBgkqhkiG9w0BAQsFADBFMQswCQYDVQQGEwJ1czERMA8GA1UECAwITmV3IFlvcmsxDTALBgNVBAoMBHRlc3QxFDASBgNVBAMMC2V4YW1wbGUuY29tMB4XDTIyMTIxNDE2MjcyNFoXDTMyMTIxMzE2MjcyNFowRTELMAkGA1UEBhMCdXMxETAPBgNVBAgMCE5ldyBZb3JrMQ0wCwYDVQQKDAR0ZXN0MRQwEgYDVQQDDAtleGFtcGxlLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAvaqmRg2Fub+DuhtKt9HJrLQNdYWyDOpErU93SgZeIkcyqVdII4BaByIh1yuG6gaUzQE6fR1sEEvHgAY77IBswF2AYa9n77FXQb/C10VSfoL5/rKpK2mVKxeRS4WQgpXyCKyNEF/PzO8yHuC0KJ0VuCYW5gi1Z+WtKv6UOW8dJUkCAwEAAaNQME4wHQYDVR0OBBYEFMhC0l5c20uxbKIUhhEWKdOQhZgoMB8GA1UdIwQYMBaAFMhC0l5c20uxbKIUhhEWKdOQhZgoMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvc</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>
        <KeyDescriptor use="encryption">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>MIICUDCCAbmgAwIBAgIBADANBgkqhkiG9w0BAQsFADBFMQswCQYDVQQGEwJ1czERMA8GA1UECAwITmV3IFlvcmsxDTALBgNVBAoMBHRlc3QxFDASBgNVBAMMC2V4YW1wbGUuY29tMB4XDTIyMTIxNDE2MjcyNFoXDTMyMTIxMzE2MjcyNFowRTELMAkGA1UEBhMCdXMxETAPBgNVBAgMCE5ldyBZb3JrMQ0wCwYDVQQKDAR0ZXN0MRQwEgYDVQQDDAtleGFtcGxlLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAvaqmRg2Fub+DuhtKt9HJrLQNdYWyDOpErU93SgZeIkcyqVdII4BaByIh1yuG6gaUzQE6fR1sEEvHgAY77IBswF2AYa9n77FXQb/C10VSfoL5/rKpK2mVKxeRS4WQgpXyCKyNEF/PzO8yHuC0KJ0VuCYW5gi1Z+WtKv6UOW8dJUkCAwEAAaNQME4wHQYDVR0OBBYEFMhC0l5c20uxbKIUhhEWKdOQhZgoMB8GA1UdIwQYMBaAFMhC0l5c20uxbKIUhhEWKdOQhZgoMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvc</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>
        <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
        <AssertionConsumerService index="0" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://sp.example.org/sso/saml"/>
        <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://sp.example.org/logout"/>
    </SPSSODescriptor>
</EntityDescriptor>

Service Provider Namespaces

For a given Financial Institution, MANTL supports multiple SAML Service Providers.

If, for example, a bank has a mobile app, a consumer online service, and a separate business online service. We might issue the following namespaces accordingly: consumer_mobile, consumer_online, and business_online.

Each namespace acts as a unique Identity Provider with their own URLs, entity IDs, certificates, and the ability to consume differences in configurations between the SPs.

API Endpoints

Information on the origin of the URL: Environments and URL Domains

Identity Provider Metadata
- We expose the Entity Descriptor for each IdP to be consumed as needed.
- {origin}/api/3.0/sso/outbound/saml/idp/metadata/{namespace}
- e.g.
```
https://open.bank.org/api/3.0/sso/outbound/saml/idp/metadata/consumer_online
```
Single Sign-On Service
- {origin}/api/3.0/sso/outbound/saml/login/{namespace}
- The endpoint on the Identity Provider that receives authentication requests.
- This service supports both HTTP Redirect and HTTP POST bindings.
- This same endpoint is used whether the user agent is experiencing an IdP or SP initiated flow.

Authorization Flow

A customer successfully completes their application for a new account in MANTL and opts to be automatically enrolled in online mobile banking.
SP-Initiated flows continue to step #3 while IdP-Initiated flows redirect the browser to an internal MANTL API and skip to step #7.
MANTL redirects the user to a URL that triggers a SP-Initiated SAML SSO flow.
The Service Provider creates a SAMLRequest and optionally a RelayState to track the user session details.
The Service Provider redirects the user to the MANTL Single Sign-On Service URL with the SAMLRequest and RelayState parameters.
MANTL will perform the following steps to verify the SP's request:
1. Verify the SP ID in the URL.
2. Verify the SP SAMLRequest against the configuration for the SP.
3. Verify the SP signature on the SAMLRequest.
4. Ensure the request has not expired.
Gather SAML assertion attributes for the user of the current session.
Generate a signed SAMLResponse using the dedicated MANTL private key associated to the SP.
Encrypt the assertion using the SP's public certificate.
MANTL will render an auto submitting HTML form which will POST the SAMLResponse and any RelayState back to the SP.
The SP will parse, decrypt, verify the SAMLResponse, and extract the SAML assertion attributes.
The SP will use the SAML assertion to query the core for user and account data.
The SP is then responsible for determining if the user is existing or needs to be enrolled and presenting the user with the correct authorization interface.

SAML Assertion Attributes

Field	Type	Description
email	string	The verified primary email address for the customers account.
given_name	string	The customers first name.
middle_name	?string	The customers middle name.
family_name	string	The customers last name.
phone_number	?string	The primary contact phone number of the customer. Only digits.
core_id	string	The customers core identifier associated with new accounts.
member_id	?string	Only provided for credit unions, this value may be provided instead of or in addition to core_id.
tax_id	string	The customers tax identifier used to open accounts. This will generally be a Social Security Number (SSN).
org_core_id	?string	The organizations core identifier associated with new accounts. Only provided if the user is navigating to enrollment from a booked, business application/account.
org_tax_id	?string	The tax identifier of the organization. Only provided if the user is navigating to enrollment from a booked, business application/account. This will generally be a Employer Identification Number (EIN).
funding_account_number	?string	The account number that funded the recently opened account. Usually an outside institution.
funding_routing_number	?string	The routing number tied to the account that funded the recently opened account. Only provided when funding_account_number is provided.
funding_account_type	?string	The type tied to the account that funded the recently opened account. Only provided when funding_account_number is provided.
account_number	?string	The number of the account.

Example Decrypted SAML Assertion

<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="id792719500825027239111231" IssueInstant="2022-09-22T22:06:01.922Z" Version="2.0">
    <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://www.mantl.com</saml2:Issuer>
    <saml2:Subject>
        <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">john.doe@mantl.com</saml2:NameID>
        <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml2:SubjectConfirmationData NotOnOrAfter="2022-09-22T22:11:02.094Z" Recipient="https://open.bank.com"/>
        </saml2:SubjectConfirmation>
    </saml2:Subject>
    <saml2:Conditions NotBefore="2022-09-22T22:01:02.094Z" NotOnOrAfter="2022-09-22T22:11:02.094Z">
        <saml2:AudienceRestriction>
            <saml2:Audience>
                https://open.bank.com
            </saml2:Audience>
        </saml2:AudienceRestriction>
    </saml2:Conditions>
    <saml2:AuthnStatement AuthnInstant="2022-09-22T22:06:01.922Z">
        <saml2:AuthnContext>
            <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
        </saml2:AuthnContext>
    </saml2:AuthnStatement>
    <saml2:AttributeStatement>
        <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
            <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
                john.doe@mantl.com
            </saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute Name="given_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
                John
            </saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute Name="middle_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
                M.
            </saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute Name="family_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
               Doe
             </saml2:AttributeValue>
         </saml2:Attribute>
        <saml2:Attribute Name="phone_number" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
               4065551234
             </saml2:AttributeValue>
         </saml2:Attribute>
        <saml2:Attribute Name="core_id" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
                bfc0aed9-1a9d-4697-b222-2dacf62c73fd
            </saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute Name="tax_id" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
                555555555
            </saml2:AttributeValue>
        </saml2:Attribute>
        <saml2:Attribute Name="account_number" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
          <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
              123456785
          </saml2:AttributeValue>
    </saml2:Attribute>
    </saml2:AttributeStatement>
</saml2:Assertion>

Supported Algorithms

Encryption

Digest

Signature

Canonicalization

Transform

Related articles