Security Use Console
The OpenIoT Security and Privacy module comes with a management console for managing services, users, and permissions.
By default, it is assumed that the management console is deployed in a local JBoss instance and is accessible on http://localhost:8080/security.management/. If this is not the case in your setting, you must adapt the clients.callbackUrl property in the global security-config.ini file, in the section delimited by @BEGIN-security.management and @END-security.management.
Likewise, it is assumed that the OpenIoT CAS is deployed locally and is accessible on https://localhost:8443/openiot-cas. If this does not correspond to your setting, update casOauthClient.casOAuthUrl and clientsRealm.permissionsURL properties in security-config.ini.
Finally, it is recommended that you change the default secret that is used for openiot-security-manager-app.
The location of log file and other logging configuration, such as logging levels, can be modified in security-management/src/main/resources/logback.xml. By default the configured log file is $jboss-home/standalone/log/security-management.log.
For using the management console security-server module must be deployed. Instructions for deploying the security-server module are here. This web application is registered in OpenIoT CAS by the name of openiot-security-manager-app.
You can deploy the security console web application by running mvn jboss-as:deploy in security-management module. After successful deployment go to http://localhost:8080/security.management/ for using security module management console. Log in with username admin, and password secret. This user has all the necessary permissions to manage users and permissions for all registered services.
The management console provides the following functionality:
- Defining/managing permissions for registered services
- Defining/managing roles for registered services
- Assigning roles to users or revoking roles from users
- Adding/managing services
- Registering/managing users
Role is a container for one or more permissions. Permissions cannot be directly assigned to users. Instead, they must be assigned to a role. Then the role is granted to the users. Roles and permissions are defined per service. This means that for each service, we have to define its own set of permissions and roles. We use Apache Shiro's wildcard permission syntax to define the permissions. We briefly describe the syntax in the following. Please refer to the official documentation for detailed information about wildcard permissions.
A wildcard permission, in the simplest case, is a string permission like “register_service” or “use_app”. In this case, the developer checks whether or not the user has the exact permission specified by the permission string. The wildcard permission "*", which means all permissions, can be assigned to users. This special permission string represents all possible permission strings. Wildcard permissions can contain multiple levels. Each level is separated by a “:”. For example, the permission string “use_app:part_n” has two levels: “use_app” and “part_n”. The number of levels is unlimited and the semantic of levels is defined by the permission designer. The wildcard character can be used in any level. For example a user with permission “use_app:*” has any permission like “use_app:X”, where “X” can be any permission string. Last but not least, each level can contain multiple permissions. For example, assigning the permission “use_app:part1, part2” to a user is equivalent to assigning her “use_app:part1” and “use_app:part2” permissions.
In the “Manage services” section of the management console, users can view registered services, edit, or remove them. New web application services and rest services can also be defined in this section. The following shows an screenshot of the “Manage services” section.
Two types of services can be registered:
- Rest Service: a service which is accessing the OpenIoT CAS using the REST interface (e.g., SD&UM)
- Web Application Service: a service which is accessing the OpenIoT CAS through a browser (e.g., management console)
To add a new web application service, click on the "New Service" button and specify the following fields as shown in the figure below.
- In the Key field enter the clientId (or the service name) of the client.
- In the Secret field enter the secret of the client.
- In the URL field enter the callback URL of the client. For example, in case of management console service on localhost, we enter
http://localhost:8080/security.management/callback?client_name=CasOAuthWrapperClient. This URL consists of the application path and the mandatory/callback?client_name=CasOAuthWrapperClientpart. - In the Display name field enter the name of the service that is displayed to the user in the authorization confirmation page. For example, in case of management console the default display name is "Manager".
- Click the Submit bottom.
To add a new REST service, click on the "New REST Service" button and specify the following fields as shown in the figure below.
- In the Key field enter the clientId (or the service name) of the client.
- In the Secret field enter the secret of the client.
- Click the Submit bottom.
A user who has the admin:add_services permission can register new services. Users can also view/edit/delete the services that they have registered.
When a new service is created, some predefined permissions and roles are created for that service. The predefined permissions include the permissions described in the table below and the following permissions:
- admin:*:SERVICE_NAME permission that includes all the individual permissions described in the table below.
- admin:service_mgmt:SERVICE_NAME permission required for viewing/editing/deleting the service SERVICE_NAME
The following roles are created for the service when the service is registered:
- user_mgmt_all:SERVICE_NAME has the permission admin:*:SERVICE_NAME.
- admin:service_mgmt:SERVICE_NAME has the permission admin:service_mgmt:SERVICE_NAME
If the user is not the admin user, who has the all permissions (e.g. the permission *), these roles are assigned to the user.
In the “Manage permissions” section of the management console application, users can manage permissions for registered services. In the first step, the user must select a service to manage its permissions as shown in the figure below.
After selecting the service, the list of permissions defined for the service is shown. By selecting a permission, the list of roles that contain the selected permission is populated. In addition, the list of users who have the selected permission is updated. The selected permission can be deleted given that the user has the permission “admin:delete_permission:openiot-security-manager-app”. The following figure shows a snapshot of the application, when the “lsm-server” service is selected for managing its permissions.
Users can define new permissions for the selected service, provided that they have the permission “admin:create_permission:openiot-security-manager-app”. As shown in the following figure, a new permission is defined by its name. The description of the permission helps to document the purpose of the permission.
In the “Manage roles” section of the management console application, users can manage roles for registered services. In the first step, the user must select a service to manage its roles. As shown in the following figure, after selecting a service, its defined roles are shown. By selection a role, the permissions assigned to it are displayed in the right pane. The list of users who are granted the selected role is also shown. In this page, new permissions can be assigned to the selected role; the role can be granted to more users; the role can be revoked from users; and permissions can be revoked from the role. The selected role can be deleted given that the user has the permission “admin:delete_role:openiot-security-manager- app”.
Users can define new roles for the selected service, provided that they have the permission “admin:create_role:openiot-security-manager-app”. A new role is defined by its name. The description of the permission helps to document the purpose of the permission.
In the “Manage users” section of the management console application, users can see the registered users and their granted roles for registered services. As shown in the following figure, after selecting a user and a service, her granted roles are shown. By selection a role, the permissions assigned to it are displayed in the right pane. New roles can be granted to the selected user and roles can be revoked from the selected user. The selected user can be deleted given that the logged in user has the permission “admin:delete_user”.
A new user can sign up using the management console application as shown in the figure below. If the security.automaticServiceSetup property is set to true in the openiot.properties file, then the user can enter a Service URL Prefix so that the required services are generated for his/her standard OpenIoT web application modules which are deployed locally. The list of these modules must be defined in the openiot.properties file using the property security.demoWebappServices. The format is like [webapp1 name, key1, secret1, display name][webapp2 name, key2, secret2, display name]...
If the property security.signup.useCaptcha is set to true, a captcha field is added to the signup form.
If the property security.automaticServiceSetup is set to true, users can see the list of the services that are configured for demo usage in the Guest services section. The property security.demoServices indicates the services that are accessible as demo services separated by a comma. For REST services the service key should be put in this comma separated list, otherwise the name of the webapp must be placed in the list.
For using the security-management application, users need to have a permission called admin:user_mgmt_general. This means that without this permission the user doesn't have access to the functionality of the security management application. The list of other service-specific permissions is provided in the table below.
| Name | Description |
|---|---|
| admin:delete_role:SERVICE_NAME | Permission for deleting roles for service 'SERVICE_NAME' |
| admin:create_role:SERVICE_NAME | Permission for creating new roles for service 'SERVICE_NAME' |
| admin:grant_role:SERVICE_NAME | Permission for granting/revoking roles to users for service 'SERVICE_NAME' |
| admin:create_permission:SERVICE_NAME | Permission for creating new permissions for service 'SERVICE_NAME' |
| admin:delete_permission:SERVICE_NAME | Permission for deleting permissions for service 'SERVICE_NAME' |
| admin:user_mgmt:SERVICE_NAME | User management permission for service 'SERVICE_NAME' |
For example, if you want to grant all permissions to user openiotuser to manage roles and permissions for service openiot-security-manager-app, you can create a role user-manager in service openiot-security-manager-app and add the above permissions to this role. Then assign this role to openiotuser. Note that SERVICE_NAME in the above permissions must be replaced by openiot-security-manager-app.