Security Realms - Lucidworks documentation

Fusion uses security realms to authenticate users of the Fusion UI. Each user has an assigned security realm, which the user must choose when logging in. Choosing a different realm results in an authentication failure. A security realm also provides a list of roles:

The list always includes the role(s) that are specified in the security realm.
(Optional) The security realm can reference one or more Fusion roles and/or get groups to which the user belongs from an external directory service that is the authentication provider. Fusion maps the group names to role names and adds these roles to the user’s list of roles.

Fusion does not use permissions from the LDAP to authorize UI access or API requests. It only obtains group names (optionally), which are used as role names or are mapped to role names. If an Active Directory Security Query Trimming Stage is used, then directory-service permissions are used for trimming. If a connector supports security trimming, then connector permissions are used for trimming.

Requests to the Fusion REST API must specify a security realm for per-request authentication, unless a session cookie is used (which contains information about the security realm). Fusion authorizes requested operations based on API permissions specified for the user and for the user’s role(s). Fusion considers the role(s) specified in the user definition and in the security realm. Fusion creates a list of roles when a session is created, that is, when a user logs in or when the Sessions REST API creates a session. Authorization based on permissions is at request time. You can define multiple security realms for a Fusion instance. This lets you give different sets of users different levels of access to specific Fusion collections.

The directory service that you use to return group information must be the same one that is used for authentication.

Security Realm Types

When you create a security realm, you can choose among the following security realm types:

OpenID Connect

OpenID Connect is an identity authorization layer which supplements the OAuth 2.0 protocol.

ImportantFusion’s OpenID Connect security realm has been tested with Google and Okta.

See Configure OpenID Connect Authentication.

Configure OpenID Connect Authentication

Configuration

Use the Realms API to configure this realm type:

curl -u USERNAME:PASSWORD -H 'content-type:application/json' -X POST http://<fusion-url>:6764/api/realm-configs -d @./realm-config.json

Below is a sample configuration:

  {
    "realmType": "oidc",
    "name": "{your_oidcName}",
    "enabled": true,
    "roleNames": [
        "admin"
     ],
    "config": {
      "autoCreateUsers": true,
      "groups": {
        "roleMapping": [
          [
            "role_user",
            "admin"
          ]
        ]
      },
      "code": {
        "clientSecret": "{your_clientSecret}",
        "redirectUri": "{your_redirectUri}",
        "authorizationUri": "{your_authorizationUri}",
        "tokenUri": "{your_tokenUri}"
      },
      "clientId": "{your_clientId}",
      "jwkSetUri": "{your_jwkSetUri}",
      "userIdAttribute": "email",
      "scope": [
        "openid",
        "email",
        "profile"
      ]
    }
  },

Required fields


Field	Description	Example
`name`	Name of the OIDC realm.	`oidc`.
`clientSecret`	A secret value shared between the application and the authentication server.	N/A
`redirectUri`	The URI to which the user will be redirected to after logging in.	`http://{fusion-url}:6764/admin`
`authorizationUri`	The authorization server URI.	`https://$\{yourOktaDomain}/oauth2/default/v1/authorize`
`tokenUri`	The URI to get access token from.	`https://$\{yourOktaDomain}/oauth2/default/v1/token`
`clientId`	A unique value which identifies the client.	N/A
`jwkSetUri`	The URL of the authorization server’s JSON Web Key Set (JWKS).	`https://$\{yourOktaDomain}/oauth2/default/v1/keys`

Google authentication

For authenticating with Google, use Google’s OpenID Configuration to retrieve the required values for authorizationUri, tokenUri, jwkSetUri, and issuer.

Okta authentication

OpenID Connect authentication with Okta involves mapping Okta groups to Fusion roles. The Okta group information can be retrieved from Okta’s admin view:

Navigate to API > Authorization Server
Select the server you will configure for mapping
In the Scope menu, add the authentication groups
In the Claims menu, add new claim groups with ID token and set regexp to .*, which will expose all groups

Native

Fusion has a single preconfigured security realm named native. The admin user is in the native realm. The native realm also provides a fallback mechanism in case of LDAP server or communication failure. This realm is required to bootstrap Fusion. Because all requests to Fusion require authentication and authorization, on initial startup you must access the Fusion UI to set the admin password. After Fusion has a valid admin password, it creates the admin account in the Fusion native realm. For the native realm, Fusion manages all authentication and permissions information directly. You can create Fusion user accounts and manage them using either the Fusion UI or the User API. Passwords are not stored, but are hashed using bcrypt.

SSO Trusted HTTP

The “SSO Trusted HTTP” realm type (trusted-http in the REST API) is useful in single sign-on (SSO) environments. If the SSO environment contains groups that make sense regarding partitioning Fusion functionality for Fusion users (that is, giving Fusion users different UI and API permissions based on the SSO groups), then you can configure an SSO Trusted HTTP security realm to return a list of group names, and then map the groups to Fusion roles in the security realm definition. See Configure Fusion for SSO.

