Automatic Creation of User Groups and Roles for Apps
App developers can manage their apps' resources, roles, and permissions using the app-level manifest file. This file allows developers to define resources, create roles with specific permissions, assign roles to the app itself using the rolesRequired section, and grant roles to user groups using the userGroupsRequired attribute. The app service automatically creates the necessary resources, roles, and permissions in the AAA system based on the uploaded manifest file, simplifying securing and controlling access to app resources.
This capability enables app developers to configure the required resources, roles, and permissions for their app while maintaining the flexibility to modify them as needed by updating the central manifest file.
- Create a manifest file: Define resources, roles, permissions, and user groups in a YAML manifest file for an app. Refer to the sample app-level manifest file provided below.
- Assign roles to user groups: Use the manifest file to assign roles to user groups, granting them the appropriate permissions to access app resources.
- Onboard the app: Use the Onboarding API to onboard the app with the appVersion to the desired tenants. This step will create the resources, roles, and permissions defined in the manifest file for the specified tenants.
- Update the manifest file: As your app evolves, you can update the manifest file to modify resources, roles, and permissions. Upload the updated manifest file and onboard the app again to update the resources, roles, and permissions in the specified tenants.
Here's a developer guide for the App version of the Automatic Creation of User Groups feature:
Create an app-level manifest file in YAML format that includes resources, roles, and permissions, and their relationships for your app. Let's take a closer look at each section:
- appId: This attribute represents the unique identifier for your app in the AAA system. This is the unique Id (human readable listing-id) that developers select when registering an app. The appId can have one of the following formats:
- platform:app: Uses a human-readable listing-id instead of a UUID. This is the recommended format and makes it easier for developers to implement.
- platform:<uuid>: The developer platform generates this ID when you create an app. Note: We will support UUID based permissions files until September, 2024. We recommend moving to the listing-id format. The recommended format, where <uuid> is a unique identifier assigned by the platform.
- resources: APIs are grouped by resources based on endpoints and permissions. You can use regex to define resourcePaths and allowedHttpMethods to specify permitted HTTP methods. You can control access to specific API endpoints by defining resources and permissions.
- roles: Roles are collections of permissions assigned to user groups or apps. Instead of assigning individual permissions, you can assign roles to appropriate entities. The manifest file allows you to define roles and their associated permissions. You can also use flags to restrict the usage of roles.
- rolesRequired: Specifies the roles that your application requires to function correctly. By listing the required roles, you can ensure that your app receives the necessary permissions during deployment or runtime. This helps maintain your application's security and integrity by explicitly defining its dependencies on specific roles.
Attribute Name | Description |
|---|---|
appId | The unique identifier for your app in the AAA system |
resource | APIs are grouped by resources based on endpoints and permissions |
resource.name | Name of the resource |
resource.description | Human readable description of resource |
resource.resourcePath | Regex of the endpoint represented by the resource |
resource.allowedHttpMethods | List of http methods allowed on the the api path exposed by resourcePath |
resource.isActive | Whether resource is active |
resource.permissions | An array of permissions |
resource.premissions.action | Name of the permission |
resource.premissions.httpMethod | http method protected by the permission in combination with the resourcePath |
resource.premissions.description | Description for permission |
resource.premissions.isActive | Whether permission is active |
roles | Collections of permissions assigned to user groups or apps |
roles.roleName | Human readable name of the role |
roles.description | Description of the role |
roles.canGrantToApps | Whether this role can be assigned to other apps |
roles.canGrantToUsers | Whether this role can be assigned to user groups |
roles.isActive | Is this role active? |
roles.permissions | List of the permissions present in the role |
rolesRequired | Specifies the roles that your application requires to function correctly. |
rolesRequired | List of roleIds with fully qualified role name that are required for given app to work |
userGroupsRequired | Roles defined to the user groups for UI access. |
The following example manifest file demonstrates the structure and content of an app manifest:
In the app manifest file, you can assign roles to the app using the rolesRequired section. This allows you to grant the appropriate permissions to the app, enabling them to access the app's resources based on their assigned roles.
For example, in the manifest file above, the participants-service role is assigned to the app, indicating that the app requires this role to function properly.
Use the UploadArtifact API to upload your app manifest file to the server.
- File: The manifest file to be uploaded. In Postman, select File from the Key dropdown menu to upload your file.
- artifactType: Set the artifactType to MANIFEST
- appVersionID: Include the versionId of the app to upload the file to.
Example:
On success, the response provides the fileID and the URL where the artifact has been uploaded.
As your app evolves and your resource, role, and permission requirements change, you can update the manifest file to reflect these changes. Simply modify the manifest file, adding, updating, or removing resources, roles, and permissions as needed. Upload the updated manifest file using the UploadArtifact API, and the app service will update the AAA system accordingly.
By following this developer guide and utilizing the app-level manifest file, you can efficiently manage resources, roles, and permissions for your app, ensuring that user groups have the appropriate access to your app's functionality.
And here's the new section to be added after the "Upload the Manifest" section:
After uploading the manifest file, use the Onboarding API to onboard the app with the appVersion to the desired tenants. This step will create the resources, roles, and permissions defined in the manifest file for the specified tenants.
You can use the following parameters when onboarding an app:
Path Parameters
Parameter | Description |
|---|---|
stackCredentialOverwrite | Forces the use of production credentials even when onboarding to developer/staging tenants. The acceptable value is production. |
Body Parameters
Parameters | Description |
|---|---|
versionId* | The unique ID for the app version. Example: appversion:0f77dbcd-56vtb-5e12-90d8-6990e3a82b |
tenantId | Unique Id for the tenant to onboard. |
stackId | Onboard app version to all tenants for a stackId. Some example values include p1 and sandbox. |
The following request onboards an app to two tenants:
By onboarding the app with the appVersion to the desired tenants, the resources, roles, and permissions defined in the manifest file will be created for those tenants, ensuring that the app is set up correctly and ready for use.