You are viewing the RapidMiner Deployment documentation for version 9.9 - Check here for latest version
Securing Web Services
Introduction
Securing REST endpoints is an important security aspect of any platform, especially ones that are accessible from the public Internet.
In the RapidMiner platform deployment, REST endpoints can be used for many things from managing executions and schedules to running RapidMiner processes exposed as web services. For backwards compatibility reasons we support enabling HTTP Basic authentication (i.e. sending the username and password unencrypted when calling a REST endpoint), but the recommended authentication scheme is the HTTP Bearer authentication (using an access token). If you migrate from an older version and already have web services embedded where you cannot easily change the used authentication scheme, follow our upgrade and migration guide on how to enable legacy basic authentication.
The components in the RapidMiner Platform deployment use a standard OAuth2/OpenID Connect scheme for authentication and authorization. In this scheme, after an interactive authentication (e.g. by providing a username and password), an access token and a refresh token is generated. Access tokens are usually short living, and when it expires, you can get a new one from our identity provider component by using the refresh token. You can read more about this topic in our security overview.
In case of machine-to-machine communication, such as when a web service provided by RapidMiner Server is called from another application, interactive user authentication is not possible. However, as stated above, even though we provide a legacy basic authentication for backwards compatibility reasons, the best thing to do from a security standpoint is to implement a token based authentication scheme between these systems.
Our KeyCloak component uses the concept of offline access tokens to solve this problem. Offline access tokens have their own expiry settings, and they are much longer living than regular access tokens. On this page we will guide you through the steps needed to generate the tokens needed to embed web services in your applications using token based authentication.
User separation
Access tokens allow the bearer of the token to do anything and everything that the token's "owner" is authorized to do. This is why access tokens are short living, to minimize the potential impact a malicious actor can achieve if getting their hands on this token.
Offline access tokens are longer living, increasing the above risk. This is why we recommend to create separate users in the platform whose sole purpose will be to provide access to the required web service endpoints. These users will only have access to what's needed to use web services, and they will have the offline_access role. This is the role that allows the user to instruct KeyCloak to issue tokens for offline access.
In our deployment templates, we pre-provisioned a user named webservice-user which has the needed authentication and authorization configuration. You can use this user as a template when provisioning new users in the platform for this purpose.
The webservice-user doesn’t have a password provisioned. To use it, you first have to set a password for it. Read more on the managing users, groups and roles page.
Getting tokens and embedding them into client applications
First, as stated above, you should create a user in the platform that represents the consumer of the web service.
To ensure that the user becomes available in all backend components, log in with the newly created user, and click on Executions and schedules on the landing page.
Next, point your browser to https://your-platform-deployment/get-token/ to open up the Token Generator. You will see a newly generated refresh token and some examples on how to exchange it for an access token and then how to use that inside a HTTP REST endpoint call to conduct a successful Bearer authentication.
To make sure that everything works, double-check that the user which represents the web service consumer has access to the RapidMiner process that implements the web service in question.
Fine-tuning token expiration
As stated above, offline tokens are longer living than regular access tokens, so they can comfortably be used for machine-to-machine communication. As such, their expiration is controlled by separate configuration parameters in Identity and Security.
In our default configuration, offline tokens expire after 1 month of inactivity, and after 1 year overall, regardless of usage. This means that you will have to use the token at least once a month, and generate a new token and embed it into your clients once a year, using th procedure described above.
The above parameters can be adjusted by logging in to Identity and Security, and on the Realm Settings page clicking the Tokens tab. The Offline Session Idle and Offline Session Max parameters control the above expiration times. If you want, you can set your offline tokens to never expire, by setting Offline Session Max Limited to Off.