Configure Fusion for SSO

The “SSO Trusted HTTP” realm type (trusted-http in the REST API) is useful in single sign-on (SSO) environments.If SSO is already set up in your environment, user identities and group information can be sent to Fusion through HTTP headers (REMOTE_USER, for example). The SSO Trusted HTTP realm type provides the configuration options for integrating this into Fusion’s authentication systems. It also supports allowing access to only a set of known client IPs, and mapping groups to Fusion roles.Use the Realms API to configure this realm type:

curl -u USERNAME:PASSWORD -H 'content-type:application/json' -X POST :3000/api/realm-configs -d @./realm-config.json

Below is a sample configuration:

{"id":"test-id",
 "enabled":true,
 "name":"sso-test",
 "realmType":"trusted-http",
 "config":{"identityKey":"REMOTE_USER",
           "groups": {"key":"GROUPS",
                      "delimiter":"|",
                       "roleMapping": [["a","admin"], ["b","foo"]]},
           "allowedIps":["127.0.0.1", "0:0:0:0:0:0:0:1", "localhost"]}}


`identityKey`	The name of an HTTP header. If this key is found in the request headers, its value is used as the identity of the client (username, for example).
`groups`	Configuration keys for auth groups: `key` The name of an HTTP header, used as the source of group names. `delimiter` The character used to split the value (defaults to comma). `roleMapping` A set of 2-tuples, used for mapping the external group values to Fusion Roles.
`allowedIps`	Allow access to only a set of known client IPs. When this property is defined and the client IP is not included in it, the realm logic return a 401. In Fusion 5.0.0+, leaving this field empty makes the realm nonoperational. To accept traffic from all destinations for development, you can use an IP such as 0.0.0.0/0. In production the concrete IP should be specified. Prior to Fusion 5.0.0, the `X-FORWARDED-FOR` header is inspected for this client IP first; the value is split on comma, and the first entry is taken. This would normally be used in cases where the client was forwarded to Fusion through one or more external proxy servers. If the `X-FORWARDED-FOR` header is not present in the request, the `REMOTE-ADDR` header value is used instead.

JWT

The JSON Web Token (JWT) realm uses an “Authorization” header in the request to authenticate the user and the data inside the JWT token for the authorization. You can configure Fusion to use a shared secret key to encrypt the JWT payload. For Fusion’s JWT realm, first create a JWT token, with the tool you use to validate users. Then create a Fusion realm. See Configure Fusion for JWT.

Kerberos

In the case where a host domain uses Kerberos for authentication and LDAP for authorization, Fusion can be configured to do the same, by configuring a realm of type “LDAP” and then specifying Kerberos as the authentication mechanism.

Kerberos support requires Fusion 5.9.5.

Fusion stores a local user record in ZooKeeper and a mapping to the Kerberos principal. SPNEGO is used for authentication via Kerberos. See how to configure Fusion for Kerberos in Configure Fusion for Kerberos in Unix and Configure Fusion for Kerberos in Windows.

Configure Fusion for Kerberos in Unix

To configure the Fusion UI service to use Kerberos for user authentication, you must create a Kerberos security realm.

Kerberos support requires Fusion 5.9.5.

Kerberos is a system that provides authenticated access for users and services on a network. Instead of sending passwords in plaintext over the network, encrypted passwords are used to generate time-sensitive tickets that are used for authentication. SPNEGO provides a mechanism for extending Kerberos to Web applications through the standard HTTP protocol.Kerberos uses symmetric-key cryptography and a trusted third party called a Key Distribution Center (KDC) to authenticate users to a suite of network services. (By users we mean both end users and client programs). The computers managed by that KDC and any secondary KDCs constitute a realm. When a user authenticates to the KDC, the KDC sends a set of credentials (a ticket) specific to that session back to the user’s machine. Kerberos-aware services use the ticket on the user’s machine for authentication instead of requiring sign-on with a password. Because tickets are used rather than passwords, this provides the convenience of Single Sign-On (SSO) in addition to security.A Kerberized process is one that has been configured so it can get tickets from a KDC and negotiate with Kerberos-aware services. When a user sends an HTTP request, Fusion tries to authenticate using the Kerberos/SPNEGO protocol. If the request was sent from a browser, Fusion does not display the initial sign-on panel; instead on login, the user sees the main Fusion collections panel.

This article focuses on configuring Fusion for Kerberos in Unix.

To Kerberize Fusion, you must:

