auth, authentication

auth providers

Displays details of all the available authentication providers.

• STRLocal is the built-in local authentication service. This will always be available to ensure that you can always login to the system regardless of whether any external service is running. It is also available so that you can complete the initial configuration.

• Other available providers include Active Directory, eDirectory, SAML, and LDAP.

• The ExternalJAASModule provider allows you to create your own JAAS (Java authentication and authorisation service) module to integrate with other types of external authentication systems. For more information, see the sample code in the etc\samples directory in your installation. This sample code explains how to create a custom authentication module that can be integrated with SuperADMIN.

auth add <provider> <service_name>

Creates a new authentication service based on one of the available authentication providers.

auth services

Displays details of all configured authentication services.

auth <service_name>

Displays the current configuration settings for the specified authentication service.

auth <service_name> active {true|false}

Activates (true) or deactivates (false) the specified authentication service. Use this command to activate your authentication service when you have finished configuring it.

auth <service_name> priority <priority>

Sets the priority for this authentication service.

Each configured service has a priority: the service with the highest priority is tried first. If the login to the service fails, the next service is tried, and so on.

The built-in STRLocal service has a priority of 100, so you should set your external service to have a priority greater than 100. If you are adding multiple authentication services you can use the priority of each one to control the order in which they will be tried.

auth <service_name> id <new_service_name>

Changes the name of the specified service to the new specified name.

auth <service_name> remove

Removes the specified authentication service.

auth <service_name> adminGroup <group>

Sets the name of the group of users who should have administrator rights in SuperADMIN.

If you are using an external authentication provider this will be a group from the external server (only the group name is required; you do not need a full Distinguished Name/DN).

For SAML authentication modules, when using this setting you also need to ensure that the group specified as the adminGroup is configured to be passed through to SuperADMIN via the groupMapping, either explicitly or using a wildcard (the group itself does not need to exist as a local group in SuperADMIN). 

auth <service_name> reload

Reload the configuration for the specified service. Use this command to force SuperADMIN to reload the configuration if you have changed one or more of the service's settings after it has already been activated.

auth <service_name> url <url>

Sets the fully qualified domain name of the LDAP, Active Directory or eDirectory server.

auth <service_name> port <port>

Sets the port to use to connect to the LDAP, Active Directory or eDirectory server. This is only required if the server is using a non-standard port.

auth <service_name> basedn <base>

Sets the default base location for LDAP searches. This will be used to search for users or groups if they do not have an explicit basedn assigned.

auth <service_name> group nameattr <attribute>

Sets the name of the attribute in the external authentication service that holds the descriptive name of the group.

auth <service_name> group idattr <attribute>

Sets the name of the attribute in the external authentication service that holds the unique ID of the group (the standard Active Directory value is cn).

auth <service_name> group basedn <base>

Sets the default search location when searching for groups. This is optional. If it is not set then it will use the basedn configured for the service.

auth <service_name> group addbasedn <base>

Adds the specified basedn to the list stored in the group basedn parameter.

auth <service_name> group removebasedn <base>

Removes the specified basedn from the list stored in the group basedn parameter.

auth <service_name> group memberAttr <attribute>

Sets the name of the attribute in the external authentication service that indicates which users are members of the group (the standard Active Directory value is member).

auth <service_name> group groupClass <class>

Sets the class type that will be used to identify groups within the LDAP repository.

auth <service_name> group addfilter <group>

Adds the specified group to the group filter.

auth <service_name> group removefilter <group>

Removes the specified group from the group filter.

auth <service_name> user nameattr <attribute>

Sets the name of the attribute in the external authentication service that holds the descriptive name of the user.

auth <service_name> user idattr <attribute>

Sets the name of the attribute in the external authentication service that holds the unique ID of the user (the standard Active Directory value is sAMAccountName).

auth <service_name> user basedn <base>

Sets the default search location when searching for users. This is optional. If it is not set then it will use the basedn configured for the service.

auth <service_name> user addbasedn <base>

Adds the specified basedn to the list stored in the user basedn parameter.

auth <service_name> user removebasedn <base>

Removes the specified basedn from the list stored in the user basedn parameter.

auth <service_name> user groupAttr <attribute>

Sets the name of the attribute in the external authentication service that indicates which groups the user is a member of (the standard Active Directory value is memberOf).

auth <service_name> user userClass <class>

Sets the class type that will be used to identify groups within the external repository.

auth <service_name> contextlogin {true|false}

Enables or disables the use of a search login user, to find an initial context for logins.

auth <service_name> contextlogin password <password>

Sets the password to use for the context login. This setting only applies when contextlogin is set to true.

auth <service_name> contextlogin userdn <dn>

Sets the DN for the context login. This setting only applies when contextlogin is set to true.

auth <service_name> qualifieduser {true|false}

Specifies whether the name entered when a user is attempting to login is a fully qualified DN or a name that must be matched against the idattr set for user accounts.

You are recommended to leave this set to false to allow users to login using their normal login credentials rather than the full LDAP DN.

auth <service_name> groupprincipalclass <fully_qualified_classname>

Sets the custom JAAS principal that stores the group name.

auth <service_name> userprincipalclass <fully_qualified_classname>

Sets the custom JAAS principal that stores the user name.

auth <service_name> loginmoduleclass <fully_qualified_classname>

Sets the custom login class that implements JAAS Login module.

auth <service_name> pluginImplementationClass <fully_qualified_classname>

Sets the implementation class for the AuthPlugin interface.

auth <service_name> addparameter <param_name> <value>

Adds a custom parameter.

auth <service_name> removeparameter <param_name>

Removes the specified custom parameter.

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 "|"

(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

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

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

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

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.