Integrate SSO

note

Before you proceed to SSO configuration, make sure the customer IDP enforces no SP session duration interval. If it does, disable the setting. For an example with SiteMinder, refer to the configuration manual page.

Install secret-storage management utility

To install the utility, log in to the main installation server (by default, APP server), and run the command:

cd PACKAGE_DIR
./install.sh install wf-sec-storage

The secret-storage management tools appear in the INSTALL_DIR/wf-sec-storage directory. You may remove this directory after you finish configuration.

Prepare for configuration

When configuring SSO, and if you have LDAP in your infrastructure, we recommend to configure them together, so that you can implement authorization procedures (Control Tower and Workspace user rights assignment) on the LDAP group level. In this case, you need to create a new group in Control Tower with the same name as the LDAP group and assign a role (for example, Administrator) to it. Thus, the IdP server will be responsible for user authentication, and the LDAP server will be responsible for user authorization. For more information on configuring LDAP, see LDAP and AD integration.

If LDAP is not available, each particular user who is going to log in to Control Tower or Workspace using SSO must be explicitly configured and assigned a role in UI.

note

All users who are going to log in to Control Tower or Workspace using SSO must have the email address defined.

Before starting the SSO configuration, you need to obtain the following files from your IdP server (usually, a security team can provide them):

Server.crt file to establish a trusted HTTPS connection to your IdP server.
Metadata file (the name can be any, but here and further in the document, we will call it idp_metadata.xml).

The idp_metadata.xml file contains certificates for SAML communications. You must extract these certificates and manually place them to Java Key Store (jks) on the APP server. To do that (further examples are provided for Active Directory Federation Services):

In idp_metadata.xml, find the following strings:

<KeyDescriptor use="encryption">
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
    <X509Data> <X509Certificate>"encryption certificate data"</X509Certificate>

Copy the actual encryption certificate data and create an X509 certificate from it. You can use services like https://www.samltool.com/format_x509cert.php for conversion.
Save the resulting file as saml-enc.crt to INSTALL_DIR on the APP server.

The second certificate needs to be extracted in the same way as the first one. For that, in idp_metadata.xml, find the following strings:

<KeyDescriptor use="signing">
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
    <X509Data> <X509Certificate>"signing certificate data"</X509Certificate>

Copy the actual signing certificate data, convert it to the X509 certificate the same way you did it before and save the resulting file as saml-sign.crt to INSTALL_DIR on the APP server.

To obtain the password jks password, run the following command as WFUSER:

INSTALL_DIR/wf-sec-storage/loader.sh workfusion review | grep wf.sso.saml.keystore.password

Import these two certificates along with server.srt, to jks by running the following commands:

keytool -keystore INSTALL_DIR/ssl/wf_saml_integration.jks -storepass \<jks password\> -import -file server.crt - -alias saml-server-crt
keytool -keystore INSTALL_DIR/ssl/wf_saml_integration.jks -storepass \<jks password\> -import -file saml-enc.crt -alias saml-encryption
keytool -keystore INSTALL_DIR/ssl/wf_saml_integration.jks -storepass \<jks password\> -import -file saml-sign.crt -alias saml-signing

For high-availability and disaster recovery installation

If you have to change or update Java Key Store and its content, remember to make these changes on all instances, where Control Tower or Workspace are installed, for example, ct1 and ct2.

Integrate WorkFusion SAML

Save requested earlier IdP metadata to INSTALL_DIR/workfusion/idp_metadata.xml.
Log in to the APP servers as a service account.
Change the workfusion property file /opt/workfusion/workfusion/conf/workfusion.properties:
```
wf.sso.saml.enable=True
```
Go to INSTALL_DIR/wf-sec-storage/.
Create a temporary file (for example, workfusion-sso.properties) with the following parameters:
```
wf.sso.saml.idp.file.metadata=/opt/workfusion/workfusion/idp_metadata.xml
wf.sso.saml.sp.metadata=wf-sp-hostname
wf.sso.saml.username.attribute=uid
```
You must agree on the attribute with your IdP beforehand. The above configuration was tested in OpenLDAP and AD FS but you might need to adjust it depending on your setup.

