Designing client applications to use IBM BPM on Cloud and IBM BPM APIs
Client applications must be authenticated
to access the IBM® BPM
on Cloud APIs. IBM BPM
on Cloud uses
basic authentication to grant access to incoming API calls from client
applications, such as administrative clients for user provisioning
or process instance cleanup.
Before you begin:
- Your client application requires service credentials (functional ID and password) to authenticate with the IBM BPM on Cloud APIs. Your IBM BPM on Cloud account administrator is responsible for giving you access to the service credentials in your client application environment.
- Your company's password renewal policy determines how often the account administrator replaces service credentials. To ensure that applications can still access IBM BPM on Cloud after new service credentials are introduced, both old and new credentials remain valid for a time. Client execution time influences the length of the overlap period. For example, if your client regularly reads in the service credentials from the environment, the time between each read should be shorter than the overlap period. Conversely, if the client reads in the credentials at server start up only, the overlap period should be longer than the client execution time. Work with the account administrator to determine a value for the overlap period that is suitable for your client application design.
When you design
a client application for IBM BPM
on Cloud,
consider the following good practices:
- Read in service credentials.
- Do not hardcode service credentials in your application. Instead, read them in, for example, from a configuration file or credential vault, and then use them to construct the basic authentication header for the HTTP calls that the application sends to the IBM BPM on Cloud APIs. Because your account administrator might change service credentials over time, ensure that the application refreshes them appropriately according to the password renewal policy and overlap period that apply to your application environment.
- Detect rejected access to IBM BPM on Cloud because of missing or invalid login credentials.
- Client application access to IBM BPM
on Cloud is
rejected when the functional ID, the password, or both are invalid.
In addition, if an application tries repeatedly to log in to IBM BPM
on Cloud with
an incorrect password, the system might lock the account.To detect rejected access, add a check in your application for the HTTP status code 302, which IBM BPM on Cloud issues to redirect to the login page, and issue an error message. If you think that the account is locked, wait for the lockout time to expire (currently one hour), and restart the application. If you think that access is rejected because of an incorrect functional ID, password, or both, check with your administrator that the service credentials you are using are valid.Important: If your application uses an HTTP client application library, ensure that the library is not configured to automatically follow page redirects.
- Detect a rejected API request due to missing authorization for the call.
- Your client application can contain both IBM BPM
on Cloud and IBM BPM API requests.
Each request type requires its own authorization:
- For IBM BPM on Cloud API requests, the service account must be authorized for the IBM BPM on Cloud operating environments where the application runs. The service account might also need the administrator or operator role. Check with your account administrator what permissions the service account has.
- For IBM BPM API requests, the service account might need IBM BPM permissions too. If your API request requires tw_admins, tw_authors, debug, or twem privileges, check with your IBM BPM on Cloud account administrator that the service account has the privileges you need. For more fine-grained IBM BPM authorization, such as authorization for task assignments, check with your IBM BPM administrator what authorization is required, and use the corresponding API calls in your application. For more information about these calls, see Authorization control for runtime REST API calls.