Configuring Fusion for SAML

SAML 2.0 is a standard for exchanging authentication and authorization data between security domains. The SAML protocol allows web-browser single sign-on (SSO) through a sequence of messages sent to and from the browser, which is the intermediary between Fusion and the SAML authority acting as the Identity Provider (IdP).

Fusion has been tested with the following IdPs (but any IdP should work):

  • ADFS

  • Okta

  • OneLogin

  • OpenAM

  • Shibboleth

To configure Fusion to use SAML 2.0 for user authentication and authorization you must create a SAML security realm. In addition to configuring the Fusion security realm, you must configure the SAML identity provider to recognize the Fusion application.

Once Fusion is configured for a SAML realm, this realm is added to the list of available realms on the initial Fusion sign-on panel. When the SAML realm is chosen from the list of available realms, the browser then redirects to the IdP which handles user authentication. Upon successful authentication, the IdP sends a response back to the browser which contains authentication and authorization information as well as the URL of the Fusion application. The browser redirects back to the Fusion URL, passing along the SAML message with the user authentication and authorization information. Fusion then issues as session cookie which is used for subsequent user access.

Fusion Configuration for a SAML Realm

You must get the following information about the SAML Identity Provider either from your sys admin or from the IdP directly:

  • Identity Provider URL - the URL used by the SAML authority for single sign-on. Usually a URL which ends in "saml/sso", e.g. "https://www.my-idp.com/<my-app-path>/sso/saml"

  • Issuer - SAML Issuer Id. A unique ID for that authority, e.g. "http://www.my-idp.com/exk686w2xi5KTuSXz0h7".

  • Certificate Fingerprint - the contents of the SAML authority certificate, without the certificate header and footer. You must get this certificate from the SAML Identity Provider. The certificate is a text file which has a pair of header and footer lines which say "BEGIN CERTIFICATE" and "END CERTIFICATE", respectively. The fingerprint consists of the lines between the header and the footer. You can cut and paste this information into the text box on the Fusion UI.

  • User ID Attribute - an optional attribute. The Identity Provider contains the user database. By default, the Fusion username is the same as the login name known to the Identity Provider. When another field or attribute in the user record stored by the IdP should be used as the Fusion username, that attribute name is the value of the User ID Attribute.

All Fusion security realms require the following information:

  • name - must be unique, should be descriptive yet short.

  • type - value is "SAML" (one of the choices on the Fusion UI Security Realms config panel).

  • "enabled" - default vale is true. The "enabled" setting controls whether or not Fusion allows user logins for this security realm.

  • "auto-create users" - default is true. This controls whether or not a user account is created automatically upon initial authentication. If false, new user accounts can only be created by a Fusion user with admin privileges.

SAML Authority Identify Provider Configuration for Fusion

The Fusion application must be registered with the SAML Identity Provider. The amount of information varies depending on the SAML authority.

All systems will require the Fusion URL to redirect to upon successful login; this is the protocol, server, and port for the Fusion application, and path "api/saml", e.g. "https://www.my-fusion-app.com:8764/api/saml". If the Fusion application is running behind a load-balancer, then this URL is the load-balancer URL plus path "api/saml". Note that the load-balancer should be session-sticky in order for the sequence of messages that comprise the SAML protocol to run to completion successfully.

Some authorities may require additional information. In particular the SAML 2.0 "AudienceRestriction" tag may be part of the SAML message. This tag specifies the domain for which the SAML trust conditions are valid, which is usually the domain in which the Fusion app is running, e.g. "https://www.my-fusion-app".

Example SAML Realm Configuration

The Fusion endpoint "api/realms-config" returns a JSON list of all the configuration objects for all realms. After configuring a SAML realm named "saml-test" using the okta.com developer preview tool, the configuration object for this realm is:

{
 "name":"saml-test",
 "realmType":"saml",
 "enabled":true,
 "config":{
     "autoCreateUsers":true,
     "idpUrl":"https://dev-417804.oktapreview.com/app/dev417804_1/exk686w2xi5KTuSXz0h7/sso/saml",
     "issuer":"http://www.okta.com/exk686w2xi5KTuSXz0h7",
     "certificateFingerprint":"MIIDpDCCAoygAwIBAgIGAVQr4A4NMA0GCSqGSIb3DQEBBQUAMIGSMQswCQYDVQQGEwJVUzETMBEG\nA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU\nMBIGA1UECwwLU1NPUHJvdmlkZXIxEzARBgNVBAMMCmRldi00MTc4MDQxHDAaBgkqhkiG9w0BCQEW\nDWluZm9Ab2t0YS5jb20wHhcNMTYwNDE5MDAxNTI0WhcNMjYwNDE5MDAxNjI0WjCBkjELMAkGA1UE\nBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNV\nBAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRMwEQYDVQQDDApkZXYtNDE3ODA0MRwwGgYJ\nKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA\nuNz0trRFPw2d4xXoUvX2oWeZolTVeFtaTnB9SWUyjK4og0WdT7rNdBg10eTvB2ezBwXCf24UGGui\nr1kjkZjiHDqDxKtzQYWpGuzLCjh/4PxKFGDaiUNKcE1Ig5myiEBTvMvv99XtrcI75QdUGDhbMiBr\n2PR5FukWOYepzlBzqY0JSDzX9NYJBKPkz+syK4mj0I6dqtYOU+bcTvjF9sR7jiHtQ+d0Zl8rz1Ca\nyuE3mNUtFJ1IJrY/RArhH1AB6mXbV/de1CXmGhKQbqQAbx9SiKtki9n84gKEwuWdV0jIqcBLGxUQ\ngjbsaIVqed2oX+7F2fh6t0g/I8NPnOWXOTvA+wIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQCPt+DR\nliIsHO/iVnmLFPGfqrCO/gMv++xnq2wOB19YX7HhT1GIY2YZoVphrQpXH3OO0/8AZJ8ApCmq0E9x\nxUTQwQPBanVqlyLtu1Hr0c6dbAqcd5PtaEe6Ci33nayWPydhOmitvIyb/WtWtbel9HcdUkoGvkAl\ng305jnxkhwGLJm4jkzYe+eaYhd6oG3/JcHqKDGYGf7i2Z+ny0D7vxTeBQ+8PbZfsUKg0PlKyTocb\nydSmDPISsA1xOH5zlw+hzFIdKgD5vW7QZLvpIclNc2hqki/nWl/CHut0TnUuP/V3boREmhDu395n\n/u72pgNANfP7+2DTBb+CBTjGUsAxpKRF",
     "userIdAttribute":""
 },
 "roleNames":["search"],
 "id":"52e1c0d2-5e00-4c76-a3d4-57f1381bdb4f",
 "createdAt":"2016-04-19T19:49:04Z",
 "updatedAt":"2016-04-19T20:06:56Z"
}