In order to grant access to a Business Automation Workflow on Cloud (BAWoC) tenant, the BAWoC concept offers two built-in authentication mechanisms. For browser access, a login UI is provided allowing a user to type in a user id and password. For programmatic client access, user authentication is enabled via a Basic Authentication header to be included into client REST calls targeting tenant APIs. In both cases, authentication is based on the transmission of the user id and the associated password and its subsequent evaluation within BAWoC.

As an alternative for browser access, BAWoC allows to request the configuration of a custom SAML Identity Provider (IDP) for your user population. The actual authentication is then performed via a IDP UI (often located on the customer premise) where a user id and password are requested.  In case of successful authentication, the IDP confirms the user identity towards BAWoC, where a login session is instantiated for subsequent tenant API calls. For SAML IDP based authentication, no credentials like user passwords are needed and stored in BAWoC.

Sometimes, you have to develop and use client applications which include their specific login UIs and mechanisms which exist independent of  BAWoC. In order for such an application to meaningfully interact with BAWoC, the context of the logged in user also needs to be established in BAWoC, i.e. the user has to be authenticated there, too. Doing this is not possible, if client application and BAWoC use completely independent login concepts.

This is especially the case, when user authentication to BAWoC is delegated to a SAML IDP implying that no user credentials are available in BAWoC. As a result, programmatic access using passwords is not possible. As a SAML  IDP serves browser based scenarios, client applications cannot make use of it either. In such a case, a client application needs another type of user authentication support towards BAWoC.

The basic concept applied here is that of identity propagation. Put simply, it creates secure circumstances under which a client can inform a server about a user context in which a call is to be executed such that the server can trust a received user identity.

The SAML concept incorporates this for its browser oriented scenario, in that, after authenticating the user via an IDP, the user identity is relayed to the server side via trusted SAML messages. Such messages require a configured trust relationship between the SAML IDP and BAWoC which includes an a-priori exchange of encryption keys for securing exchanged messages.

In this contribution we describe an approach for identity propagation which, unlike SAML, can be used by programmatic clients when interacting with BAWoC. It is based on the specification for "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants", as introduced in [https://datatracker.ietf.org/doc/html/rfc7523].

As implied by its name, using the JWT profile is linked to the communication pattern used by OAuth clients which follows distinct communication phases:

1. a first phase to authenticate the client wishing to communicate with a server, here BAWoC. As a result of this phase, a pair of oauth tokens gets generated: an access_token and a refresh_token.

2. a phase of performing communication by including the access_token as an Authorization header of type Bearer into every http request. As long as the token is valid, the requests are treated by BAWoC as being authenticated.

3. a phase of either terminating the communication by letting the token expire or explicitly invalidating it. As an alternative, the received refresh_token can be employed to request a new access_token to enter phase 2. anew.

Handling phases 2. and 3. corresponds to OAuth definitions as documented in e.g. [https://tools.ietf.org/html/rfc6749]. A BAWoC related description can be found in [https://www.ibm.com/docs/en/dbaoc?topic=applications-using-oauth-20-based-authentication] where described steps 2, 3, 4 detail the use of an access_token, how to refresh the token and how to revoke the tokens respectively.

Identity propagation making use of the “JWT profile for OAuth 2.0 client authentication” covers phase 1. from above. For using it with BAWoC, it amounts to performing a request of the type:

resulting in the mentioned pair of OAuth tokens, e.g.:

Note the grant_type used in the request directing BAWoC to use the received assertion value to extract the user identity and perform the identity assertion (i.e. user authentication) on its side.
The assertion value itself is to be constructed by the client in accordance to [https://datatracker.ietf.org/doc/html/rfc7519], along with some easy to follow rules in the context of BAWoC.

The token consists of three Base64 encoded values, one for a Header part, another one for a Payload part and the third one carrying the signature ensuring that no tampering with the token content is possible. BAWoC mandates the use of these attributes in the token:

Header:
 {
   "alg": "HS256",                             // algorithm to compute the token signature
   "typ": "JWT"                                  // fixed value
}

Payload:
{
  "iss": "myissuer",                                          // currently not checked
   "sub": "myid@mycomp.com",                     // the user to be asserted
   "exp": 1686317070,                                    // expiry (secs since 1970, checked)
   "iat": 1686313470,                                      // issued at (currently not checked)
   "nbf": 1683125729                                     // not before (secs since 1970, checked)

}

Signature: computed using the specified algorithm and a pre-agreed key to be used for validating the signature on the BAWoC side.

Similar to SAML, a trust relationship has to be established between client and server in order to trust exchanged assertions. For BAWoC, this has to be done by contacting the BAWoC support team and requesting access to a specific tenant and agreeing on one of the options available for signature validation.

The support team provisions the tenant access for using JWT tokens, including  a client_id and client_secret.

For signature validation, you have the choice between applying a symmetric encryption algorithm to compute the validation part or an asymmetric approach based on a public key provided by the customer. For the former case, customer and support team have to agree on one of the supported encryption algorithms (e.g. HS256) and the symmetric encryption key.

For the latter case, an encryption algorithm has to be agreed on (e.g. RS256) and the customer has to make available his public key which can be used for signature validation. As an alternative, the public key can be made available via a customer API referred to as "Signing JWKS uri".

Usually, the client credentials will be constrained to accessing the tenant which is indicated to the support team during the initial request. Correspondingly, the user specified in a JWT has to exist in BAWoC in the context of the indicated tenant, otherwise the identity assertion will fail.

Note that access control within the BAWoC tenant is applied as defined using tenant administration tools. The JWT token does not affect such access control decisions.

The described approach provides an easy-to-use way for programmatic clients to assert user identities in BAWoC without having to provide user specific credentials (e.g. passwords). This implies that the actual user authentication responsibility lies with the programmatic client acting on behalf of the tenant customer. BAWoC will assert an identity as requested, without having the chance to countercheck a user specific credential on its side.