Upload the new parameters to Vault Workfusion case:

loader.sh workfusion workfusion-sso.properties

To check the result, enter the command:

loader.sh workfusion review | grep -i sso

Restart the workfusion services to apply changes.
```
wfmanager restart workfusion
```

For high-availability and disaster recovery installation

Remember to make these changes on all instances, where Control Tower or Workspace are installed, for example, ct1 and ct2.

Download Workfusion Metadata

To download Workfusion Metadata:

In your web browser, go to https://workfusion-lb.example.com/workfusion/saml/web/metadata.
Enter the credentials from config.yml of Vault for authentication.

To obtain the username and the password, run the following command as WFUSER:
```
loader.sh workfusion review | grep wf.sso.saml.metadata.admin
```
Click Generate new service provider metadata, leave default values in all fields, and click Generate.

The spring_saml_metadata.xml file will be downloaded. Rename it to ct_metadata.xml.
Send ct_metadata.xml to your IdP provider security team.

Integrate WorkSpace SAML

Save requested earlier IdP metadata to INSTALL_DIR/workspace/idp_metadata.xml.
Log in to the APP servers as a service account.
In the workspace property file /opt/workfusion/workspace/conf/workspace.properties, make the following change:
```
ws.sso.saml.enable=True
```

Go to INSTALL_DIR/wf-sec-storage/, and create a temporary file (for example, workspace-sso.properties) with the following parameters:

ws.sso.saml.idp.file.metadata=/opt/workfusion/workspace/idp_metadata.xml
ws.sso.saml.sp.metadata=ws-sp-hostname
ws.sso.saml.username.attribute=mail

You must agree on the attribute with your IdP beforehand. See the examples below:

OpenLDAP:
```
ws.sso.saml.username.attribute=mail
```

AD FS:

ws.sso.saml.username.attribute=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Upload the new parameters to Vault Workspace case:
```
loader.sh workspace workspace-sso.properties
```
To check the result, enter the following command:
```
loader.sh workspace review | grep -i sso
```
Restart the workspace services to apply changes.
```
wfmanager restart workspace
```

For high-availability and disaster recovery installation

Remember to make these changes on all instances, where Control Tower or Workspace are installed, for example, ct1 and ct2.

Download Workspace Metadata

Open your web browser.
Go to https://workspace-lb.example.com/workspace/saml/metadata.
The spring_saml_metadata.xml file will be downloaded automatically. Rename it to ws_metadata.xml.
Send ws_metadata.xml to your IdP provider security team.

Integrate Elastic Stack SAML

The Elastic stack is operating as a service provider in the SAML terminology. Configuring SAML in Elastic stack will enable SSO in Kibana.

note

To integrate SAML for the Elastic stack in the HA environment, apply the below changes for all the servers/roles, for example, for two APP and three INT servers.

Configure Elasticsearch

To configure Elasticsearch:

Create the SAML realm by adding the following lines to elasticsearch.yml configuration file located in the <elasticsearch_home>/config directory.

xpack.security.authc.token.enabled: true
xpack.security.authc.realms.saml.<name_of_realm>:     # name of saml realm
    order: <order>                                    # unique order of realm. It's recommended that saml realm has the highest order
    idp.metadata.path: <path_to_idp_metadata>         # path to Identity provider metadata file or URL
    idp.entity_id: <idp_url>                          # Id of Identity Provider. It should match the entityID attribute within the metadata file.
    sp.entity_id:  <kibana_url>                       # Id of Service Provider. Recommended value is the base URL of Kibana instance.
    sp.acs: <kibana_url>/kibana/api/security/v1/saml         # Assertion consumer service URL. Must be in form of <kibana_url>/kibana/api/security/v1/saml
    sp.logout: <kibana_url>/kibana/logout                    # Single logout service. Must be in form of <kibana_url>/kibana/logout
    attributes.principal: <user_attribute_uri>        # URI of user attribute returned by Identity Provider
    attributes.groups: <group_attribute_uri>          # URI of group attribute returned by Identity Provider