Configure the Kerberos client on the server that the Fusion UI service will be running on so that it can talk to the KDC (section Configuring the Kerberos client below).
Configure the security realm of the Fusion UI (section Configuring Fusion Authentication for Kerberos Realm below).
Depending on the encryption used by the KDC, you may also need to install additional Java security libraries into the Fusion distribution. These are freely available from Oracle, see download and installation instructions below.

To do this, you need following information, which you can get from your sysadmin:

Kerberos realm name. In most cases, this is your domain name in upper case.
KDC name. This is usually a combination of kerberos. and your domain name. For example, kerberos.example.com
Kerberos principal name and password. A principal is a unique identity to which Kerberos can assign tickets. When the entity is a client program, this is called the Service Principal name.
A keytab file. This holds the encrypted credentials.

The usual scenario in an enterprise organization is to have a Kerberos admin create a service principal with a random key password. Then, the admin generates a keytab, which is then used for Fusion service principal authentication.The Kerberos commands needed for configuration and testing are:

kinit. Obtain and cache a ticket from the KDC (i.e., domain login)
kdestroy. Destroys credentials (i.e., domain logout)
klist. Lists cached credentials
ktutil. Create or add credentials to a keytab file

If your browser is not already configured to use the Kerberos/SPNEGO, you need to do so in order to test the Fusion configuration.

Configuring the Kerberos client

Step 1: Edit the Kerberos configuration file.

To configure your local Kerberos client so that it can talk to the Kerberized server, you must edit Kerberos configuration file named krb5.conf. On most Unix systems, this file is located at /etc/krb5.conf.This file contains Kerberos configuration information, including the locations of KDCs and admin servers for the Kerberos realms of interest, defaults for the current realm and for Kerberos applications, and mappings of hostnames onto Kerberos realms.If your organization realm name is “MYORG.ORG”, and your KDC server is named “kerberos.myorg.org”, then you edit two entries. The first entry is libdefaults. Set MYORG.ORG as the default realm:

[libdefaults]
  default_realm = MYORG.ORG

The second entry is realms. Add MYORG.ORG as a realm:

[realms]
  MYORG.ORG = {
    kdc = kerberos.myrealm.com
  }

For example, for realm LUCIDWORKS.IO, the krb5.conf file is just like the above example, except that instead of “myorg.org” we specify “lucidworks.io”.

Step 2: Authenticate to Kerberos

The command kinit is the Kerberos authentication command. To get started, you authenticate to Kerberos using the Kerberos principal name and password (which you may need to obtain from your sysadmin). For this example, the principal name is “prince”.

> kinit prince

The kinit command prompts for a password. Successful authentication is silent. Unsuccessful authentication results in an error message.The command klist shows all cached Kerberos credentials. To check that you have successfully authenticated, run this command:

> klist

Output should be in this form, but with your data:

Credentials cache: API:C980F9F5-415C-4A3E-9C67-883C7D5FFFBE
        Principal: prince@MYORG.ORG

  Issued                Expires               Principal
May  6 15:14:55 2015  May  7 01:12:47 2015  krbtgt/MYORG.ORG@MYORG.ORG

The Service Principal Keytab file

The usual scenario in an enterprise organization is to have a Kerberos admin create a service principal with a random key password. Then, the admin generates a keytab, which is then used for Fusion service principal authentication. If you are your own Kerberos admin, then you will need to create this file for yourself.

Step 3. Create a Keytab file

The command ktutil creates the service principal keytab file which holds the encrypted credentials that the Fusion UI Proxy will use for Kerberos authentication. In order to generate the keytab file, you must have a set of cached credentials, therefore, first run the kinit command (step 2).From the command line, run the command ktutil. You must enter your password twice.

> ktutil -k http-myrealm.org.keytab add -p HTTP/myrealm.org@MYORG.ORG -e aes256-cts-hmac-sha1-96 -V 0

The -k argument specifies the name of the keytab file which will be created or updated. The command “add” takes the following argument flags:

“-p” : service principal, format <service>/<fully.qualified.domain>@REALM
“-e” : encryption type. Depending on the encryption type, you may need to download additional Java security libraries for strong encryption.
The following encryption types are not supported by Fusion: * DES-CBC-CRC * DES_CBC_MD5 * Microsoft Windows 2000 RC4-HMAC
“-V” : key version number (kvno). Key version numbers are used in the Kerberos V5 protocol to distinguish between different keys in the same domain.

If successful, this command creates a keytab file called “http-myrealm.org.keytab”. Note the directory you are in - you will need this full path when creating the Proxy realm-config later.

Step 4. Test the Keytab file

The location of this keytab file will be used to configure UI Proxy configuration. Before configuring the Fusion UI Proxy, you should check that the keytab file is valid. Testing the keytab requires the following sequence of steps:

Clear any existing credentials via command kdestroy.
Log in using the keytab as an argument to the command kinit -kt <keytab file> <principal>, where <principal> is the name of a principal within the keytab file.
Examine your credentials via command klist.
Clear credentials via command kdestroy, which removes any existing credentials, effectively logging you out of Kerberos.

To remove cached credentials, use the kdestroy command. This command succeeds silently. To check that credentials have been removed, re-run the klist command:

> kdestroy
> klist
klist: krb5_cc_get_principal: No credentials cache file found

Use the keytab to login as the service principal, without being prompted for a password:

> kinit -t http-myrealm.org.keytab HTTP/myrealm.org

Examine your credentials via the command klist. The output should be similar to this:

Credentials cache: API:51D488FF-5CD9-4E16-98FA-B47743F5B4ED
        Principal: HTTP/myrealm.org@MYORG.ORG

  Issued                Expires               Principal
Apr  1 09:15:02 2015  Apr  1 19:13:42 2015  krbtgt/MYORG.ORG@MYORG.ORG

Logout again with kdestroy.

Configuring Fusion Authentication for Kerberos Realm

Once you have tested both the user and service principal logins, you must create the service principal realm-config in the Fusion Authentication Proxy. This allows the Proxy to authenticate to Kerberos as the service principal, without a password.

Step 5. Configure the Fusion Realm

Fusion security realms can be configured either via the Fusion UI Admin tool or the Fusion REST API. The advantage of using the Fusion UI Admin Tool is that a single panel’s worth of configuration requires a series of calls to the REST API. It is important to understand the set of configuration properties collected by the Fusion UI and how they are used by the REST API.A security realm for Kerberos has the following properties:

name : unique string identifier
realmType : “kerberos”
enabled : whether or not the realm is available for users to use with system authentication
config : this property is required for the realm type “kerberos”. It takes two key-value pairs:
- principal : the principal service name
- keytab : this must be the full path to the keytab file.

To configure Fusion via the Fusion UI:

Log in to Fusion as “admin” or as a user who has super-admin privileges.
In the left-hand side navigation bar, click System > Access control.
Click the Security Realms tab, then Add Security Realm.
On the New Security Realm form, choose type “kerberos” from the pulldown menu so that there are input boxes for the Kerberos realm properties “Service Principal” and “Keytab path”.
Choose a realm name, and make sure the “enabled” box is checked.
If the auto-created box is unchecked, a user with admin privileges will need to create Fusion user accounts.
Select default roles. The default roles are assigned to a user the first time they access Fusion via this realm, using the Kerberos/SPNEGO protocol. For example, once you have defined a Kerberos realm “my-kerberos-realm” for domain “MYORG.ORG”, when user “any.user” in domain “MYORG.ORG” authenticates to Fusion for the first time via this realm, they are added to the set of Fusion users as username “any.user@MYORG.ORG” and they have all default roles. It is prudent to allow the minimum set of default roles, as all users will have these permissions. Some users will require admin privileges and a few users will require super-admin privileges. There should always be a user with super-admin privileges that can authenticate to Fusion using the native security realm and can then grant permissions to individual users as needed.
The Fusion proxy Kerberos realm works only with one Fusion host. For a multi-node Fusion cluster where each node resides on a different host, configure a separate realm for each host with a dedicated service/principal.
Enter the service principal and the full path to the keytab file.
Click Save. Fusion displays a confirmation message.

Kerberos/SPNEGO HTTP Authentication

SPNEGO provides a mechanism for extending Kerberos to applications that use the HTTP protocol including web browsers and the curl command-line utility.

Step 6. Configure the HTTP client

When a user sends a request to the Kerberized Fusion UI, a SPNEGO request (http[s]) is made. If the user is not already authenticated, the Fusion authentication proxy will yield a 401 status code and a Negotiate header. This status/header response triggers compatible clients to fetch a local ticket from their Kerberos “ticket tray”. This ticket is then encoded and sent back to the Fusion. The Fusion authentication proxy will then decode the ticket, and perform a SPN.doAs(user) authentication request to the KDC/Authentication Service. Depending on the results, the proxy then successfully executes the original request (along with a session cookie) or a 401 (without the Negotiate). Clients can either choose to use the session cookie or continue authenticating on every request.

Configuring Web Browsers and `curl` for SPNEGO

The --negotiate option enables SPNEGO in curl.IE and Safari require no additional configuration to use SPNEGO.To configure Firefox, access the low level configuration page by loading the about:config page. Then go to the network.negotiate-auth.trusted-uris preference and add the hostname or the domain of the web server that is HTTP Kerberos SPNEGO protected (if using multiple domains and hostname use comma to separate them).The Chrome browser must be launched from the command line with several added parameters.To run Chrome on linux:

> google-chrome --enable-plugins --args\
  --auth-server-whitelist="*KERBEROS_DOMAIN"\
  --auth-negotiate-delegate-whitelist="*KERBEROS_DOMAIN"\
  --auth-schemes="basic,digest,ntlm,negotiate"

