Skip to main content

Using OAuth 2.0 in a Service Model

Target audience: Developers & Modelers & Administrators

Introduction​

Service models are a convenient way to call external systems (most commonly a REST API) from your business apps without writing custom Java code. Many of these external systems are protected with OAuth 2.0 and expect an Authorization: Bearer <access token> header on every request, where the access token is obtained through the OAuth 2.0 client credentials flow.

This how-to shows how to authenticate a REST service in a Service Model using such an OAuth 2.0 client. It assumes you already have a Service Model with a REST service and focuses on the authentication part. If you are new to service models, start with the Service Registry introduction.

There are two steps involved:

  1. Register an OAuth 2.0 client that knows how to get access tokens for the external system.
  2. Reference that client from the REST service in your Service Model.
tip

Flowable uses Spring Security OAuth under the hood. Once an OAuth 2.0 client is registered, Flowable takes care of requesting access tokens, caching them and refreshing them when they expire. You never have to embed a static token in your model.

Step 1: Register an OAuth 2.0 client​

Before a Service Model can use OAuth 2.0, an OAuth 2.0 client registration must exist for the external system. A registration is identified by a registration key (also called a client registration id), which you will reference from the model in Step 2. There are two ways to register a client, and each one is paired with a way of referencing it in Step 2.

Option A: Configure the client in Flowable Control​

An administrator can register the OAuth 2.0 client at runtime in the OAuth Clients section of Flowable Control (or Flowable Hub in the cloud). This requires no changes to properties files and no restart, which makes it the most convenient option.

Provide a Registration key, the Client id and Client secret, and the Token uri (or Issuer uri) and Scopes of the external system. See OAuth Clients for the details of this screen.

A client registered this way is referenced from the Service Model by its Registration key using the OAuth2 client token type, described in Step 2, Option 1.

Option B: Configure the client in application.properties​

Alternatively, add a Spring Security OAuth 2.0 client registration to the application.properties of Flowable Work (or Flowable Design when modeling and testing there). The part after registration. / provider. (here myService) is the registration key and can be chosen freely, as long as it is used consistently:

# Credentials of the OAuth 2.0 client as registered with the identity provider
spring.security.oauth2.client.registration.myService.client-id=<your client id>
spring.security.oauth2.client.registration.myService.client-secret=<your client secret>

# Service-to-service communication uses the client_credentials flow (no interactive login)
spring.security.oauth2.client.registration.myService.authorization-grant-type=client_credentials

# Optionally restrict the requested scopes
spring.security.oauth2.client.registration.myService.scope=<scope1>,<scope2>

# Endpoint that hands out the access tokens
spring.security.oauth2.client.provider.myService.token-uri=https://identity.example.com/oauth2/token
note

Depending on the identity provider you can use issuer-uri instead of token-uri, in which case the token endpoint is discovered automatically. This is the same configuration style used for the Salesforce connection.

A client registered this way is referenced from the Service Model with a flwAuthTokenUtils expression, described in Step 2, Option 2.

Step 2: Reference the OAuth 2.0 client from the REST service​

With a registration in place, open your REST service in Flowable Design and go to the REST Settings tab. Flowable offers two ways to use the registration.

Option 1: Use the OAuth2 client token type​

Use this option together with an OAuth client registered in Flowable Control (Step 1, Option A). It is the simplest option and requires no expression. In the REST Settings tab:

  • Set Authorization to Bearer.
  • Set Token type to OAuth2 client.
  • Set the OAuth2 Registration Key to the Registration key you defined in Flowable Control.

REST service using the OAuth2 client token type

At runtime Flowable resolves an access token for that registration through the client credentials flow and adds it as a Bearer token to every request of the service. The token is cached and refreshed automatically.

note

The authorization can be configured on the service definition (applies to all operations) or overridden per operation. The same OAuth2 client token type is also available for other service types, such as MCP services.

Option 2: Use flwAuthTokenUtils in a Bearer expression​

Use this option for a client configured in application.properties (Step 1, Option B). Set Token type to Expression and resolve the token with the flwAuthTokenUtils helper:

${flwAuthTokenUtils.getAccessToken('myService')}

The argument is the registration key from Step 1 (myService in the example above). flwAuthTokenUtils.getAccessToken(...) returns a valid access token for that OAuth 2.0 client, requesting and refreshing it as needed. This is the same mechanism used when connecting to Salesforce.

Conclusion​

Authenticating a Service Model against an OAuth 2.0 protected API comes down to two things: registering an OAuth 2.0 client and pointing the REST service at that registration. For a no-code setup, register the client in Flowable Control and reference it with the OAuth2 client token type. If you prefer to keep the client in application.properties, reference it with a flwAuthTokenUtils expression instead. In both cases the credentials stay outside of the model and Flowable manages the token lifecycle for you.