Automatic Creation of User Groups
Developers can now streamline creating and updating solution level user groups using the solution service-level manifest file. This manifest file allows developers to define the user groups with corresponding role mappings. The solution service in turn will create the user groups in AAA based on the uploaded manifest file. Once a customer subscribes to a solution, the user groups defined in the manifest are automatically created within the tenant with the mapped roles assigned. After subscription, developers can update the user groups and role mappings by uploading a new manifest file, which in turn will be used by the solution service to update the AAA user groups.
This capability allows developers to configure the necessary user groups and permissions for their solution while having the flexibility to modify as needed by updating the central manifest file.
Additionally, we introduced schema validation in the UploadArtifact API for App and Solution manifest file types so developers can catch any potential schema level issues while uploading the YAML files.
- Create a manifest file: Define user groups and role mappings in a YAML manifest file for a solution. Please refer here for a sample solution level manifest file.
- Onboard to tenants: Use the Onboarding API to onboard the solution. When a customer subscribes the solution service will create user groups with role mappings in AAA. There is also
Create a solution-level manifest file in YAML format that includes user groups and their corresponding roles.
The following example manifest provides a pre-defined set of user groups for both administrators and business users. It also maps the relevant application roles to each group. Additionally, when a solution is subscribed, it automatically assigns the "Solutions-Admin" group to the tenant administrator.
In the YAML file, we have a solution-level manifest that defines user groups and their associated roles for the "gated-solution" solution. Let's break down what this YAML file is doing:
- solutionId: This attribute specifies the unique identifier for the solution, which is "gated-solution" in this case.
- userGroupsRequired: This section defines the user groups required for the solution.
- name: Specifies the name of the user group. In this example, we have two user groups: "Solutions-Owner" and "Field-Executive".
- description: Provides a brief description of the user group's purpose or role within the solution.
- landingPage: Specifies the landing page details for each user group.
- url: Indicates the URL or path of the landing page associated with the user group.
- rank: Determines the order or priority of the landing page for the user group.
- roles: Lists the roles assigned to each user group using the format Role:<listingId>:<roleName>.
- For the "Solutions-Owner" user group, two roles are assigned: "dispatch-get-orders" and "dispatch-view-orders" from the "dispatch-orders-app" listing.
- For the "Field-Executive" user group, three roles are assigned: "dispatch-list-routes" and "dispatch-view-routes" from the "dispatch-routes-app" listing, and "dispatch-view-users" from the "dispatch-users-app" listing.
- adminUserGroups: This section specifies the user group(s) that should be assigned to the tenant admin users for this solution. In this example, the "Solutions-Admin" user group is assigned to the tenant admin users.
Please note that if an app developer includes an existing user group (a group that already exists in a solution manifest) within their App manifest /permissions file, then the developer can only assign new roles to the existing group but will not be able to remove the roles added to such a user group. The vice versa is also true i.e. roles defined by the App manifest file cannot be removed from the solution manifest by the solution developers.
Also, in such cases, the resultant user group will be a union of user groups (and roles assigned) in the solution manifest and user groups (and roles assigned) in the app manifest.
Certainly! Here's an updated section for the "Automatic Creation of User Groups and Roles for Apps" developer guide that covers updating permissions for a Frontend App:
When developing a frontend application that interacts with a backend app, you can define the roles required by the frontend app to communicate with the backend. This allows for more granular control over the permissions granted to the frontend app and helps in managing the size of access tokens.
To update the permissions for a frontend app, you need to create a YAML file that specifies the required roles. Here's an example YAML file:
In this YAML file:
- The appId field follows the format platform:<AppIdFromDevPortal>-client, where <AppIdFromDevPortal> represents the unique identifier of the app obtained from the Developer Portal.
- The rolesRequired section lists all the roles that the users of the frontend app may require to communicate with the backend of the corresponding app.
By specifying the required roles in the YAML file, you can control the permissions granted to the frontend app. When an access token is generated for a user of the frontend app, it will contain the intersection of the user's roles and the roles specified in the rolesRequired section of the YAML file.
For example, let's say a user has roles A, B, C, and D. If the frontend app requires only roles A and B, as specified in the YAML file, the access token generated for that user will contain only roles A and B.
Use the UploadArtifact API to upload your manifest file to the registered solution. By default, the user groups from manifest are created during tenant subscription to the solution.
If you want to create user groups at solution onboarding, you need to specify it using the forceCreateUserGroup parameter in Onboarding API request.
- 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
- solutionVersionID: Include the versionId of the solution to upload the file to.
Example:
On success, the response provides the fileID and the URL where the artifact has been uploaded.
Please note that only the Solution owner/s will be able to update their solution-level manifest file, the same is true for app-level manifest as well (only the app developers will be able to update).
Proceed to use the Onboarding API to onboard the solution to the desired tenants. Upon initial subscription, the solution service will automatically create or update user groups in AAA based on the uploaded manifest. Whenever the manifest file is updated and onboarded, the user groups will be updated accordingly.
There are two flows:
- First time user group creating during the initial subscription
- Ongoing updates to existing groups based on the updated manifest yaml file as and when the updated file is onboarded through platform
Upon subscription or when there is any change to the manifest, the solution service ensures the user groups and role mappings in AAA match the latest manifest.
You can use the following parameters when onboarding a solution:
Path Parameters
Parameter | Description |
|---|---|
stackCredentialOverwrite | Forces the use of production credentials even when onboarding to developer/staging tenants. The acceptable value is production. |
forceCreateUserGroup | Set to true in order to force the user group creation during onboarding. |
Body Parameters
Parameters | Description |
|---|---|
versionId* | The unique ID for the app or solution version. Example: solutionversion:0f77dbcd-56vtb-5e12-90d8-6990e3a82b |
tenantIdx | Unique Id for the tenant to onboard. |
stackId | Onboard app or solution version to all tenants for a stackId. Acceptable Values:
|
The following request onboards a solution to a two tenants:
Use the CreateUsers API to add users, passing the group names from the manifest file and setting designation per the solution’s requirements for proper group mapping. This step allows for flexible mapping between designations and user groups, supporting both one-to-one and one-to-many relationships.
The following example request creates a new user, setting the designation field parameter as "New-Tenant-Admin" and the groups object as "solutions-admin" and "business-owner":