Assigning API roles to callers

The manner in which API roles are assigned to a caller depends on the type of caller.

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), PolicyCenter 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 Alice Applegate is an internal user with two user roles: Underwriter and Reinsurance Manager. Alice Applegate triggers a Cloud API call. When the API call is received, PolicyCenter queries the database for Alice's user roles. Two user roles are returned: Underwriter and Reinsurance Manager. PolicyCenter then grants Alice the endpoint access defined in the API roles named "Underwriter" and "Reinsurance Manager".

API roles and PolicyCenter 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 PolicyCenter 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 PolicyCenter... 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 PolicyCenter user interface This is used to determine which API roles to assign to the user The Roles screen on the PolicyCenter 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 PolicyCenter 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 PolicyCenter 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, PolicyCenter 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, PolicyCenter does the following:

  1. It strips off the prefix "gwa.<planetclass>.<xc>." substring.
  2. It converts any blanks in the remaining to string to underscores.
  3. 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.pc.Customer Service Representative". PolicyCenter removes the initial "gwa.prod.pc." 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 PolicyCenter 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 PolicyCenter 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, PolicyCenter 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, PolicyCenter does the following:

  1. It strips off the prefix "scp.<xc>." substring.
  2. It converts any blanks in the remaining to string to underscores.
  3. 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.pc.Document Viewer". PolicyCenter removes the initial "scp.pc." 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 PolicyCenter 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, PolicyCenter 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, PolicyCenter does the following:

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

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

When PolicyCenter receives a request with a user context header, it looks for the API roles to grant. If the user context specifies an internal user, PolicyCenter retrieves the user's name from the <xc>_username token, where <xc> is the application code ("cc", "pc", or "bc"). Then, PolicyCenter 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 PolicyCenter receives a request with a user context header, it looks for the API roles to grant. If the user context specifies an external user, PolicyCenter 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, PolicyCenter does the following:

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

Assigning API roles

PolicyCenter 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.pc.Document Editor".
  • A user context header that specifies an external user with a groups token claim that contains the following string: "gwa.prod.pc.Document Viewer".

First, PolicyCenter determines the service's API roles. To do this, it converts the JWT into a token map. Then, it removes the initial "scp.pc." 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, PolicyCenter 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, PolicyCenter 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 PolicyCenter 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. PolicyCenter 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). PolicyCenter 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, PolicyCenter 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. PolicyCenter then grants ACME Documents the endpoint access defined in the API roles named "Document Viewer" and "Document Editor".

API roles and PolicyCenter 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 PolicyCenter 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 PolicyCenter... 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 PolicyCenter user interface This is used to determine which API roles to assign to the service The Roles screen on the PolicyCenter 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 and the endpoints to create an account. Unauthenticated callers are automatically assigned the API role named Unauthenticated.

An anonymous user is a person who is not yet known to the insurer but who may establish a business relationship with the insurer. Typically, an anonymous user can only create an account (and its associated objects), quote a submission, and bind a submission. Once an anonymous user binds a submission, they logically move from being an anonymous user to an external user.

Every anonymous user starts out as an unauthenticated user. After the user creates an account, PolicyCenter generates a self-signed JWT. This JWT grants the user access to the API role named anonymous.