Assigning API roles to callers

Assigning API roles to internal users

An internal user is a person who is listed as a user in the InsuranceSuite application's operational database. For example:

Andy Applegate, a ClaimCenter adjuster
Alice Applegate, a PolicyCenter underwriter
Aaron Applegate, a BillingCenter clerk

When an internal user makes a Cloud API call (using either basic authentication or bearer token authentication), BillingCenter queries the operational database for this internal user's user roles. The user is given endpoint access to all API roles whose names correspond to the names of the user's user roles.

For example, suppose that Aaron Applegate is an internal user with two user roles: Billing Clerk and Billing Manager. Aaron Applegate triggers a Cloud API call. When the API call is received, BillingCenter queries the database for Aaron's user roles. Two user roles are returned: Billing Clerk and Billing Manager. BillingCenter then grants Alice the endpoint access defined in the API roles named "Billing Clerk" and "Billing Manager".

API roles and BillingCenter user roles

For internal users, there are two sets of roles that are used to enable endpoint access. For each logical role, there is a BillingCenter user role and an API role with the same name. The API role provides endpoint access comparable to the user role.

The following table compares the two types of roles.


Type of role	What does the role specify?	For internal users logging directly in to BillingCenter...	For internal users who trigger a Cloud API call...	Where is the role configured?
InsuranceSuite user role	A set of system permissions	This specifies what the user can do through the BillingCenter user interface	This is used to determine which API roles to assign to the user	The Roles screen on the BillingCenter Admin tab
API role	A list of accessible endpoints, methods, and fields	Not applicable	This specifies the endpoint access provided to the user	A set of YAML files in Studio

Assigning API roles to external users

An external user is a person who is known to the insurer but who is not listed as a user in the BillingCenter operational database.

When external users make API calls, the call includes a JWT (JSON Web Token). This JWT contains authentication information about the caller, including the API roles to assign to the caller.

Parsing API role information

When BillingCenter receives a JWT, it extracts the information into a "token map". It then calls the IExpandTokenPlugin plugin, which may add or modify values in the token map.

Then, BillingCenter looks in the token map for the API roles to grant. For external users, this information is in the groups claim. Any value in this claim is assumed to be an API role if it starts with "gwa.<planetclass>.<xc>.", where <planetclass> is set to either "prod", "preprod", or "lower", and where <xc> is the application code ("cc", "pc", or "bc"). For each value, BillingCenter does the following:

It strips off the prefix "gwa.<planetclass>.<xc>." substring.
It converts any blanks in the remaining to string to underscores.
It then searches for an API role file with the same name.

For example, suppose there is a token map with a groups token claim that contains one string: "gwa.prod.bc.Customer Service Representative". BillingCenter removes the initial "gwa.prod.bc." and converts the spaces to underscores, resulting in the string "Customer_Service_Representative". It then searches for an API role whose file name is "Customer_Service_Representative.role.yaml".

If there are no matches between the resulting strings and the API role names, the caller is given no endpoint access.

If there are multiple matches between the resulting substrings and API role names, the caller is given the union of the access specified in all matching roles. In other words, the API roles are ANDed together.

Assigning API roles to standalone services

A standalone service is a service-to-service application that executes the call as itself. It does not execute the call on behalf of a specific person or through a BillingCenter user account.

When standalone services make API calls, the call includes a JWT (JSON Web Token). This JWT contains authentication information about the caller, including the API roles to assign to the caller.

Parsing API role information

When BillingCenter receives a JWT, it extracts the information into a "token map". It then calls the IExpandTokenPlugin plugin, which may add or modify values in the token map.

Then, BillingCenter looks in the token map for the API roles to grant. For standalone services, this information is in the scp token claim. Any value in this token claim is assumed to be an API role if it starts with "scp.<xc>.", where <xc> is the application code ("cc", "pc", or "bc"). For each value, BillingCenter does the following:

It strips off the prefix "scp.<xc>." substring.
It converts any blanks in the remaining to string to underscores.
It then searches for an API role file with the same name.

For example, suppose there is a token map with a scp token claim that contains the following string: "scp.bc.Document Viewer". BillingCenter removes the initial "scp.bc." and converts the spaces to underscores, resulting in the string "Document_Viewer". It then searches for an API role whose file name is "Document_Viewer.role.yaml".

If there are no matches between the resulting strings and the API role names, the caller is given no endpoint access.

If there are multiple matches between the resulting substrings and API role names, the caller is given the union of the access specified in all matching roles. In other words, the API roles are ANDed together.

Assigning API roles to services with user context

A service with user context is a service-to-service application that presents information about itself and about a specific user. The call is able to do only the things that both the service by itself could do and the user by itself could do.

When services with user context make API calls, the call includes a JWT (JSON Web Token) and a user context header. The JWT contains authentication information about the caller, including the API roles associated with the service. The user context header contains authorization information about the user, including the API roles associated with the user.

