With IBM Cloud™ App ID, you can define which users are able to access your sensitive data, use specific features, or perform specific actions in your apps.
Ensuring that the correct people have the approved access when they need it can be difficult when you are coding your application. Now, with IBM Cloud App ID, you can define which users are able to access your sensitive data, use specific features, or perform specific actions in your apps.
In this blog post, I'll walk you through how you can grant access to specific resources by defining runtime actions and assigning role-based permissions to your users. I'll also show how my application validates users' scopes to provide a different experience according to their role.
A scope is a runtime action in your application that you register with IBM Cloud App ID to create an access permission. A role is a collection of scopes that allow varying permissions to different types of app users. To control access, you can create scopes and group them into roles. Then, you can assign the role to one or more of your app users.
So, to show what that means, I'm using an elevator application as an example. I'll assign roles to the different types of users that allow each type of user to perform different operations. Specifically, I'll assign the roles Caller and Technician. A Caller is able to call the elevator and select a new floor only. The Technician role allows the user to perform more operations. For example, If I don't want just anyone to be able to stop or service the elevator; the permissions for those actions are assigned to the Technician only.
Before you begin
Before you can start creating roles and scopes, you need to be sure that you have the following prerequisites:
- An instance of App ID.
- An application.
- App users. For this blog post, I created the users Bob, Peter, and Ted in Cloud Directory.
Want to follow along?
- Download the sample app.
localhost:3000/*to your list of allowed redirect URIs. You can edit your allowed redirect URIs on the Manage authentication > Authentication settings page of the App ID dashboard.
Creating scopes and roles
Now that App ID is configured and I have the users that I need, let's walk through creating scopes and roles.
- Register your application with App ID by going to Applications > Add Application. I created an application called
Elevatorsand I defined the scopes
elevator.serviceto represent the specific operations that the different roles can perform:
- Create your roles by going to Roles and profiles > Roles > Create role. I created the roles
Technician. I added only the
elevator.callscope to the
Callerrole. While for the
Technicianrole, I gave the ability to complete more operations by adding the scopes
- Assign the roles to specific application users by going to Roles and profiles > User profiles. Then, choose the user that you want to assign the role to and click the More options menu > Assign role. I assigned the
Technicianrole to Ted and the
Callerrole to Peter. In the following image, you can see what it looks like when I assign the
Technicianrole to Ted:
Note: I used the credentials of my elevator application in the configuration of my sample applications in
localdev-config.json. To grab your credentials, open your application in the Applications page of the App ID dashboard.
Configuring your application's endpoints
After creating the roles and assigning them to users, I want my application to verify the users' scopes when performing certain operations. To do this, I will define some endpoints on my application that will either use App ID's WebApp Strategy or send a request to backend endpoints that I will also define, which will perform the validation by using App ID's API Strategy.
WebAppStrategy (Web app endpoints)
Using the elevator app as an example, you can see how I secure the following endpoint by using the
hasScope method in
WebAppStrategy to check whether the access token contains the
These three endpoints call backend server endpoints to validate that the access token contains the
elevator.stop scopes respectively:
APIStrategy (Backend endpoints)
These endpoints on the backend server use APIStrategy to validate that the access token contains the
elevator.stop scopes respectively:
Access control in action
Signing in as Bob (no roles)
Bob doesn't have the
Caller role, and specifically, he doesn't have a role that contains the
elevator.call scope, so he is not able to call an elevator. When he tries to call the elevator, Bob receives a message saying he doesn't have the permissions that are required for this action:
Viewing Bob's access token, we see it doesn't contain any of the scopes we defined for this application:
Signing in as Peter (Caller role)
When signing in with Peter (who has the Caller role), we land on the following page:
Peter has the caller role so he is able to call an elevator:
Viewing Peter's access token, we see that it contains the
Signing in as Ted (Technician role)
The technician menu is only shown for users with the
elevator.stop scopes. Ted has the Technician role that contains these scopes, so he is shown the Technician menu:
Ted can call an elevator since he has the
elevator.call scope as part of the Technician role:
When you click on
Stop Elevator or
Start Service Mode, a request is sent to the backend server to validate that the access token contains the required scope. Ted's access token contains the
elevator.stop scope. When he clicks the
Stop Elevator button, his access token is validated by the server, which will allow us to show the text:
Elevator is now stopped:
Viewing Ted's access token, we see it contains the scopes
In this post, I showed you how to use App ID to manage users access permissions to your application's resources. Hopefully, now you feel confident in your ability to set up your App ID instance with scopes and roles and set up your application to manage access according to the roles that you assigned.
Questions and feedback
We'd love to hear from you with feedback! Have questions, comments, or concerns? Let us know:
- Reach out directly to the development team on Slack!
- If you have technical questions about App ID, post your question on Stack Overflow and tag your question with
- For questions about the service and getting started instructions, use the IBM Developer Answers forum. Include the
- Open a support ticket in the IBM Cloud menu.
To get started with App ID, check it out in the IBM Cloud Catalog.