# Example:
xpack.security.authc.token.enabled: true
xpack.security.authc.realms.saml.shibboleth:
    order: 2
    idp.metadata.path: saml/idp-metadata.xml
    idp.entity_id: "https://sso.example.com/"
    sp.entity_id:  "https://kibana.example.com/"
    sp.acs: "https://kibana.example.com/kibana/api/security/v1/saml"
    sp.logout: "https://kibana.example.com/kibana/logout"
    attributes.principal: "urn:oid:0.9.2342.19200300.100.1.1"
    attributes.groups: "urn:oid:1.3.6.1.4.1.5923.1.5.1."

You must agree on the attribute with your IdP beforehand. See the examples below:

OpenLDAP:

attributes.principal: "urn:oid:0.9.2342.19200300.100.1.1"
attributes.groups: "urn:oid:1.3.6.1.4.1.5923.1.5.1."

AD FS:

attributes.principal: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"
attributes.groups: "http://schemas.xmlsoap.org/claims/Group"
nameid_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"

Generate the Kibana SAML 2.0 Service Provider Metadata file by running the following commands:

$ cd <elasticsearch_home> # the directory where elasticsearch is installed to.

$ bin/elasticsearch-saml-metadata --realm <name_of_realm>     # the name of the SAML realm configured in elasticsearch.yml file.

# Example
$ bin/elasticsearch-saml-metadata --realm shibboleth

Register Service Provider at Identity Provider by providing the generated Service Provider Metadata file to Identity Provider.

Map a role via Kibana API. For that, go to Kibana UI as the admin user, open the Dev tool tab, and POST the role mappping in the following format:

POST /_security/role_mapping/<mapping_name>    # name of the mapping request
{
    "enabled" : true,
    "roles" : [
    "<kibana role>"                          # role with permissions the users should be mapped to, for example, superuser, kibana_user
    ],
    "rules" : {
    "all" : [
        {
        "field" : {
            "realm.name" : "<name_of_realm>"   # name of saml realm 
        }
        },
        {
        "field" : {
            "groups" : "<group_name>"          # group name users belong to from AD/LDAP, for example, Admins
        }
        }
    ]
    },
    "metadata" : { }
}

# Example
POST /_security/role_mapping/saml-superuser
{
    "enabled" : true,
    "roles" : [
    "superuser"
    ],
    "rules" : {
    "all" : [
        {
        "field" : {
            "realm.name" : "shibboleth"
        }
        },
        {
        "field" : {
            "groups" : "Admins"
        }
        }
    ]
    },
    "metadata" : { }
}

For the description of a built-in user, see the guide.

Configure Kibana

Log in to the APP server via SSH and add the following lines to kibana.yml located in the <kibana_home>/config directory to use the SAML realm.

# SAML integration
xpack.security.public:
  protocol: https
  hostname: <kibana_DNS_record>        # kibana-lb.example.com
  port: 443

xpack.security.authProviders: [saml]
xpack.security.authc.saml.realm: <name_of_realm>     # name of saml realm specified in elasticsearch.yml, for example, shibboleth
server.xsrf.whitelist: [/api/security/v1/saml]

# Example
xpack.security.public:
  protocol: https
  hostname: kibana.example.com
  port: 443

xpack.security.authProviders: [saml]
xpack.security.authc.saml.realm: shibboleth
server.xsrf.whitelist: [/api/security/v1/saml]

The SAML support in Kibana assumes that it will be the primary (or sole) authentication method for users of that Kibana instance. However, it is possible to support both SAML and Basic authentication within a single Kibana instance by setting xpack.security.authProviders as per the example below:

xpack.security.authProviders: [saml, basic]

Restart Kibana and Elasticsearch.
```
wfmanager restart elasticsearch kibana
```

WorkFusion Documentation

10.1.6

Hardware

Install Linux components

Security settings in Control Tower

note

Install secret-storage management utility

Prepare for configuration

note

For high-availability and disaster recovery installation

Integrate WorkFusion SAML

For high-availability and disaster recovery installation

Download Workfusion Metadata

Integrate WorkSpace SAML

For high-availability and disaster recovery installation

Download Workspace Metadata

Integrate Elastic Stack SAML

note

Configure Elasticsearch

Configure Kibana