To run Chrome on a Mac:

> open 'Google Chrome.app' --args\
  --auth-server-whitelist="*ROGUECLOUD.COM"\
  --auth-negotiate-delegate-whitelist="*KERBEROS_DOMAIN"\
  --auth-schemes="basic,digest,ntlm,negotiate"

To run Chrome on Windows:

chrome.exe --auth-server-whitelist="*KERBEROS_DOMAIN"\
  --auth-negotiate-delegate-whitelist="*ROGUECLOUD.COM"\
  --auth-schemes="basic,digest,ntlm,negotiate"

For more information, see Using a Web Browser to Access an URL Protected by Kerberos HTTP SPNEGO and Authentication + Authorization.

Session cookies

A successful Kerberos/SPNEGO login will yield a session cookie, this cookie is identical to the cookie yielded by the Fusion authentication proxy’s current POST-login-mechanism.The expiration policy on the cookie is currently fixed at 8 hours. But has a 1 hour “idle” max, which means if you do not make a request for 1 hour, the cookie is invalidated. Otherwise the lifetime is pushed ahead until the 8 hour max is met.The name of the cookie is “id” and the value is a UUID. This UUID is a key that maps to an in-memory value containing the real user ID.

Testing and Troubleshooting

Once you have configured the Kerberos security realm, you can test it as follows:

Log out of Fusion and shut down the browser.
Check that you have a valid Kerberos authentication ticket via the klist command.
Open a new browser session and access the Fusion installation. This should take you directly to the main Fusion panel, bypassing the Fusion “Welcome” login panel. To view your login profile, click on the profile icon at the top right. Your user name should be your login name + ”@” + your domain name.
- If you see the Fusion login panel instead of the main Fusion panel, your browser is not configured for SPNEGO.
- If the Fusion display consists only of an empty top nav bar, this indicates an authentication failure. Check that the path to your keytab file is correct. Then check the Fusion logs.
- If your KDC uses a weak encryption method, Fusion rejects your login credentials. The following weak encryption types are disabled in Fusion:
  - DES-CBC-CRC
  - DES_CBC_MD5
  - Microsoft Windows 2000 RC4-HMAC

References and Tutorials

https://en.wikipedia.org/wiki/Kerberos_%28protocol%29
http://www.roguelynn.com/words/explain-like-im-5-kerberos/
https://en.wikipedia.org/wiki/SPNEGO
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/Using_Kerberos.html#about-kerberos
http://www.oracle.com/technetwork/articles/idm/weblogic-sso-kerberos-1619890.html - section “Install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files”
http://www.cisco.com/c/en/us/support/docs/security-vpn/kerberos/16087-1.html

Configure Fusion for Kerberos in Windows

To configure the Fusion UI service to use Kerberos for user authentication, you must create a Kerberos security realm.

Kerberos support requires Fusion 5.9.5.

This article focuses on configuring Fusion for Kerberos in Windows.

Kerberos support requires Fusion 5.9.5.

Set up and Configure the Active Directory Domain Service

Install the Active Directory Domain Service

To begin, follow Microsoft’s instructions on how to install Active Directory Domain Services.This topic uses the following domain throughout this example:


NETBIOS Domain	FUSIONIS
Fully qualified domain name	fusionis.life

Create a New User

Launch the Server Manager. Navigate to Tools > Active Directory Users and Computers. Within the fusionis.life server, locate the “Users” folder, right-click on the folder and select New > User.

When creating a user for this purpose, ensure the First name and Display name fields both hold the exact same value.

These instructions use the following user name throughout this example:

User name	Notes
Distinguished name (DN)	CN = kerberos500 CN = Users DC = fusionis DC = life
User Principal Name (UPN)	`kerberos500@fusionis.life`
NETBIOS Domain\samAccountName	FUSIONIS\kerberos500

Establish the desired delegation rules for the new user in the “Delegation” tab.

Create a Keytab for the New User

Enter the following command into the command prompt to create a keytab for the user you just created:

ktpass -out c:\Users\Administrator\kerberos500.keytab -princ HTTP/fusionis.life@FUSIONIS.LIFE -mapUser FUSIONIS\kerberos500 -mapOp set -pass YOUR_PASSWORD -crypto AES256-SHA1 -pType KRB5_NT_PRINCIPAL -kvno 0

The following weak encryption types are not supported by Fusion:

DES-CBC-CRC * DES_CBC_MD5
Microsoft Windows 2000 RC4-HMAC

The output will be similar to:

