Configure Fusion for SAML

Table of Contents

Add a Security Realm
Configure SAML identity provider
Example SAML Realm configuration
References

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).

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.

Add a Security Realm

In the Fusion workspace, navigate to System > Access Control.
Click Security Realms.
Click Add Security Realm.
Specify info for the new realm:
- Enter a Name. The name must be unique and should be descriptive yet short.
- Select saml from the Type pulldown menu.
  
  When you select a type, Fusion displays additional configuration options.
- The default value for Enabled is true. This setting controls whether or not Fusion allows user logins for this security realm.
- The default value for Ephemeral Users is false. When disabled, this setting prevents ephemeral users from being created in ZooKeeper during login. If enabled, this property negates Auto Create Users.
- The default value for Auto Create Users is true. If enabled, a user account is created automatically upon initial authentication. If disabled, then a Fusion user with admin permissions must create Fusion users.
Under SAML Realm, configure the following information:
- Enter the Identity Provider URL. This URL is used by the SAML authority for single sign-on. For example: https://www.my-idp.com/<my-app-path>/sso/saml
  
  The URL format may differ depending on the SAML Identity Provider.
- Enter the URL of the IdP Issuer. For example: http://www.my-idp.com/exk686w2xi5KTuSXz0h7.
  - IdP Issuer must match <saml:Issuer> in the SAML payload.
- Optionally, provide the App Issuer. This field is required if there is an audienceRestriction in the SAML assertion and must match <saml:Audience> in the SAML payload.
- In the Certificate Fingerprint, paste the contents of the SAML authority certificate, without the certificate header and footer.
- Optional: Enter the User ID Attribute. 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.
- Optional: Provide a Post Login Redirect URL. If not set, the Fusion URL is used.
- Optional: Provide a Logout URL.
Optional: Under Groups Mapping, specify the Group Name Attribute and add group mappings.
Click Save.

Configure SAML identity provider

To finish setup, register Fusion with your SAML identity provider. The amount of information required to register varies depending on the SAML authority.

All systems require the Fusion URL to redirect to upon successful login. This includes the protocol, server, and port for the Fusion application, and path api/saml, such as 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, such as https://www.my-fusion-app.

Example SAML Realm configuration

The Fusion endpoint api/realm-configs 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"
}