Authentication and security

Authentication is configured at the Studio level for all sub-components including Knowledge Model Management. By default Studio comes pre-configured to use from-based “static list of users” authentication though this list of users is empty (so before anyone will be able to login this list of users will need to be updated). In normal every day use, you will want to configure the application so that users must login so that you can control model access using an authentication mechanism such as LDAP or Active Directory.

Configuring authentication

There are different levels or types of user authentication supported by Studio:

1. No authentication - No login is required and user is signed in as “Administrator” (a reserved account allowing full access).
2. formbased - User is required to login using a system provided login screen with authentication performed by the server itself
3. header - The header of the request to Knowledge Model Management will include authentication information (typically used in Single Sign On, or “SSO”, systems).
4. openid - Uses a custom JASPIC provider compatible with Tomcat to enable OAuth2 OpenID authentication and authorization using Okta or Azure OAuth2 services.

Which level is used is configured by modifying the <Studio Installation Directory>/webapps/ROOT/WEB-INF/web.xml file. The default configuration has both header and form-based authentication enabled. To completely disable authentication comment out or remove the configuration sections following the form authentication comment.

Mapping external roles to roles

There is an option to provide mapping between external roles and roles recognized by Studio and KMM. This mapping is configured in the /opt/semaphore/studio/conf/auth/auth-override.properties file.

For example, in order to map an external role “CustomerRole” to “SemaphoreSuperAdministrators”:

1. Ensure the Studio service is stopped.
2. Add the following entries to the auth-override.properties file:
   Copy

   roles.mapping.CustomerRole=SemaphoreSuperAdministrators
   
   

3. Restart the Studio service.

Setting a default role

It is possible to set a default role to users that are not part of any known group. To do this set the property

roles.default=SemaphoreAuthenticatedUsers

