Managing User Roles¶
Roles contain permissions for users to manage the server. They can be reused and they eliminate the overhead of granting permissions to users individually.
The following roles that are typically used in many enterprises are used throughout this documentation. You can also define different user roles depending on your requirements.
- admin: The API management provider who hosts and manages the API Gateway and is responsible for creating users in the system, assigning them roles, managing databases, security, etc. The Admin role is also used to access the WSO2 Admin Portal (
https://<APIM_Host>:<APIM_Port>/admin), where you can define workflow tasks, throttling policies, analytics configurations, etc. The Admin role is available by default with the credentials admin/admin. By default, this role contains all the permissions (including super admin permissions) in the permission tree.
- creator: A creator is typically a person in a technical role who understands the technical aspects of the API (interfaces, documentation, versions, etc.) and uses the API publisher to provision APIs into the Developer Portal. The creator uses the Developer Portal to consult ratings and feedback provided by API users. The creator can add APIs to the Developer Portal but cannot manage their lifecycle. Governance permission gives a creator permission to govern, manage, and configure the API artifacts.
- publisher: A person in a managerial role and overlooks a set of APIs across the enterprise and controls the API lifecycle, subscriptions, and monetization aspects. The publisher is also interested in usage patterns for APIs and has access to all API statistics.
- subscriber: Users or Application Developers who search the Developer Portal to discover APIs and use them. They read the documentation and forums, rates/comments on the APIs, subscribes to APIs, obtain access tokens, and invokes the APIs.
Follow the instructions below to create the
subscriber roles in the API Manager for sample purposes.
Creating user roles¶
- Sign in to the management console (
https://<APIM_Host>:<APIM_Port>/carbon) as the admin (default credentials are admin/admin).
Click Main, and then click Add under Users and Roles.
Click Add New Role.
Enter the name of the user role (e.g.,
In the Domain list, specify the user store where you want to create this role. This list includes the primary user store and any other secondary user stores that are configured for your product. For information on how user stores (which are repositories storing information about users and roles) are set up and configured, see Configuring User Stores. Enter a unique name for this role (
creator) and click Finish.
The Domain drop-down list contains all user stores configured in the system. By default, only the PRIMARY user store is configured. To configure secondary user stores, see Configuring Secondary User Stores.
In WSO2 API Manager, Developer Portal and Publisher Web Application UIs are populated by API-M REST APIs and all the authentication and authorization to access the different components in the UI solely depend on the scope role mapping defined in
/_system/config/apimgt/applicationdata/tenant-conf.jsonthat can be accessed through the Management Console from Resources > Browse.
By default, the scope-role mapping contains
Internal/devopsas the default roles. If there are custom roles defined with API creator, API publisher, admin and API subscriber permissions, those roles have to be configured in the
tenant-conf.jsonfile under the relevant scopes.
For more information on role mapping or scope mapping, see Adding role permissions
When a user creates an application and generates application keys, a role is created automatically in the following format.
This is a special case of the
internal role that is created for a particular service provider application. Only users who are assigned the application role permission can manage the corresponding service provider application.
These roles do not have any permissions assigned to it, but it is used to manage the visibility of the corresponding service provider that is created in the format of
'<username>_<applicationUUID>_PRODUCTION' within the Key Manager. The created service provider is only visible to users with the latter mentioned role that has been generated automatically. Only if a user with admin privileges assigns the latter mentioned role to a user, will that user be able to view the details of the service provider that is created per application.
As a limitation, when you delete a user and create another with the same username, applications of the previous user will be visible on the Developer Portal applications listing page. However the new user will not be able to access the details of the application as the service provider is already deleted.
Adding Role Mappings¶
You can use role mapping to map the above created roles to the existing default internal roles of API-M. This enables users with new roles to use REST API scopes of API-M Portals easily.
Sign in to the Admin Portal (
https://<APIM_Host>:<APIM_Port>/admin) if you have not done so already.
Provide the name of the newly created role.
The newly created role can be mapped to an existing internal or admin role if required.
Select the required existing scopes for the newly created role and save the changes.
This will update all the scope mappings in the
tenant-conf.jsonfile with the
Internal/creatorrole as an allowed role. As a result, the new creator role will also be allowed for all scopes that are allowed for the
The following are the scopes that are allowed for each default Internal role under the default configurations section.
Editing or deleting a role¶
Sign in to the management console (
https://<APIM_Host>:<APIM_Port>/carbon) if you have not done so already.
In the Main menu, click List under Users and Roles.
If you need to modify to a role, select the domain (user store) under Search Roles > Select Domain where the role resides.
Then use the relevant links in the Actions column that corresponds to the role listing to perform the following:
- Rename the role
- Change the default permissions associated with this role
- Assign this role to users
- View the users who are assigned this role
- Delete the role if you no longer need it
If the role is in an external user store to which you are connected in read-only mode, you will be able to view the existing roles but not edit or delete them. However, you can still create new editable roles.
Updating before the first startup (recommended)¶
The default role name of the Administrator, (
admin) can be changed before starting WSO2 API Manager by editing
<API-M_HOME>/repository/conf/deployment.toml file. For more information, see Change the super admin credentials.
Configure the property
admin_role with your custom role (
administrator) in the
deployment.toml file as follows and start the server.
[super_admin] admin_role = "administrator" username = "admin" password = "admin" create_admin_account = true
Updating the role name after the product is used for some time (advanced configuration)¶
These steps are not necessary if you have already updated the role names before the first startup of the product.
The following steps guide you through updating the role names after you have used the product for some time.
Make the configuration changes indicated in the above section.
Do the following user store level changes for existing users:
If you are connected to the
JDBCUserStoreManager, update the
UM_ROLEtable with the new role name that you defined in place of the
The schema can be located by referring to the data source
[database.shared_db]defined in the
deployment.tomlfile. The data source definition can also be found in the same file.
- If you are connected to the
ReadWriteLdapUserStoreManager, populate the members of the previous
adminrole to the new role under Groups. For more information, see Configuring User Stores
- If you are connected to the
Start the apim server with newly configured admin role.
Log into the management console (
https://<APIM_Host>:<APIM_Port>/carbon) with the new admin credentials.
Navigate to Main > Resources and click on Browse.
Update all the places where the "admin" key word exists with your new admin role (i.e
Save the changes and restart the server.