SAML

SAML (Security Assertion Markup Language) is an open standard for exchanging authentication and authorisation data.

The SAML release of SuperSTAR provides support for authenticating users via a third-party SAML identity provider.

Limitations in this Release

There are some limitations in this release:

SAML authentication is currently supported for SuperWEB2 only; it is not supported for the SuperADMIN Console or for SuperCROSS. This may be addressed in a future release, subject to customer requirements.
Open Data API access is not currently supported for SAML-authenticated users. Non SAML authenticated users can use the API.
Customers may encounter issues if they have local user accounts defined in SuperADMIN with IDs that clash with those of user accounts authenticated via SAML. This is an existing known issue with SuperSTAR’s authentication module functionality (for example it is also an issue when configuring authentication via Active Directory or LDAP). WingArc does not currently plan to address this issue: the recommended workaround is to ensure that the user IDs of SAML-authenticating users are different to those of any local user accounts.
For SAML authentication to work properly with SuperWEB2 account based features, the Identity Provider must be configured to use a persistent name ID. If the Identity Provider only supports transient name IDs then authentication will work, but users will not be able to retrieve their private saved tables on future logins (as they will log back in with a different ID).

Depending on customer requirements, this may be addressed in a future release (which would then treat users with transient IDs as guest users, with the account-based features disabled, rather than allowing them to save tables and custom data but not reload them).

You can use the nameIdFormat setting in your authentication module to specify which attribute from the identity provider to use to uniquely identify users.

Configure SAML

Follow the steps below to set up SAML authentication:

Step 1 - Create SuperADMIN Authentication Service

The first step is to create an authentication service in the SuperADMIN console using the auth command. If you are working with multiple SAML identity providers (for example you have different providers for internal and external users, or different groups of external users connecting via different providers) then you will need to create a separate authentication service for each one.

Type the following command to create a new SAML authentication service:

TEXT

auth add SAML <service_name>

Replace <service_name> with a unique ID of your choice for this service. For example:

CODE

auth add SAML saml_keycloak

Step 2 - Configure the Service

Use the following commands to configure the service parameters.

Each command starts with auth <service_name>, where <service_name> is the name you selected in step 1 when you created the service.
You can type auth services or auth <service_name> at any time to review the settings you have already configured.

auth <service_name> identityProviderMetadataPath <url_or_file_path>