in the auth-override.properties file. (The default value is SemaphoreAuthenticatedUsers, you may want to change it.

User security

There are four levels of security for each user in Knowledge Model Management:

1. Access level security (roles) - Provides access to specific Knowledge Model Management functionality. This is defined using authentication “roles” assigned to the user.
2. Access level SPARQL Access - Provides access the SPARQL Editor and the SPARQL end-point generator.
3. Model/Task level - Provides levels of access to specific Knowledge Model Management models and model tasks. This is defined within Knowledge Model Management for each model and task.
4. Environment Permissions - Provides permission to publish, but note that a user is not automatically allowed to publish every model and task because of their environment permissions. Rather, with the environment permissions, they can be granted publishing permissions on a model-by-model basis by a model manager. Environment Permissions also grants access to update Classification Server rulenets using the “Rulenet Manager”

Access level security (roles)

The authentication mechanism, by default, should pass the following authentication roles (groups) through to Knowledge Model Management to provide the indicated access (these roles are case sensitive):

• SemaphoreUsers - Users assigned this role can log into Knowledge Model Management but access to specific models must be granted by model administrators. Users with only the “SemaphoreUsers” have these permissions:

  • Cannot create new models
  • Do not have SPARQL Access Permissions (unless explicitly granted)
  • Cannot grant SPARQL Access Permissions
  • Cannot view or access models or tasks they have not been granted permissions to and cannot create tasks unless given the proper Model Role permissions
  • Cannot perform model Backup and Restore
  • Cannot manage plugins
  • Cannot grant Environment Permissions

• SemaphoreAdministrators - have these permissions:

  • Can create new models
  • Do not have SPARQL Access Permissions (unless explicitly granted)
  • Cannot grant SPARQL Access Permissions
  • Cannot view or access models or tasks they have not been granted permissions to and cannot create tasks unless given the proper Model Role permissions
  • Cannot perform model Backup and Restore
  • Cannot manage plugins
  • Cannot grant Environment Permissions

• SemaphoreSparqlUsers - have these permissions:

  • Cannot create new models
  • Have SPARQL Access Permissions for every model/task where they have Contributor or higher Model Role permissions
  • Cannot grant SPARQL Access Permissions
  • Cannot view or access models or tasks they have not been granted permissions to and cannot create tasks unless given the proper Model Role permissions
  • Cannot perform model Backup and Restore
  • Cannot manage plugins
  • Cannot grant Environment Permissions

• SemaphoreSuperAdministrators - In the case of the SemaphoreSuperAdministrators, the user is granted the Model Role of Manager for every model in Semaphore, regardless of any lesser, or no, permissions granted on models or tasks. Additionally, SemaphoreSuperAdministrators::

  • Can access all models and all tasks with “manager” level permissions
  • Can create new models
  • Have SPARQL Access Permissions for every model/task
  • Can grant SPARQL Access Permissions
  • Can perform model Backup and Restore
  • Can manage plugins
  • Can grant Environment Permissions

• SemaphoreRoots - (Internal) Provides access to the “TBL” (Top Braid Live) section of the deployment (e.g. “/tbl/…” URLs). This is not typically used by customers as changes to the TBL layer of the deployment are rarely if ever required. The permissions for this role are strictly for that access, and do not include any other permissions such as those granted by the other roles.

• SemaphoreAuthenticatedUsers - Users are automatically assigned this role if they pass authentication including users with or without the core authentication roles.

Custom Access level security (roles)

It is possible to add additional external roles (groups) for use in Studio and Knowledge Model Management for provision of group-level security on models. This can be done as follows:

1. Update the “/opt/semaphore/studio/conf/auth/auth-override.properties” file to add the additional roles (groups) required
2. Uncomment the line starting with roles.builtin and add (append) the additional roles to the end of the “roles.builtin” parameter. For example, to add “CUSTOMROLE” you would update the file to contain the following (be sure the scroll to the right of the example if necessary):
   Copy

     roles.builtin=SemaphoreAdministrators,SemaphoreUsers,SemaphoreSparqlUsers,\
           SemaphoreRoots,SemaphoreSuperAdministrators,CUSTOMROLE
   

3. Restart Studio.
4. Update the “/var/opt/semaphore/kmm/data/workspace/com.smartlogic.workbench.auth/customized/auth-override.properties” file to add the additional roles (groups) required.
5. Uncomment the line starting with roles.builtin and add (append) the additional roles to the end of the “roles.builtin” parameter. For example, to add “CUSTOMROLE” you would update the file to contain the following (be sure the scroll to the right of the example if necessary):
   Copy

     roles.builtin=SemaphoreAdministrators,SemaphoreUsers,SemaphoreSparqlUsers,\
           SemaphoreRoots,SemaphoreSuperAdministrators,CUSTOMROLE
   

6. Restart KMM.
7. Log into Studio at least once with a user that has the CUSTOMROLE role.
8. Verify in a model in KMM that the CUSTOMROLE principal is visible as an option to add to a model.

Access level SPARQL Access

By default users will have SPARQL read access. This means that they will be able to use SPARQL to read data out of the model to which they have at least read access. They can do this using the built-in SPARQL editor or using the SPARQL endpoint.

In addition, they can be assigned SPARQL write access. This can be done either through giving them the role “SemaphoreAdministrators” or “SemaphoreSparqlUsers” or by a SemaphoreSuperAdministrator using the “Manage SPARQL access” option behind the Admin menu in Knowledge Model Management (the settings wrench).

SPARQL Access will also allow the user to publish a model or task.

Model/task level security

There are four levels (roles) of model security within Knowledge Model Management:

1. Manager
2. Editor
3. Contributor
4. Reviewer

Permissions for each role are described below.

Here is the detailed access level per role.

Manager

1. Models: Can create and delete models
2. Tasks: Can create and delete tasks
3. Tasks: Can commit tasks
4. Users: Can assign users and their permissions to models and tasks
5. Structure: Can add, edit, or delete model structure elements
6. Concepts: Can add, edit, or delete model concepts and concept schemes
7. Model Linking: Can manage model linking
8. Model Languages: Can add, edit, or delete model languages
9. SPARQL Editor: Has access to the SPARQL editor
10. Reporting: Has access to reporting
11. Import/Export: Can import and export models and tasks
12. Clear History: Can clear out the details of tasks that have been committed to master. The list of changes will remain, but not the triple level details - this can be used to free up server resources. If you wish to have this functionality disabled for all users, then in the file <<Installation>>/kmm/webapps/ROOT/ui/deploymentSetup.js set the value of the property enableClearHistoryDetails to false, then restart KMM.

Editor

1. Models: Cannot create or delete models
2. Tasks: Can create but not delete tasks
3. Tasks: Cannot commit tasks
4. Users: Cannot assign users to models. Cannot assign users to tasks not created by themselves. Can assign users to the tasks they created.
5. Structure: Can add, edit, or delete model structure elements
6. Concepts: Can add, edit, or delete model concepts and concept schemes
7. Model Linking: Cannot manage model linking
8. Model Languages: Cannot add, edit, or delete model languages
9. SPARQL Editor: Has access to the SPARQL editor
10. Reporting: Has access to reporting
11. Import/Export: Can import and export models and tasks

Contributor

1. Models: Cannot create or delete models
2. Tasks: Cannot create or delete tasks
3. Tasks: Cannot commit tasks
4. Users: Cannot assign users or their permissions to models and tasks
5. Structure: Cannot add, edit, or delete model structure elements
6. Concepts: Can add, edit, or delete model concepts and concept schemes
7. Model Linking: Cannot manage model linking
8. Model Languages: Cannot add, edit, or delete model languages
9. SPARQL Editor: Has access to the SPARQL editor
10. Reporting: Has access to reporting
11. Import/Export: Can import and export models and tasks

Reviewer

1. Models: Cannot create or delete models, but can view them
2. Tasks: Cannot create or delete tasks, but can view them
3. Tasks: Cannot commit tasks
4. Users: Cannot assign users or their permissions to models and tasks; cannot view assigned users
5. Structure: Cannot add, edit, or delete model structure elements, but can view them
6. Concepts: Cannot add, edit, or delete concepts or concept schemes, but can view them
7. Model Linking: Cannot manage model linking
8. Model Languages: Cannot add, edit, or delete model languages
9. SPARQL Editor: Cannot access the SPARQL editor
10. Reporting: Cannot access reporting
11. Import/Export: Cannot import and export models and tasks

Defining model level security

Model level security is defined using the “Edit Model Settings” screen in Knowledge Model Management, accessed as follows:

1. Login to Knowledge Model Management
2. Open the model you wish to change permissions for
3. In the “context” menu for the model, select the “Edit model settings” option
   

On the “Edit Model Settings” screen displayed user permissions are changed using the “Manager users” section.

Defining task level security

Similarly, task level security is defined using the “Edit Task Settings” screen in Knowledge Model Management, accessed as follows:

1. Login to Studio then go into Knowledge Model Management
2. Open the model associated with the task you wish to change permissions for
3. In the “context” menu for the relevant task, select the “Edit task settings” option
   

On the “Edit Task Settings” screen displayed user permissions are changed using the “Manager users” section.

Setting user or role-level permissions

Permissions are added by first (1) typing the username or user role (e.g. “SemaphoreUsers”) in the user entry box (auto-complete will show you a list of suggestions as you type) then (2) pressing the “Submit” button and finally (3) altering their access level (as per the above definitions) in the “Role” column.

Press the “Save” button to save these permissions which will be available immediately to the relevant users.

Deleting model history

It is possible to delete through the user interface the history associated with changes made to the model. If you do not want to have this facility (e.g. for audit purposes) then in the configuration file

<KMM Install>/webapps/ROOT/ui/deploymentSetup.js

set the parameter enableClearHistoryDetails to false.