Automatic Creation of User Groups and Roles for Apps

overview 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 integration flow 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 (user groups are optional) use the manifest file to assign roles to user groups, granting them the appropriate permissions to access app resources upload the manifest file upload the manifest file using the upload artifact api https //docs getos1 com/reference/uploads an artifact for an app or a soln onboard the app use the onboarding api https //docs getos1 com/reference/onboard tenant v2 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 a manifest file 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 attributes 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 appid "truck tracker" resources \ name "user" description "user endpoint" resourcepath "/core/api/v1/example/users/ " allowedhttpmethods \ get \ post \ put \ delete \ patch isactive true permissions \ action "getuser" httpmethod "get" description "get the user resources" isactive true \ action "createuser" httpmethod "post" description "create the user resources" isactive true \ action "updateuser" httpmethod "put" description "update the user resources" isactive true \ action "deleteuser" httpmethod "delete" description "delete the user resources" isactive true \ action "patchuser" httpmethod "patch" description "patch the user resources" isactive true roles \ rolename "admin" description "admin role of the users" isactive true assignpermissions true cangranttoapps true cangranttousers true permissions \ getuser \ createuser \ updateuser \ deleteuser \ patchuser \ rolename "enduser" description "end role of the users" isactive true assignpermissions true cangranttoapps true cangranttousers true permissions \ getuser \ patchuser rolesrequired roles \ role\ listing id\ participants service \#mapping the roles defined to the user groups for ui users access usergroupsrequired \ name solutions owner description solutions owner role roles \ role\ listing id\ admin \ name field executive description field executive role roles \ role\ listing id\ enduser \#group that is to be assigned to the admin users e g the first user who signs up for the os1 subscription adminusergroups \ solutions admin assign roles to the app 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 upload the manifest use the uploadartifact api https //docs getos1 com/reference/uploads an artifact for an app or a soln 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 curl location request post 'https //developer platform tms/developer/artifacts?appversionid=appversion 1f866da9 6205 5760 a82e 94acb79dcd1e\&artifacttype=manifest' \\ \ form 'file=@"/path/to/app manifest yaml";type=text/x yaml' on success, the response provides the fileid and the url where the artifact has been uploaded update the manifest file 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 https //docs getos1 com/reference/uploads an artifact for an app or a soln , 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 onboard the app after uploading the manifest file, use the onboarding api https //docs getos1 com/reference/onboard tenant v2 to onboard the app https //docs getos1 com/onboarding apps and solutions 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 { "versionid" "appversion\ f8594a6b 47f4 4a3b 9edf 8b2c641e38af", "tenantids" \[ "devtenant1", "devtenant2" ] } 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