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 ClaimCenter operational database. For example, Andy Applegate, a ClaimCenter adjuster, is an internal user.

When an internal user makes a system API call (using either basic authentication or bearer token authentication), ClaimCenter 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 Andy Applegate is an internal user with two user roles: Adjuster and Reinsurance Manager. Andy Applegate triggers a system API call. When the API call is received, ClaimCenter queries the database for Andy's user roles. Two user roles are returned: Adjuster and Reinsurance Manager. ClaimCenter then grants Andy the endpoint access defined in the API roles named "Adjuster" and "Reinsurance Manager".

API roles and ClaimCenter 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 ClaimCenter 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 ClaimCenter...	For internal users who trigger a system API call...	Where is the role configured?
InsuranceSuite user role	A set of system permissions	This specifies what the user can do through the ClaimCenter user interface	This is used to determine which API roles to assign to the user	The Roles screen on the ClaimCenter Admin tab
API role	A list of accessible endpoints, operations, 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 and services

An external user is a person who is known to the insurer but who is not listed as a user in the ClaimCenter operational database. A service is a service-to-service application.

When external users or 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 in a JWT

When ClaimCenter receives a JWT, it looks for the API roles to grant. This information is either in the groups token claim (for external users) or the scp token claim (for services). Any value in the appropriate 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 (such as "cc" or "pc"). For each value, ClaimCenter 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 an external user JWT with a groups token claim that contains one string: "gwa.prod.cc.Customer Service Representative". ClaimCenter removes the initial "gwa.prod.cc." 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 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.