C:\Users\Administrator>ktpass -out c:\Users\Administrator\kerberos500.keytab -princ HTTP/fusionis.life@FUSIONIS.LIFE -mapUser kerberos500 -mapOp set -pass FroFro123# -crypto AES256-SHA1 -pType KRB5_NT_PRINCIPAL
Targeting domain controller: WIN-OVV6VHBGIB8.fusionis.life
Using legacy password setting method
Successfully mapped HTTP/fusionis.life to kerberos500.
Key created.
Key created.
Key created.
Key created.
Key created.
Output keytab to c:\Users\Administrator\kerberos500.keytab:
Keytab version: 0x502
keysize 71 HTTP/fusionis.life@FUSIONIS.LIFE ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype 0x1 (DES-CBC-CRC) keylength 8 (0xcd07200bea625d20)
keysize 71 HTTP/fusionis.life@FUSIONIS.LIFE ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype 0x3 (DES-CBC-MD5) keylength 8 (0xcd07200bea625d20)
keysize 79 HTTP/fusionis.life@FUSIONIS.LIFE ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype 0x17 (RC4-HMAC) keylength 16 (0xe39a141de38abd8750bf9c0bf49fd1c5)
keysize 95 HTTP/fusionis.life@FUSIONIS.LIFE ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype 0x12 (AES256-SHA1) keylength 32 (0xdd6018ab718a4c312038189a20498f70c07d09a19d77ceea31cdd4cd1b08800a)
keysize 79 HTTP/fusionis.life@FUSIONIS.LIFE ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype 0x11 (AES128-SHA1) keylength 16 (0x9b610485eae2d97dcf0ecaf4ab38a32b)

This process will create the kerberos500.keytab file required to set up the Kerberos realm in Fusion. The command will also set the service principal to HTTP/fusionis.life@FUSIONIS.LIFE.

If you see the following, the user was not created correctly: DsCrackNames returned 0x2 in the name entry for kerberos500. Ktpass:failed getting target domain for specified user. Delete the user, and repeat the steps above.

Set up Kerberos on Fusion Server

Install Fusion and set up the Kerberos Realm

If you have not done so already, install Fusion now.Copy the keytab file to the server.

The keytab file must be installed on each Fusion node.

Log into Fusion as a native admin and navigate to DevOps > Access Control > Realms > New Realm. Use the following parameters:


Type	Kerberos
Keytab file	The path to the keytab file you saved on the server
Service principal	The service principal you generated in the previous step
Kerberos name mapping	The field that specifies the mapping from a Kerberos Principal name to a short name

You can specify the default rule, which should work for most situations:

DEFAULT
RULE:[1:$1@$0](.*@.*)s/@.*//

You can also add custom rules. See Mapping Kerberos Principals to Short Names for more information on creating custom rules.Save your new realm before continuing. You should now be able test with Negotiate authentication.

Verify Kerberos is Working

You will test to verify that Kerberos is working in the following sections. You must log into Windows as a user in the protected realm, meaning that the service principal name you are using has access to generate a ticket for your user.

Verify with cURL

Windows users can log in as a user within the domain, launch the command prompt, and run the cURL command below:

curl --negotiate -u : http://fusionis.life:8764/api/apollo/collections

Linux users may also need to run a kinit to login as a user prior to running.Navigate your web browser to http://fusionis.life:8764. If you are automatically logged in, Kerberos is working.

Verify with Google Chrome

To verify Kerberos is working with Google Chrome, run Chrome with the following command parameters:

"c:\Program Files (x86)\Google\Chrome\Application\chrome.exe" --auth-server-whitelist="*fusionis.life" --auth-negotiate-delegate-whitelist="*fusionis.life" --auth-schemes="basic,digest,ntlm,negotiate"

Navigate your web browser to http://fusionis.life:8764. If you are automatically logged in, Kerberos is working.

Verify with Firefox

To verify Kerberos is working with Firefox, navigate to about:config in your browser’s URL bar. If a message appears stating “This might void your warranty!”, click “I accept the risk!”.Search for the string network.negotiate-auth.trusted-uris, double-click the field, and enter fusionis.life into the field that appears. Click “Ok”.Navigate your web browser to http://fusionis.life:8764. If you are automatically logged in, Kerberos is working.

Troubleshooting

Defective token detected

If you encounter this issue, check the var/log/proxy/proxy.log after attempting to make a request.See Stack Overflow for addtional steps to resolve this issue.

Kerberos Name mapping rules

You may see the following error if you did not specify a mapping rule and the Proxy could not figure out how to map the Kerberos Principal name to a short name:

2021-07-30T15:15:03,584 - ERROR [qtp353842779-52:clojure.tools.logging$eval11$fn__16@0] - {} - Uncaught application error!
org.apache.hadoop.security.authentication.util.KerberosName$NoMatchingRule: No rules applied to YOURUSERNAME@YOURDOMAIN.SUBDOMAIN.EXAMPLE.COM

