Resource access strategies

Strategies and IDs

A resource access strategy is a set of logic that identifies which resources a caller can access.

A resource access ID is a string that identifies either who the caller is or what the caller owns.

For each call, resource access is determined by executing the resource access strategy using the resource access ID as input. For example, suppose a given resource access strategy states "the caller can access information related to accounts they own". And suppose, for a given call, the resource access ID is account number 464778619. This would mean the following:

  • The caller can access resources that are related to account 464778619.
  • The caller cannot access resources that are related to accounts other than 464778619.

Some resource access strategies require a single resource access ID. Other resource access strategies allow for an array of resource access IDs.

The list of resource access strategies

The base configuration includes the following resource access strategies:

Strategy name Persona using this strategy Resource access ID is... Grants access to...
bc_username Internal users A BillingCenter user name Resources this internal user could see in BillingCenter.
bc.​service Trusted service-to-service application Not applicable All resources
default Callers who have been authenticated but specify no resource access strategy with the call Not applicable Metadata resources only (including API schemas and typelists)
unauthenticated Callers who have not been authenticated Not applicable API definition metadata only
Strategy name Persona using this strategy Resource access ID is... Grants access to...
bc_username Internal users A BillingCenter user name Resources this internal user could see in BillingCenter.
bc.​service Trusted service-to-service application Not applicable All resources
default Callers who have been authenticated but specify no resource access strategy with the call Not applicable Metadata resources only (including API schemas and typelists)
unauthenticated Callers who have not been authenticated Not applicable API definition metadata only

The strategy name is used in the JWT. It appears in the scp token claim to identify which resource access strategy to use for the call. Also, when appropriate, it appears as its own token claim to specify the resource access IDs.

For example, suppose that a given call is using the bc_username resource access strategy with a resource access ID of aapplegate@acme.com. The JWT would include the following.

"scp": [
  "bc_username"
],
"bc_username": [
  "aapplegate@acme.com"
]
Java

Determining a call's resource access strategy

Resource access strategies are assigned by internal code as described in the following table. For calls made by services with user context, two resource access strategies are assigned, one at the service level and one at the user level. For all other types of calls, only one resource strategy is assigned.

Strategy name This is assigned to a call when...
bc_username

Any of the following are true:

  • The call is using basic authentication, or
  • The JWT's scp token claim contains bc_username, or
  • The call includes a user context header, and the header includes a bc_username token claim, or
  • The JWT specifies a client ID that was mapped to a service account.
bc.​service The JWT's scp token claim contains bc.​service.
default The caller has been authenticated, but the JWT specifies no resource access strategy.
Strategy name This is assigned to a call when...
bc_username

Any of the following are true:

  • The call is using basic authentication, or
  • The JWT's scp token claim contains bc_username, or
  • The call includes a user context header, and the header includes a bc_username token claim, or
  • The JWT specifies a client ID that was mapped to a service account.
bc.​service The JWT's scp token claim contains bc.​service.
default The caller has been authenticated, but the JWT specifies no resource access strategy.

The bc.service resource access strategy

Most of the resource access strategies specify restrictions. These resource access strategies limit what a caller can view.

However, the bc.service resource access strategy specifies almost no restrictions. This is because this resource access strategy is designed to be used by services. Services are expected to be configured such that they access only the resources appropriate for the circumstance. Consequently, JWTs for API calls from services do not typically include resource access IDs.

Note that resource access for the different service-related auth flows behave as described here:

  • For standalone services, calls use the bc.service resource access strategy. Therefore, they have unrestricted resource access.
  • For services with user context, each call's resource access is the intersection of the service-level resource access and the user-level resource access. The service-level resource access is the bc.service resource access strategy, which has no restrictions. Therefore, logically speaking, a service-with-user-context call has resource access equivalent to the user-level resource access.
  • For services with service account mapping, the service is mapped to an internal service account. The bc.service resource access strategy is not used. Rather, the call uses the bc_username resource access strategy.