Skip to main content

Access Token Scopes

You use a service account to identify the tenant service group (TSG) to which you want to perform API access. If the TSG or tenant does not have a service account, then you cannot perform API access against it. This is a 1:1 relationship. That is, if you have a tenant, Tenant 1A, with a service account named 1A_svc, then you use that service account to obtain an access token. That access token cannot be used to perform API calls against any other tenant. All API requests made using that access token are routed to the tenant based on the TSG ID contained in the access token.

Note: The TSG IDs used here are intentionally fake. Real TSG IDs are 10-digit integers.

Note: There is no functional difference between a tenant service group and a tenant. The terms are often used interchangeably.

Scope within a TSG hierarchy​

When you use multiple tenants, you will organize them in a hierarchy of TSGs and tenants. You can, if you want, create a dedicated service account for every TSG and tenant in your hierarchy. This is the simplest case, but it isn't necessary. The service account for a TSG can specify the TSG ID of any descendent of that TSG when it creates an access token.

Consider the following diagram. TSG A is the root tenant service group, and it has two tenants: Tenant 1A and Tenant 2A. It also has a child TSG, TSG B, with two tenants: Tenant 1B and Tenant 2B:

In this scenario, assume that service accounts a_svc and b_svc were created with the superuser role for their respective TSGs (TSG A and TSG B). If this is true, then:

  • a_svc service account can be used to create an access token that specifies any TSG_ID in the hierarchy, because every tenant and TSG is a child of TSG A.

  • Tenant 1A, Tenant 2A, Tenant 1B, and Tenant 2B cannot create access tokens directly because they do not have service accounts.

  • b_svc service account can be used to create access tokens for TSG B, plus Tenant 1B and Tenant 2B because those are children of TSG B.

  • b_svc cannot create access tokens for TSG A, Tenant 1A, or Tenant 2A because they are either peers or ancestors in the hierarchy.

Using scope outside of the hierarchy​

In the previous scenario, we showed that b_svc could not be used to create an access token for Tenant 1A. But there might be situations where you need to do this. To work around the TSG hierarchy restrictions, you can create an ordinary user account for Tenant 1A using the Client ID for the b_svc service account. This will allow the b_svc service account to create an access token for API access to Tenant 1a. service account.

You can accomplish this task using the multitenant UI, or you can use the Identity and Access Management create an access policy API. For example:

curl -d "{\"role\":\"superuser\",\"resource\":\"prn:18::::\",\
          \"principal\":\"b_svc@15.iam.panserviceaccount.com\"}" \
-H "Authorization: Bearer <ACCESS_TOKEN_WITH_TSG_15>" \
-H "Content-Type: application/json" \
-X POST https://api.sase.paloaltonetworks.com/access_policies