Security & Authorization¶
omlox™ hub uses the OpenID standard to secure access to the API. This document describes how to apply permission settings to individual API endpoints and OpenID users, and provides an example OpenID setup using Keycloak as OpenID server. Though any standard OpenID server can be used. Also refer to the Server Configuration readme for OpenID configuration options.
In order to enable authorization features permissions, OpenID and server configurations need to be configured accordingly. The following gives a quick overview about files and configuration options which need to be configured to enable authorization and security features:
require_authorization must be set to true
openid_client_name must be set to verify audiences. This is mandatory by OpenID, see also the audience claim setup example below.
openid_config_url must be set to the standard OpenID configuration endpoint, e.g. openid_config_url: http://127.0.0.1:8080/auth/realms/omlox/.well-known/openid-configuration
verify_authserver set to true when running the server in production mode (requires authserver_public_key_path).
authserver_public_key_path should point to the public key of the OpenID server when running in production mode
force_https should be set to true in production mode to disable any insecure plain http or websocket communication
Authorization to the API is controlled in this file (explained in the next section).
When running the server in production mode, appropriate settings such as server certificates, configure host, public_key_path, private_key_path and dh_params_path must be set. Please refer to the Server Configuration readme.
Authorization Flow Type¶
omlox™ hub uses Bearer Authorization for the REST API. Clients connecting to the hub will never send passwords directly to the hub. Instead clients login to the OpenID server and provide the bearer token with each request header to the Hub. The hub is able to securely verify the token is valid and was issued by the configured OpenID server.
For service-to-service and client-to-service communication we advise to use bearer authorization. For web clients we advise to use Authorization Code Flow for secure login. An Angular web client example is located in the examples/angular-oidc-sample-code-flow folder.
Applying individual API Permissions¶
omlox™ hub server uses an RBAC (Role Based Access Control) model to assign permissions to OpenID roles. The permissions are stored in a YAML based file in the data directory of the Docker container. The permissions are loaded once at startup.
General structure of the permissions file:
role-name: description: Some role description '/api/path': - PERMISSION - PERMISSION '/api/path_2' ...
Description of the core elements:
“role-name” must match an actual OpenID role name provided as part of the JWT Access Token.
“/api/path” must match an actual omlox™ API endpoint (refer to the swagger file for a list of available endpoints). It’s possible to use * as a wildcard to give permissions to all subpaths of an API, e.g. “/api/*” will match all subpaths like “/api/path1”, “/api/path2” etc.
“Permission” can be any of the following (multiple entries possible): CREATE_ANY, READ_ANY. UPDATE_ANY, DELETE_ANY, CREATE_OWN, READ_OWN, UPDATE_OWN, DELETE_OWN.
The role is allowed to create (e.g. via POST request) a resource at the given API path.
The role is allowed to read all resource objects at a given API path.
The role is allowed to update (e.g. via PUT request) resources at given API path.
The role is allowed to delete all resources for a given API path.
CREATE_OWN, READ_OWN, UPDATE_OWN, DELETE_OWN¶
The role is only allowed to read or mutate it’s own resources. Resource ownership is defined via JWT AccessToken. A particular user which owns a resource must have a matching resource UUID in an “owns” array of the Access Token. refer to the example below to learn about basic OpenID configuration and ownership management.
In the example below a role named omlox™-api-role is provided full admin access to all API endpoints using a wildcard match:
omlox-api-role: description: Super user with all permissions '/v1/*': - CREATE_ANY - READ_ANY - UPDATE_ANY - DELETE_ANY
Example OpenID setup with Keycloak¶
An OpenID server is required in order to enable authorization features in omlox™ hub. Below is an example using Keycloak, though the basic setup should work similar for other OpenID servers.
Prerequisites: A running Keycloak instance. See the guide at  to get started. You can start with a simple standalone instance for development and testing.
At first we have to create an omlox™ realm:
Go to http://localhost:8080/auth/admin/ and log in to the Keycloak Admin Console using the account.
From the Master drop-down menu, click Add Realm.
Type omlox™ in the Name field and click Create.
Next we create the role omlox™-api-role for Hub API access. To do so:
From the menu, click Roles to open the roles list.
Click on Add Role on the right side of the list
Enter omlox™-api-role in the Role Name field. The role name must not be changed, because this role name is mapped to omlox™ permissions.
Next we create a user named omlox™-api-user. To create a new user in the omlox™ realm, complete the following steps:
Make sure the omlox™ Realm is the selected current Realm in the Master drop-down menu
From the menu, click Users to open the user list page.
On the right side of the user list, click Add User to open the add user page.
Enter the name omlox™-api-user in the Username field. Flip the Email Verified switch from Off to On and click Save to save the data and open the management page for the new user.
Click the Credentials tab and enter a password for the new user. Flip the Temporary switch to Off to make the new password permanent. Click Set Password to save the changes.
Click the Role Mappings tab. In the Realm Roles list, select omlox™-api-role and click the Add selected button.
Next we create a client named omlox™-api-client. To create a new user in the omlox™ realm, complete the following steps:
Make sure the omlox™ Realm is the selected current Realm in the Master drop-down menu
From the menu, click Clients to open the client list page.
On the right side of the client list, click Create to open the create client page.
Enter the name omlox™-api-client in the Client ID field. Select openid-connect in the Client Protocol dropdown.
Select Public as Access Type
Toggle Service Accounts Enabled. This enables Client Credentials Grant workflow for the Hub to fetch access tokens for token verification of client requests.
Next, create another client to be used by the hub service itself. Note: This client is mandatory even in case no other OpenID exists to communicate with the hub, and the client name must match with the openid_client_name in the hub config. All other OpenID clients which communicate with the hub have to include this client in the JWT as audience, so that the hub can verify audiences as mandated by OpenID.
Repeat the previous step to create a client.
Name deephub-service. Note: The name is case-sensitive and must match the one in the configuration file.
Set the Access Type to bearer-only.
For security reasons an OpenID enabled service has to verify audience claims in order to avoid token misuse. Follow these steps:
From the meu, click Client Scopes to open the client scopes list.
Click Create to create a new client scope.
Enter hub-service into the Name field.
Click the Save button to create the new client scope.
In the list of client scopes, select the newly created hub-service.
Select Mappers from the top menu.
Click the Create button on the right side.
Enter hub-service-audience into the Name field.
From the Mapper Type selection choose Audience.
In the Included Client Audience select deephub-service.
Click Save button to save the changes.
Now we create a mapping between the newly created scope and the client used for user logins. From the left menu panel, choose Clients and choose omlox™-api-client.
From either the Default Client Scopes or Optional Client Scopes list select hub-service and click on Add selected. You can only add it to either default or optional. The difference is that when you add it to the default list the token will always contain the audience hub-service. When you set it to optional the user client (e.g. web application) must explicitely set the scope to hub-service when requesting the token, the token will then contain the audience deephub-service. It’s advised to use the optional mapper and limit scopes appropriately on the user client side.
Optional steps It’s possible to define fine-grained ownership permissions by adding custom attributes to a user. This allows for assigning read_own permissions to API paths which are restricted to users that own a particular ressource. Follow these steps:
From the left menu, click Clients.
From the clients list, select omlox™-api-client. From the top menu select Mappers.
Click on the Create button to create a new mapper.
Set a name like User Trackable Mapper.
In the Mapper Type selection, select User Attribute.
In the User Attribute field, set owns.trackable1. Important: This field must match with the one we set in the User attributes for the particular user.
In the Token Claim Name field, set „owns“ (without quotes). It’s important to use this exact name, as the omlox™ hub will look for its owns property and checks if a user has access to particular resources. This is done by UUIds provided as part of the user attributes.
From the Claim JSON Type selection, select String.
Now we can create actual user attributes which will then be mapped at runtime. To assign a trackable to a user, follow these steps:
In the left menu bar, click Users
Choose a user from the list to whom you want to assign a trackable
In the attributes key / value list, set key to owns.trackable1 and the value to the ID of the trackable you want to assign to the user (e.g. 5896823C-3B3F-48BB-B74B-E43041ABD59C).