Adjust your Kerberos name mapping rules to resolve this issue.

LDAP

You can use LDAP as an authentication provider for Fusion. If the LDAP contains groups that make sense regarding partitioning Fusion functionality for Fusion users (that is, giving Fusion users different UI and API permissions based on the LDAP-group memberships of LDAP users), then you can configure an LDAP security realm to search for LDAP groups and to map the LDAP groups to Fusion roles. Fusion stores a local user record in ZooKeeper, and authentication is performed by the LDAP server. User accounts can be managed by Fusion, or created automatically, in which case the Fusion user ID maps directly to the LDAP Distinguished Name (DN). Fusion permissions can be assigned automatically based on LDAP group membership. See Configure Fusion 5.x for LDAP.

Configure Fusion 5.x for LDAP

You can create security realms that use external LDAP servers for authentication. Optionally, Fusion can search in the LDAP for groups to which a user belongs, and then map those groups to Fusion roles. Fusion performs authorization using permissions stored in Fusion users and Fusion roles.Note: Fusion does not use permissions from the LDAP for authorization of UI access or API requests. It only obtains group names (optionally), which are mapped to role names. If an Active Directory Security Query Trimming Stage is used, then directory-service permissions are used for trimming. If a connector supports security trimming, then connector permissions are used for trimming.To configure Fusion to use an external LDAP as an authentication provider, you’ll need to get information about the LDAP server(s) running on your system, either from your system or your sysadmin.

Add an LDAP Security Realm

Log in to the Fusion UI as the user admin, or as a different user with corresponding permissions.
Navigate to System > Access Control.
Click Security Realms.
Click Add Security Realm.
Specify info for the new realm:
- name – Name of the security realm. It must be unique. It should be descriptive but short.
- type – Select ldap from the pulldown menu. When you select ldap, Fusion displays additional, LDAP-specific configuration options.
- enabled checkbox – Whether Fusion allows user logins for this security realm. The default is yes (checked).
- auto-create users checkbox – Whether a user account is created automatically upon initial authentication. The default is yes (checked). If the checkbox is unchecked, then a Fusion user with admin permissions must create Fusion users.
Scroll down and specify additional options as explained in detail below.

Specify Static Roles (Optional)

Specify one or more Fusion roles for the security realm. These roles are always considered. They do not depend on searching for LDAP groups and mapping group names to Fusion role names.In a security realm, you can specify these static roles, add to the list of roles dynamically through an LDAP search, or both. If you do neither, Fusion uses only the role(s) and permissions defined for the user.

Specify LDAP Connection Details

Specify the hostname and port of the LDAP server. Check the checkbox if the server is running over SSL.

Specify the Authentication Method

Specify the authentication method:

Bind. LDAP authentication is carried out via a single “Bind” operation. See Bind below.
Search. LDAP authentication is carried out indirectly via a Search operation followed by a Bind operation. See Search below.
Kerberos. Kerberos authenticates Fusion and an LDAP Search operation is carried out to find group-level authorizations. See Kerberos below.

Bind

Use the Bind authentication method when the Fusion login username matches a part of the LDAP distinguished name (DN). Specify the remainder of the LDAP DN in the “DN Template” configuration entry, which uses a single pair of curly braces ({}) as a placeholder for the value of the Fusion username.

Search

Use the Search authentication method when the username used for Fusion login doesn’t match a part of the LDAP DN. The search request returns a valid user DN, which is then used together with the user password for authentication via a Bind request.

Construct a search request. The Search authentication method is generally required when working with Microsoft Active Directory servers. In this case, you need to know the username and password of some user who has sufficient privileges to query the LDAP server for user and group memberships; this user doesn’t have to be the superuser. In addition to a privileged user DN and password, the Search authentication method requires constructing a search request. There are two parts to the request. The first part is the base DN of the LDAP directory tree that contains user account objects. The second part of the request is a Search Filter object that restricts the results to a matching subset of the information.
Provide the administrator bind DN:

Kerberos

Use the Kerberos authentication method when Kerberos is the authentication provider.

Search for LDAP Groups (Optional)

A Fusion role is a bundle of permissions tailored to the access needs of different kinds of users. Access to services and data for LDAP-managed users is controlled by mappings from LDAP users and groups to Fusion roles.Roles can be assigned globally or restricted to specific LDAP groups. The security realm configuration panel contains a list of all Fusion roles with a checkbox for each, used to assign that role to all users in that realm. LDAP group names can be mapped directly to specific Fusion roles and LDAP group search and filter queries can also be used to map kinds of LDAP users to specific Fusion roles.

Map LDAP Groups to Fusion Roles (Optional)

If LDAP group names returned by the search for groups match Fusion role names, you do not need to map the group names to role names. You must map any LDAP group names that do not match to Fusion role names (if you do not, they will not be used).

