Share this post:
Updated runtime APIs for IBM Cloud App ID
IBM Cloud App ID is based on a set of well-known industry standard protocols and specifications. For us at IBM, it is important to be compliant in those standards because they provide people and organizations with a basis for mutual understanding, security felicitation, and interpretability. As part of our efforts to further the standards, we’ve made a few changes. By making those changes we are able to tighten interoperability within the OIDC workflow and broaden the frameworks that are able to use App ID, such as Spring 5 Security.
New to the service? By integrating IBM Cloud App ID into your apps, you can easily add authentication and authorization to secure your applications and protected resources; even when you don’t have a lot of security experience.
Don’t have time to read the whole blog at the moment? No problem – here’s what you need to know now.
- The changes affect only the runtime APIs. The Management and Profiles APIs remain unchanged.
- You must migrate to v4 no later than the end of November 2019.
- To migrate, point to the v4 APIs and update your SDKs to version 6.0. No changes to your code required!
- If you create new bindings, be sure to use the latest SDKs. (It’s a best practice anyway!)
- By default, all new instances of App ID use the new version of the API.
In this blog post, we will describe the updates and guide you through the few changes that current users need to make to their apps. The changes can be made at your earliest convenience but must be completed no later than the end of November 2019.
Note: The Management and Profiles APIs remain unchanged.
In this update to the App ID service, we’re offering the following:
- Updating our runtime API version and SDKs
- Continuing the journey to the new “cloud.ibm.com” branding and domain
- Adding the discovery endpoint to service credentials
- Updating our tokens to reflect the changes made to the APIs:
- The issuer is now a full URL with a protocol and points to your specific App ID instance in the “cloud.ibm.com” domain.
- The audience field is now formatted as an array.
- Tokens now have a version. This can be found in the header of the tokens in the
- The gender field has been removed from the identity token. If the field is needed for your apps, you can add it to your token through custom claims mapping.
OAuth client field has been removed from the access token.
How does that affect me?
To pick up the updates, you just need to complete a few simple steps. First, you’ll need to invoke version 4 of the APIs and then ensure that your app is consuming the changes. For more detailed instructions, you can either check out the video below to see the changes in real time or you can follow the step-by-step instructions below.
Want to see the changes in real time?
Check out the following video to see all of the required changes in less than two minutes! In the video, we use application credentials but you can follow similar steps if you’re using service credentials. The video also shows how to update your SDK version.
I’m using an SDK, what do I need to do?
If you have a mobile application, the version of the API is hardcoded into the service SDKs. To make the update, change your SDK version to 6.0 and you’re good to go.
If you’re using an SDK with a web application, there are a few more steps, but it’s still a very simple change. To pick up the updates, you just need to make sure of the following steps:
- You are invoking version 4 of the runtime APIs, as shown in: https://cloud.ibm.com/apidocs/app-id/oauth.
- Your application can use the new APIs.
Step 1: Invoke version 4 APIs
To ensure that you’re invoking the latest APIs, you can either update your existing credentials or create new ones. If you’re currently using Service Credentials, you might take this opportunity to update to application credentials, which are App ID’s preferred credentials.
Updating existing credentials
To keep your client ID and secret, update your credentials within your app so that your
discoveryEndpoint fields now point to v4 instead of v3.
For example, the following image should look similar to your credentials after you update. You should note that the credentials now use the IBM Cloud domain. You might also take this opportunity to update your app to use the new domain name.
App ID application credentials – v4
Generating new credentials
Generate new credentials by using the App ID dashboard. New credentials contain the new endpoints as well as a new client ID and secret.
Do you have a web application that’s bound to IBM Cloud? You must create new credentials as your old service credentials are part of the platform and cannot be updated.
Step 2: Consume version 4 APIs
Update your app to version 6.0 to invoke the new API endpoints.
I’m using the APIs directly, what do I do?
If you are directly using App ID’s REST APIs with web apps, be sure to update your credentials. Then, if you’re using mobile or web apps, ensure that you’re following OIDC guidelines to verify the App ID tokens appropriately since we have tightened interoperability in this update.
Don’t forget: Re-deploy your app
To pick up the changes, simply re-deploy your application. After you deploy your app, it will use the new APIs and be able to take advantage of all of the updates made to the tokens.
Have questions or feedback?
As always, we’d love to hear your feedback and questions. Get help for technical questions at Stack Overflow with the
ibm-appid tag. For non-technical questions, use IBM developerWorks with the
appid tag. For defect or support needs, use the Support section in the IBM Cloud menu. To get started with App ID, check it out in the IBM Cloud Catalog.