Replace <url_or_file_path> with the location of the metadata file supplied by the identity provider, enclosed in double quotes. In most cases this will be a URL, but can also be a file path to a local file (starting with file://) in cases where the SAML identity provider supplies a file for download and local hosting, rather than a direct link.

For example:

auth saml_keycloak identityProviderMetadataPath "https://example.com/realms/master/protocol/saml/descriptor"

auth <service_name> entityId <entity_ID>

A unique identifier for this entity to be configured on the SAML identity provider, enclosed in double quotes.

In most cases you should follow these general best practice guidelines for creating an entity ID. If the SAML identity provider is only used internally then you may have your own entity ID format, in which case you should use that instead (if the identity provider is only used for this service, then the entity ID can use any format you wish).

auth <service_name> callbackUrl <callback_url>

The URL that the user will be redirected to after successful login via the SAML identity provider. Set this to the full URL of your SuperWEB2 instance, followed by rest/saml/login and enclosed in double quotes.

For example, if your SuperWEB2 server is available at https://myserver.com/webapi/ then the callback URL would be configured as follows:

auth saml_keycloak callbackUrl "https://myserver.com/webapi/rest/saml/login"

auth <service_name> groupAttribute <attribute>

The type of attribute used on the SAML identity provider for managing collections of permissions, enclosed in double quotes. This will typically be either Role or Group. For example:

auth saml_keycloak groupAttribute "Role"

In the next section, you will use the groupMapping parameter to configure how these roles or groups should be mapped to local groups defined in SuperADMIN.

auth <service_name> groupDelimiter <attribute>

(Optional). A delimiter used to split the attributeValues string in the SAMLAttribute returned from the SAML identity provider, enclosed in double quotes.

If you choose to specify a delimiter, then the string in the SAML ticket will be split into individual groups using the delimiter character. For example, if the SAML ticket contains the following value:

attributeValues=[public|registered|census]

Then you can split this into the individual groups public, registered, and census by setting the delimiter to |. For example:

auth saml_keycloak groupDelimiter "|"

auth <service_name> authnRequestBindingType <type>

(Optional). Use a specific binding type (redirect or post) on the identity provider. If the specified binding is not supported, it will fall back to the supported binding.

If not specified, defaults to post.

Supported values:

post or urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
redirect or urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

auth <service_name> nameIdFormat <format>

(Optional). The attribute to use as the name ID (unique ID for the user). You will need to ensure you have configured the identity provider accordingly for whatever value you set in SuperADMIN.

If not specified, defaults to urn:oasis:names:tc:SAML:1.1:nameid-format:persistent.

For example:

auth saml_keycloak nameIdFormat "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"

auth <service_name> groupMapping <mapping>

A mapping between the roles or groups on the identity provider and the corresponding local groups defined in SuperADMIN. These mappings can be based on information provided by the identity provider, but you should take care about how explicitly you configure the mappings, depending on how much you trust or control the identity provider.

If you have not already done so, you will need to use the SuperADMIN console to create local groups as appropriate and define permissions for those groups.

Configure the mappings in the form: "<remote_group>=<local_group>"

Replace <remote_group> with the name of the role or group on the SAML identity provider.
Replace <local_group> with the local SuperADMIN group you want to map it to.
Separate each mapping with a semi colon.
Enclose the complete mapping definition in double quotes.

You can use the wildcard * on the left side to represent all roles or groups and _ on the right side to map a remote role or group to a group of the same name in SuperADMIN.

Following are some examples in order of safety:

Map All Users to a Specific SuperADMIN Group

For example: "*=keycloak_users"

This will map all users who are authenticated through this identity provider (including users who are not part of any group) to a SuperADMIN group named keycloak_users.

This is the safest mapping as the identity provider has no control over the groups that users are assigned to.

Map Specific Groups/Roles to Specific SuperADMIN Groups

For example: "subscribers=keycloak_subscribers;guests=_"

This will map:

All users with the subscribers group attribute to a SuperADMIN group named keycloak_subscribers.
All users with the guests group attribute to a SuperADMIN group named guests.

This type of mapping is reasonably safe even if you do not fully trust or control the identity provider as it only applies to specific groups that you explicitly define.

You should be careful about mapping any groups to SuperADMIN’s administrators group (including via use of the _ wildcard), as this would allow the identity provider to designate users as SuperSTAR administrators.

Pass Through all Groups/Roles Unchanged

"*=_"

This will map all groups or roles on the identity provider to the corresponding SuperADMIN groups of the same name. This should only ever be used if you fully trust or control the identity provider.

auth <service_name> adminGroup <group>

(Optional). A group of users from the identity provider who should have administrator-level permissions in SuperWEB2.

If you choose to specify this setting, you must also ensure that the group is passed through to SuperADMIN using the groupMapping. It can either be explicitly mapped, or passed through using a wildcard (the group itself does not need to exist as a local group in SuperADMIN).

If you do not set a value for adminGroup in your authentication module, it will be added automatically and set to administrators by default. This default setting will not take effect unless you also configure the groupMapping to pass through the administrators group.

Note that as SAML authentication is currently supported only for SuperWEB2 connections, the effect of designating users as administrators is currently limited to those users having access to all datasets in SuperWEB2. They will not be able to log in to the SuperADMIN console via the SAML-authenticated users.

auth <service_name> displayNameAttribute <attribute>

auth <service_name> enableDisplayName {true|false}

(Optional). The attribute from the identity provider to use as the display name for the user. For example:

CODE

auth saml_keycloak displayNameAttribute "displayName"

The display name appears in the logout option on the menu in the top-right of SuperWEB2.

By default, SuperWEB2 will attempt to use the display name attribute sent by the identity provider. In most cases this will work automatically and you will not need to set a value for displayNameAttribute in your authentication module. However, if you want to use a different attribute to the default (or the default does not work for your provider), set displayNameAttribute to the name of the attribute you want to use.

You do not need to set the enableDisplayName property unless you want to stop using display names completely: if you set enableDisplayName to false SuperWEB2 will use the configured name ID instead. You can revert back to using display names by setting the value of enableDisplayName to true.

You should avoid changing the display name settings after going into production with SAML authentication as future changes to this setting will affect the ability of users to access their previously saved tables.

Example Configuration

Following are some examples of complete configuration.

Map all users to one fixed SuperADMIN group:

CODE

auth saml_keycloak identityProviderMetadataPath "https://example.com/realms/master/protocol/saml/descriptor"
auth saml_keycloak entityId "https://example.com/idp"
auth saml_keycloak callbackUrl "https://myserver.com/webapi/rest/saml/login"
auth saml_keycloak groupMapping "*=keycloak_users"

Map all users to one fixed SuperADMIN group, with an additional explicit mapping:

CODE

auth saml_keycloak identityProviderMetadataPath "https://example.com/realms/master/protocol/saml/descriptor"
auth saml_keycloak entityId "https://example.com/idp"
auth saml_keycloak callbackUrl "https://myserver.com/webapi/rest/saml/login"
auth saml_keycloak groupAttribute "Role"
auth saml_keycloak groupMapping "*=keycloak_users;subscribers=keycloak_subscribers"

Step 3 - Export Metadata

Once you have completed the service configuration, you need to export the metadata for this service from the SuperADMIN configuration and upload this to the SAML identity provider.

Run the following command:
CODE
```
auth <service_name> exportMetadata <filename>
```
Replace <service_name> with the name you selected in Step 1 when you created the service.

You can use <filename> to specify where to write the export, which can be any of the following:
- A filename of your choice (this will be written to the console working directory; if you installed to the default location on Windows, this will be C:\ProgramData\STR\SuperADMIN\console);
- A relative path within the console working directory, followed by your chosen filename; or
- Omit the filename, in which case the file will be written to output/sp-metadata_<service_if>.xml
For example:
CODE
```
auth saml_keycloak exportMetadata samlmetadata.xml
```
Only locations within the console working directory are supported for the export. You can not use a file path to save the file to an arbitrary location on disk.
Locate the exported metadata file and upload it to the SAML identity provider you are using.

Step 4 - Configure SuperWEB2 Login

The next step is to configure how SuperWEB2 will present the different options on the login page. For example, you may want to:

Configure multiple different SAML services for different user groups.
Combine both standard logins (with a username and password), alongside SAML-based authentication.
Hide the SAML login options completely for general users, so only users with a special URL can login via SAML.

The structure of the login page is configured through login group configuration, which you define in SuperADMIN.

Default Login Page

By default, if you do not configure any login groups, SuperWEB2 simply displays an additional login button for each active SAML service with default button text that reads Log in with <service_name> (where <service_name> is the name you set in SuperADMIN).

You can configure the text on this button by editing the settings in the messages.properties configuration file (located in <tomcat_home>\webapps\webapi\WEB-INF\classes\). You may need to edit multiple versions of this file for all the UI languages you support:

To change the Log in with text, edit the value of page.login.loginWith.button.label (making sure to keep the {0} in the value, as this will be replaced with the corresponding service name:
CODE
```
page.login.loginWith.button.label=Log in with {0}
```
To set the display name for each configured service, add a new property in the format loginService.<service_name>.displayName (where <service_name> matches the name you set in SuperADMIN). For example:
CODE
```
loginService.saml_keycloak.displayName=SAML
```

Defining Login Groups (Optional)

If you are happy with the default login page described above, where all SAML login options are displayed on a single page, alongside the regular logins, then you do not need to do any additional login configuration.

However, for more advanced settings, such as if you want to have multiple different login pages for different user groups, you will need to define your login structure in SuperADMIN. By default, when you set up multiple login pages, users will be able to access a drop-down list to select the appropriate group for them, but you can also choose to hide the link to this selector, in which case users will be able to access the appropriate group via a special URL.

Refer to the loginConfig command for more details on the options available and how to configure them. Some example configurations are shown below.

You can define the labels for any groups you create by adding a new property in the format loginGroup.<group_name>.displayName to messages.properties (and the corresponding localised versions of that file for other UI languages that you support). For example:

CODE

loginGroup.saml_logins.displayName=SAML Logins

Example loginGroups Configuration

Following are some example group configurations for various scenarios. Each example assumes you are starting from an empty configuration with no existing groups defined.

Example Configuration: One SAML Identity Provider plus Local Users

The below example shows SuperADMIN commands to setup a single SAML identity provider (using the service named saml_keycloak) as well as local usernames and passwords.

JS

loginConfig addGroup SW2
loginConfig groups SW2 addservice "usernameAndPassword"
loginConfig groups SW2 addservice "saml_keycloak"

Example Configuration: One SAML Identity Provider Only

The below example shows a single SAML identity provider (using the service named saml_keycloak) only, and automatic login.

JS

loginConfig addGroup SW2
loginConfig groups SW2 addservice "saml_keycloak" true

Example Configuration: Multiple Login Groups with Separate SAML Identity Providers

The below example shows multiple SAML identity providers in different groups, as well as local usernames and passwords.

JS

loginConfig addGroup external
loginConfig addGroup internal
loginConfig groups external addservice "saml_keycloak" true
loginConfig groups internal addservice "usernameAndPassword"
loginConfig groups internal addservice "saml_azure"

Step 5 - Activate the SAML Service in SuperADMIN

Once you have completed the configuration, the final step is to activate the SAML service in SuperADMIN, by setting the active parameter on the service to true:

CODE

auth <service_name> active true

Replace <service_name> with the name you selected in Step 1 when you created the service. For example:

CODE

auth saml_keycloak active true

Once you have activated the service, open the SuperWEB2 login page and verify that you can login using the SAML identity provider.

If you make changes to the configuration of your SAML auth service after you activate it, you will need to reload the configuration using the following command:

auth <service_name> reload

For example:

auth saml_keycloak reload