Save the Security Realm Configuration

Click Save.Fusion reports whether or not authentication was successful:

Basic LDAP Concepts and Terminology

The LDAP protocol is used to share information about users, systems, networks, and services between servers on the internet. LDAP servers are used as a central store for usernames, passwords, and user and group permissions. Applications and services use the LDAP protocol to send user login and password information to the LDAP server. The server performs name lookup and password validation. LDAP servers also store Access Control Lists (ACLs) for file and directory objects which specify the users and groups and kinds of access allowed for those objects.LDAP is an open standard protocol and there are many commercial and open source LDAP servers available. Microsoft environments generally use Active Directory. Unix servers use AD or other LDAP systems such as OpenLDAP, although many Unix systems do not use LDAP at all. To configure Fusion for LDAP, you’ll need to get information about the LDAP server(s) running on your system either from your sysadmin or via system utilities.

Directories and Distinguished Names

An LDAP information store is a Directory Information Tree (DIT). The tree is composed of entry nodes; each node has a single parent and zero or more child nodes. Every node must have at least one attribute which uniquely distinguishes it from its siblings which is used as the node’s Relative Distinguished Name (RDN). A node’s Distinguished Name (DN) is a globally unique identifier.The string representation of a DN is specified in RFC 4514. It consists of the node’s RDN followed by a comma, followed by the parent node’s DN. The string representation of the RDN is the attribute-value pair name, connected by an equals (”=”) sign. This recursive definition means that the DN of a node is composed by working from the node back through its parent and ancestor nodes up to the root node.Here is a small example of a DIT:

The person entry in this tree has the DN: “uid=babs, ou=people, dc=example, dc=com”.Attribute names include many short strings based on English words and abbreviations, e.g.:


Name	Description
cn	commonName
dc	domainComponent
mail	email address
ou	organizationalUnitName
sn	surname
uid	userId

LDAP entry attributes can refer to other LDAP entries by using the DN of the entry as value of that attribute. The following example of a directory which contains user and groups information shows how this works:

This tree contains two organizational units: “ou=people” and “ou=groups”. The children of the “group” organizational unit are specific named groups, just as the child nodes of organization unit “people” are specific users. There are three user entries with RDNs “uid=bob”, “uid=alice”, “uid=bill” and two groups with RDNs “cn=user” and “cn=admin”. The dotted lines and group labels around the person nodes indicate group membership. This relationship is declared on the groups nodes by adding an attribute named “member” whose value is a users DN. In the LDAP data interchange format (LDIF), this is written:

cn=user,ou=groups,dc=acme,dc=org
    member: uid=bob,ou=people,dc=acme,dc=org
    member: uid=alice,ou=people,dc=acme,dc=org
cn=admin,ou=groups,dc=acme,dc=org
    member: uid=bill,ou=people,dc=acme,dc=org

See the Wikipedia’s LDAP entry for details.

LDAP Protocol Operations

For authentication purposes, Fusion sends Bind operation requests to the LDAP server. The Bind operation authenticates clients (and the users or applications behind them) to the directory server, establishes authorization identity used for subsequent operations on that connection, and specifies the LDAP protocol version that the client will use.Depending on the way that the host system uses LDAP to store login information about users and groups, it may be necessary to send Search operation requests to the LDAP server as well. The Search operation retrieves partial or complete copies of entries matching a given set of criteria.LDAP filters specify which entries should be returned. These are specified using prefix notation. Boolean operators are ”&” for logical AND, ”|” for logical OR, e.g., “A AND B” is written ”(&(A)(B))”. To tune and test search filters for a Unix-based LDAP system, see the ldapsearch command line utility documentation. For Active Directory systems, see AD Syntax Filters.

SAML

Fusion stores a local user record in ZooKeeper and the URL and information about the SAML Identity Provider. The SAML 2.0 protocol is used to provide web browser single sign-on. See Configure Fusion for SAML.

Configure 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).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.
Enter the following information 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"
}

References

Manage Security Realms

Only Fusion users with admin privileges can manage security realms. There are two ways to manage security realms: In the Fusion UI Navigate to System > Access Control > Security Realms. Using the Realms API Use the http://FUSION_HOST:FUSION_PORT/api/realm-configs/ endpoint to manage security realms. See the Realms API reference for details. In production environments, use port 8765.

Introduction to Fusion

Getting Data In

Getting Data Out

Operations

Reference

Developer Docs

Neural Hybrid Search

Release Notes

​Security Realm Types

​OpenID Connect

​Native

​SSO Trusted HTTP

​JWT

​Kerberos

​LDAP

​SAML

​Manage Security Realms

Security Realm Types

OpenID Connect

Native

SSO Trusted HTTP

JWT

Kerberos

LDAP

SAML

Manage Security Realms