A while ago a colleague passed on a query from one of his customers who was trying to extract a list of users assigned to the Tenant, IaaS and Fabric Administrator roles in vRA 7.6. They also wanted to extract a list of the users who had the XaaS Architect role. Their aim was to be able to run this on a regular basis ultimately as part of a scheduled task.
The customer had tried a few different things and had been able to return a list of the Tenant Administrators, they were unsure how to get details of the other roles though.
Since I work with vRA more frequently than my colleague he hoped I might have done this before (I hadn’t) or could help confirm for his customer if it was possible.
When I started to investigate the different api options available for vRA on the VMware Code website there appeared to be a few different options that might potentially return the information I wanted. There are queries relating to permissions, roles, principals and groups listed some of which are on a per tenant basis.
There was no magic wand waving here, I ended up trying lots of the different options trying to get a list of the groups, roles or users returned to give me a starting point. I also looked to see which api methods had the option to filter them, or pass a query as a body to set a scope for the search.
Through trial and error I managed to find a set of api commands which could return a list of users assigned to a particular role.
Some examples of the API calls used within this blog post are available as part of the Postman vRealize Automation Identity Service API collection which can be downloaded on the VMware Code website .
Logging in via the API
vRA requires a bearer token to be provided for any api calls that require authorisation or authentication. The token is generated by sending a username, password and tenant name to vRA for a user who is authorised to access the content you want to query within vRA, for example a user who is assigned the Tenant Administrator role.
The url for generating the token is
https://<vra_fqdn>/identity/api/tokensWhen submitting the request you need to specify headers of Accept: application/json and Content-Type: application/json.
You also need to supply the credentials for your user account in the body or data of the request. The example below shows how this is formatted when using Postman with variables for each of the username, password and tenant values. An example using curl is available within the VMware documentation at https://vdc-download.vmware.com/vmwb-repository/dcr-public/06da0b0e-11cf-4471-b1c3-0a040e8910fb/8ec54592-d9e9-4677-9325-801ce9d01d7f/vrealize-automation-76-programming-guide.pdf
{
"username": "{{username}}",
"password": "{{password}}",
"tenant": "{{tenant}}"
}In the response the bearer token is listed in the id field:
{
"expires": "2020-10-28T17:01:39.000Z",
"id": "MTYwMzg3NTY5OTk2Mzo0N2Y0MDViY2M5OTk1Y2UzNTMzZjp0ZW5hbnQ6dnNwaGVyZS5sb2NhbHVzZXJuYW1lOmNsb3VkYWRtaW5AY29ycC5sb2NhbGV4cGlyYXRpb246MTYwMzkwNDQ5OTAwMDo1OTdiZjI5NWY2NzY2YTZhMGQzNTI1YzM4YjkwMTVkYmY5OGMwODk2OTIxNjMyYjQyMDNmY2I0NzM1OWMwYmQ3NWI0ODBmMzc5YjM3YTZlNzQ0MDZkNDRmYzg5ZDQ5OTZkNTExZTMyNzc1ZDA2ZGRhNzhhMGUxNDAxMjEwOTdiZA==",
"tenant": "vsphere.local"
}This token value must be specified in the header of any api calls to provide authorization. To do this add a header Authorization: Bearer <token value> to the api call e.g.
Authorization: Bearer MTYwMzg3NTY5OTk2Mzo0N2Y0MDViY2M5OTk1Y2UzNTMzZjp0ZW5hbnQ6dnNwaGVyZS5sb2NhbHVzZXJuYW1lOmNsb3VkYWRtaW5AY29ycC5sb2NhbGV4cGlyYXRpb246MTYwMzkwNDQ5OTAwMDo1OTdiZjI5NWY2NzY2YTZhMGQzNTI1YzM4YjkwMTVkYmY5OGMwODk2OTIxNjMyYjQyMDNmY2I0NzM1OWMwYmQ3NWI0ODBmMzc5YjM3YTZlNzQ0MDZkNDRmYzg5ZDQ5OTZkNTExZTMyNzc1ZDA2ZGRhNzhhMGUxNDAxMjEwOTdiZA==
Getting the role membership
To get the role membership information I discovered that I needed to use two api calls. The first api call is used to retrieve a role id value for each of the roles I’m interested in, such as Tenant Administrators.
The second api call is used to perform a filtered search against the principals (users and groups) within vRA to return the membership associated with the specified role.
Getting the role id
To be able to perform a filtered search for the membership of a role we need to be able to specify the role id for each of the roles we want to list. The role ids can be found by performing a GET command against:
https://<vra_fqdn>/identity/api/authorization/roles
Remember to set the Accept header to application/json and the Authorization header to include your bearer token for authorization. The results are returned in the body of the response in JSON as an array of roles, including the sub roles they provide.
{
"@type": "TenantRole",
"id": "DESIGNER_SERVICE_ARCHITECT",
"name": "XaaS Architect",
"description": "XaaS Architect",
"assignedPermissions": [
{
"id": "GUI_DESIGNER",
"name": "Access Blueprint and Blueprint Component Design GUI",
"description": "Access the blueprint and blueprint component design GUI.",
"prereqAdminPermissions": null
},
{
"id": "CATALOG_AUTHOR_TENANT",
"name": "Catalog Tenant-level Author",
"description": "Create, update and publish services, catalog items and actions shared across a Tenant.",
"prereqAdminPermissions": null
},
{
"id": "COMPOSITION_SERVICE_AUTHOR_COMPONENT_TYPES",
"name": "Publish Blueprint Components",
"description": "Publish blueprint components for reuse in the tenant.",
"prereqAdminPermissions": null
},
{
"id": "EDIT_ASD_SERVICES",
"name": "Create and Publish XaaS services",
"description": "Create and publish XaaS services.",
"prereqAdminPermissions": null
},
{
"id": "CONTENT_AUTHOR_TENANT",
"name": "Author content tenant wide",
"description": "Create, edit ,import and publish content in the tenant context.",
"prereqAdminPermissions": null
},
{
"id": "CONTENT_CONSUME_TENANT",
"name": "Consume content tenant wide",
"description": "Consume and export content in the tenant context.",
"prereqAdminPermissions": null
},
{
"id": "MANAGE_ASD_CONTENT",
"name": "Manage XaaS content",
"description": "Import/Export XaaS content.",
"prereqAdminPermissions": null
}
]
},The value we are interested in capturing is the id field, for example in the results for the XaaS Architect role you can see the id value listed above the name of the role. There is also an option to provide a filter to this query to target a single role if preferred.
Returning the role membership
Now that we have the role id values we can use them to perform a filtered query with a second api method. The role id is specified at the end of the url after a ? to signify it is a query or filter.
https://<vra_fqdn>/identity/api/tenants/<tenant_id>/principals?role=<role_id>
We are also specifying the tenant we want to gather the role membership within so we are filtering our query to a particular tenant and then reporting the role membership for a specific role within that tenant. The tenant id is specified in the url as the name of the tenant e.g. vsphere.local
This will return a second JSON formatted array which lists the users and groups assigned to the role specified in the query. Whilst the format is not pretty enough to put directly into a report, such as an audit report it would just require the output to be parsed and formatted in some way before it could be shared.
{
"links": [],
"content": [
{
"@type": "User",
"firstName": "Cloud",
"lastName": "Admin",
"emailAddress": "cloudadmin@rainpole.com",
"description": "Cloud Admin",
"locked": false,
"disabled": false,
"password": null,
"principalId": {
"domain": "corp.local",
"name": "cloudadmin"
},
"tenantName": "vsphere.local",
"name": "Cloud Admin"
},
{
"@type": "User",
"firstName": "Rainpole",
"lastName": "Cloud Service",
"emailAddress": null,
"description": "Rainpole Cloud Service",
"locked": false,
"disabled": false,
"password": null,
"principalId": {
"domain": "corp.local",
"name": "rpcloudsvc"
},
"tenantName": "vsphere.local",
"name": "Rainpole Cloud Service"
},
{
"@type": "User",
"firstName": "Rainpole",
"lastName": "Cloud Admin",
"emailAddress": null,
"description": "Rainpole Cloud Admin",
"locked": false,
"disabled": false,
"password": null,
"principalId": {
"domain": "corp.local",
"name": "rpadmin"
},
"tenantName": "vsphere.local",
"name": "Rainpole Cloud Admin"
}
]
}Fabric Administrators – a special case
The api methods outlined above will allow you to gather details on the majority of roles. During testing I found there is an exception though, if you try to use it to gather details about Fabric Administrators no results are returned. I suspect this is because the Fabric Administrator role is not assigned on a per tenant basis.
I wasn’t able to find anyway around this, I couldn’t find any api method which would return details about Fabric Administrators on the Identity api endpoint. It is however very easy to get this information via vRO. The code snippet below will collect all of the Fabric Administrators across all Fabric Groups for a vRA host. It will then sort the list alphabetically and remove any duplicate entries from the list to give a single combined list of administrators. Credit to tnavarro1 who uploaded the original code sample for removing duplicates from an array to the VMware code site, which I am reusing in my vRO code. It will not tell you which Fabric group they are a member of should there be more than one group present, however you could choose to also capture and return this information by using the group.name property for each group.