Using service credentials to authenticate client applications

Client applications can use basic authentication to access the cloud environment. For this type of authentication, client applications use service credentials to authenticate their access.

Before you begin:
  • Your client application requires service credentials (functional ID and password) to authenticate with the cloud operations APIs and APIs provided by the capabilities, for example, the Business Automation Workflow APIs. Your account administrator is responsible for giving you the service credentials you need for your client application.
  • Your company's password renewal policy determines how often the account administrator changes service account passwords. To ensure that applications can still access the cloud environment after new service credentials are introduced, consider applying a credentials rollover scheme to ensure that both old and new credentials remain valid for a time. In such a scheme, client execution time influences the length of the overlap period. For example, if your client regularly reads in the service credentials from the cloud 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.
For more information about service credentials, see Creating and managing service accounts.
Consider the following good practices for authenticating your client application:
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 Authorization header for basic authentication of the API calls.
Important: When client applications interact with IBM® Cloud Pak for Business Automation as a Service, they might receive a set of cookies. To avoid response-time degradation, include valid cookies in subsequent calls in addition to the Authorization header for basic authentication.
Detect rejected access to the cloud subscription because of missing or invalid login credentials.
Client application access to the cloud subscription is rejected when the functional ID, the password, or both are invalid. In addition, if an application tries repeatedly to log in to the subscription 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 Cloud Pak for Business Automation as a Serviceissues to redirect to the login page, and send an error message. If you think the account is locked, wait for the lockout time to expire, then retry the client application access to the cloud subscription. If you think that access is rejected because of an incorrect functional ID, password, or both, check with your account 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 cloud operations API calls and IBM Cloud Pak for Business Automation as a ServiceAPI calls. Each API type requires its own authorization:
Cloud operations API calls
The service account used by the client must be authorized for the cloud environments where the application runs. The service account might also need the Account Administrator or Operator role. Check with your account administrator what permissions the service account has.
IBM Cloud Pak for Business Automation as a Service API calls
The service account might need capability specific group permissions. If your API request requires IBM Cloud Pak for Business Automation as a Servicerole privileges, check with your account administrator that the service account has the role you need. E.g. for more fine-grained workflow authorization, such as authorization for task assignments, check with your workflow 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.
For both types of requests, add a check to your client code for the HTTP status code 401 Unauthorized.
Share service credentials across subscriptions.
If you have more than one IBM Cloud Pak for Business Automation as a Service subscription, client applications can share service credentials across subscriptions. To share service credentials, use the service credentials and import token operations provided by the Credentials API. All API calls require the caller to have the Account Administrator role. For more information, see the IBM Cloud Pak for Business Automation as a Service instance services APIs in the Cloud operations API reference.
  1. On one of your subscriptions, create a set of service credentials by using either the Access Management page in the cloud portal or the Credentials API.
  2. On the same subscription, use the API to create a service credential import token to authorize the import of service credentials into other subscriptions.
  3. On your other subscriptions, make the service credentials available to client applications on these subscriptions by using the API to import the credentials into each subscription.
  4. On your other subscriptions, assign the roles and permissions the service credentials need for the client application scenarios by using the Access Management page.
If a set of service credentials no longer needs access to a subscription, you can delete them from the subscription by using either the Access Management page or the Credentials API.