Parsing API role information

When BillingCenter receives a JWT, it extracts the information into a "token map". It then calls the IExpandTokenPlugin plugin, which may add or modify values in the token map.

Then, BillingCenter looks in the token map for the API roles to grant. For services with user context, this information is in the scp token claim. Any value in the appropriate token claim is assumed to be an API role if it starts with "scp.<xc>.", where <xc> is the application code ("cc", "pc", or "bc"). For each value, BillingCenter does the following:

It strips off the prefix "scp.<xc>." substring.
It converts any blanks in the remaining to string to underscores.
It then searches for an API role file with the same name.

Parsing API role information in the user context header (internal users)

When BillingCenter receives a request with a user context header, it looks for the API roles to grant. If the user context specifies an internal user, BillingCenter retrieves the user's name from the <xc>_username token, where <xc> is the application code ("cc", "pc", or "bc"). Then, BillingCenter queries the operational database for this internal user's user roles. The user is given endpoint access to all API roles whose names correspond to the names of the user's user roles.

Parsing API role information in the user context header (external users)

When BillingCenter receives a request with a user context header, it looks for the API roles to grant. If the user context specifies an external user, BillingCenter checks the groups token in the user context header. Any value in this token claim is assumed to be an API role if it starts with "gwa.<planetclass>.<xc>.", where <planetclass> is set to either "prod", "preprod", or "lower", and where <xc> is the application code ("cc", "pc", or "bc"). For each value, BillingCenter does the following:

It strips off the prefix "gwa.<planetclass>.<xc>." substring.
It converts any blanks in the remaining to string to underscores.
It then searches for an API role file with the same name.

Assigning API roles

BillingCenter assigns the caller endpoint access to all endpoints, methods, and fields listed in both the service's API roles and the user's API roles.

For example, suppose a service with user context sends a call with the following:

A JWT with a scp token claim that contains the following string: "scp.bc.Document Editor".
A user context header that specifies an external user with a groups token claim that contains the following string: "gwa.prod.bc.Document Viewer".

First, BillingCenter determines the service's API roles. To do this, it converts the JWT into a token map. Then, it removes the initial "scp.bc." from the token map's scp claim and converts the spaces to underscores, resulting in the string "Document_Editor". It then searches for an API role whose file name is "Document_Editor.role.yaml".

Second, BillingCenter determines the user's API roles. To do this, it removes the initial "gwa.<planetclass>.<xc>." from the user context header's groups token claim and converts the spaces to underscores, resulting in the string "Document_Viewer". It then searches for an API role whose file name is "Document_Viewer.role.yaml".

Finally, BillingCenter grants endpoint access to:

Every endpoint listed in both "Document_Editor.role.yaml" and "Document_Viewer.role.yaml".
Every method on the endpoints that are listed in both "Document_Editor.role.yaml" and "Document_Viewer.role.yaml".
Every field on the endpoint resources that are listed in both "Document_Editor.role.yaml" and "Document_Viewer.role.yaml".

Assigning API roles to services with service account mapping

A service with service account mapping is a service-to-service application that is mapped to an account in the BillingCenter database and has access as determined by that account.

When a service with service account mapping makes a Cloud API call, it presents a client ID. BillingCenter maps that client ID to a service account (a user account that is not used by any person, but rather is used exclusively by the service it is mapped to). BillingCenter then queries the operational database for this service account's user roles. The service is given endpoint access to all API roles whose names correspond to the names of the service account's user roles.

For example, suppose that ACME Documents is a service with service account mapping. It is mapped to a service account with two user roles: Document Viewer and Document Editor. ACME Documents triggers a Cloud API call. When the API call is received, BillingCenter maps the service to its service account and then queries the database for the service account's user roles. Two user roles are returned: Document Viewer and Document Editor. BillingCenter then grants ACME Documents the endpoint access defined in the API roles named "Document Viewer" and "Document Editor".

API roles and BillingCenter user roles

For service accounts, there are two sets of roles that are used to enable endpoint access. For each logical role, there is a BillingCenter user role and an API role with the same name. The API role provides endpoint access comparable to the user role.

The following table compares the two types of roles.


Type of role	What does the role specify?	If the service were to directly log in to BillingCenter...	For internal users who trigger a Cloud API call...	Where is the role configured?
InsuranceSuite user role	A set of system permissions	This specifies what the service account could do if it were to log in to the BillingCenter user interface	This is used to determine which API roles to assign to the service	The Roles screen on the BillingCenter Admin tab
API role	A list of accessible endpoints, methods, and fields	Not applicable	This specifies the endpoint access provided to the service	A set of YAML files in Studio

Assigning API roles to other types of callers

An unauthenticated caller is a user or service who provides no authentication information. Unauthenticated callers can access only metadata endpoints. Unauthenticated callers are automatically assigned the API role named Unauthenticated.