Skip to main content

SAML Integration for Identity Providers

  • Updated

    Bringing authenticated customers from an Online/Mobile Banking (OMB) platform into the MANTL Online Account Opening System using SAML to securely identity the user.

     

    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.
    • Implementation of RSA v1.5 for the key transport encryption algorithm is not supported due to security risks associated with the algorithm.
      • Instead of RSA 1.5 (http://www.w3.org/2001/04/xmlenc#rsa-1_5) use RSA-OAEP (http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p).

    Supported Features & Limitations

    • MANTL's Assertion Consumer Service does not implement the HTTP Artifact Binding.
    • Our Service Providers support both Idp and SP initiated login flows.
    • MANTL supports multiple SAML Identity Providers per tenant.

    Required Data from the Identity Provider

    Before MANTL can operate as a Service Provider and receive data at the Assertion Consumer Service endpoint, a few pieces of information will need to be sent to your Implementations or CSM Manager.

    • A URL to or the raw XML of the Entity Descriptor metadata for your provider.
      • How to choose a good Entity ID.

      • Example IdP Metadata

        <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://idp.example.org">
    <md:IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>MIICqDCCAhGgAwIBAgIBADANBgkqhkiG9w0BAQ0FADBxMQswCQYDVQQGEwJ1czERMA8GA1UECAwITmV3IFlvcmsxEDAOBgNVBAoMB0V4YW1wbGUxGDAWBgNVBAMMD2lkcC5leGFtcGxlLm9yZzERMA8GA1UEBwwITmV3IFlvcmsxEDAOBgNVBAsMB2V4YW1wbGUwHhcNMjMwMTE5MjAwNjU4WhcNMzMwMTE2MjAwNjU4WjBxMQswCQYDVQQGEwJ1czERMA8GA1UECAwITmV3IFlvcmsxEDAOBgNVBAoMB0V4YW1wbGUxGDAWBgNVBAMMD2lkcC5leGFtcGxlLm9yZzERMA8GA1UEBwwITmV3IFlvcmsxEDAOBgNVBAsMB2V4YW1wbGUwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMFSwE5ahb8yPV+Ozm1pTe6h8kJ8L+X/QjfPOFtbJq4w08KcBLHm9Fsb1iAas2bWqW9I7TfZLkqOTmmXnKqSwoYPKeuPr2IZSkc0PC/YJAv1bZeDKebB3lQcB0prqP828jf4bYa2lTtB6gcGi9S2+6blMMy78gpVjtJomVRubKtDAgMBAAGjUDBOMB0GA1UdDgQWBBSl75RBIlf9h2PvwRgLyL6XPef42DAfBgNVHSMEGDAWgBSl75RBIlf9h2PvwRgLyL6XPef42DAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBDQUAA4GBACEFQj3+nNwVSM/wFw5E+cUYr4MB8/OswoDHdAeZsGfP7jgN7N8Yw0dC/vrwcmdERSCPLI8XtBJ4TVVDhjjJ4MoGKXiASW5zuDz1cIep+tRZERjuftmh9OU5QQYD133D/1rMzjrwU6Vi6UkmLwiM+r0WJ8ZRPzrQvlZHBlgtFV5+</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.example.org/sso/saml"/>
        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.example.org/sso/saml"/>
        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.example.org/logout"/>
    </md:IDPSSODescriptor>
</md:EntityDescriptor>
    • Message Signing Order.
      • Does your service sign-then-encrypt or encrypt-then-sign the SAMLResponse before encoding it?
    • Assertion Attribute Name(s).
      • We generally only consume the unique identifier of the user from the Financial Institution's core. Sometimes their SSN or membership ID. In the decrypted assertion, what is the attribute name or names you will be send these values to us as? 

    Identity Provider Namespaces

    For a given Financial Institution, MANTL supports multiple SAML IdPs.

    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 Service Provider with their own URLs, entity IDs, certificates, and the ability to consume differences in configurations between the IdPs.

    API Endpoints

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

    • Service Provider Metadata
      • We expose the Entity Descriptor for each SP to be consumed as needed.
      • {origin}/api/3.0/sso/inbound/saml/sp/metadata/{namespace}
      • e.g. 
        https://open.bank.org/api/3.0/sso/inbound/saml/sp/metadata/consumer_online
    • Initiate Login Redirect
      • {origin}/api/3.0/sso/inbound/saml/initiate/{namespace}
      • This endpoint is only used to trigger an SP-initiated login flow.
      • Directing the user's browser to this endpoint will cause the browser to redirect to the IdP's HTTP Redirect Binding SingleSignOnService with a signed AuthNRequest.
    • Assertion Consumer Service
      • {origin}/api/3.0/sso/inbound/saml/login/{namespace}
      • This service only supports HTTP POST Binding.
      • This same endpoint is used whether the user agent is experiencing an IdP or SP initiated flow.

    Product Specific Interactions

    The default behavior of a successful SAML login will land the user on the MANTL product selection page, which has a curated list of product offerings for the given Financial Institution. However, a common use case is to have the call-to-action in the OMB be product specific. In this case, the user will land in an already open application for the given product type.

    To facilitate this, the OMB needs to include a Product ID as part of the SAML flow. Product IDs themselves will be provided by your CSM manager. They're slugs that can look like the following: personalSavings, 12monthCD>250k, etc.

    The product ID can be provided as the query parameter product_id to either the Initiate Login Redirect or Assertion Consumer Service endpoints. Or as part of the URL encoded body to the Assertion Consumer Service endpoint with the key ProductId.

     

    Customer Category and Product Type Filtering

    Identity Providers may also land a user on the product selection page filtered by customer category (e.g. personal, business, or minor) or product type (e.g. savings, checking, certificate, etc.) by providing the query parameters customer_category and/or product_type to either the Initiate Login Redirect or Assertion Consumer Service endpoints. Or as part of the URL encoded body to the Assertion Consumer Service endpoint with the keys CustomerCategory and/or ProductType.

    The allowed values and combinations depend on the configured products of the Financial Institution, however, the values will be the same the those shown on the MANTL landing page when browsing products.

     

    Marketing Parameters

    Any of the marketing parameters supported by the MANTL product selection page (promo code, UTM parameters, etc.) can be included as query parameters to either the Initiate Login Redirect or Assertion Consumer Service endpoints.

    Related articles