Specific Cloud API resource access strategies

The contactAuthorizationIds strategy

This section only applies to ClaimCenter and BillingCenter.

The contactAuthorizationIds resource access strategy is designed to provide access for claimants in ClaimCenter and account owners, primary payers, and invoice item payers in BillingCenter. This strategy accepts an array of one or more contact authorization IDs. It provides callers with access to resources associated with claims where at least one of the provided contacts has an appropriate business relationship with the resource.

Here is a ClaimCenter example: suppose a caller made a request with the following JWT.

"scp": [
  "cc_contactAuthorizationIds",
  "tenant.acme",
  "project.default",
  "planet_class.prod"
],
"groups": [
  "gwa.prod.cc.Claimant"
],
"cc_contactAuthorizationIds": [
  "cm:123890",
  "cm:445566"
]

Based on the cc_contactAuthorizationIds token, the caller would have access to resources where either contact cm:123890 or contact cm:445566 had an appropriate business relationship with the resource. For example, the caller can access any claim where contact cm:123890 or contact cm:445566 is listed on the claim's policy as the insured or a covered party. The caller could also access any exposure on those claims where contact cm:123890 or contact cm:445566 is the exposure's claimant.

Assigning authorization IDs to contacts

The contactAuthorizationIDs resource access strategy requires the following to be true:

If the strategy is being used for ClaimCenter, every caller using the strategy is represented in the ClaimCenter database as a ClaimContact who is associated with a Contact with an authorization ID.
If the strategy is being used for BillingCenter, every caller using the strategy is represented in the BillingCenter database as an AccountContact or PolicyContact who is associated with a Contact with an authorization ID.
The JWT includes that authorization ID.

When determining how to assign authorization IDs, the insurer must consider several use cases. This includes assigning authorization IDs to the following:

Contacts newly created in ClaimCenter or BillingCenter, depending on which application is using the strategy
Contacts created in another Guidewire application, such as PolicyCenter
Contacts migrated from another system or previous version of ClaimCenter or BillingCenter, depending on which application is using the strategy

For more information on how to assign authorization IDs, see Configuring Cloud API contact authorization IDs.

Filtered access to third-party data

For some types of callers, some resources contain data that is third-party data from the perspective of the caller. This applies to external users using the contactAuthorizationIds strategy.

Here is a BillingCenter example: suppose Ray Newton is the owner of account 111 and an invoice item payer for account 222. Ray Newton can access all contacts on account 111, as he is the account owner. But for account 222, Ray Newton can access only the contact that represents himself. Ray Newton does not have access to accounts on account 222 other than himself.

To control access to third-party data, Cloud API uses additional accessible fields filters. These filters are expressions that check the business relationship a caller has with each resource. The filter can limit which fields the caller can view or edit.

For more information on filtered access to third-party data, see Filtering Cloud API access to third-party data in BillingCenter.

The producerCodes strategy in ClaimCenter

This section only applies to ClaimCenter.

The producerCodes resource access strategy accepts an array of one or more producer codes. It provides callers with access to resources associated with claims where the producer code for the producer of service on the claim's policy is one of the provided producer codes.

For example, suppose a caller made a request with the following JWT.

"scp": [
  "cc_producerCodes",
  "tenant.acme",
  "project.default",
  "planet_class.prod"
],
"groups": [
  "gwa.prod.cc.Producer"
],
"cc_producerCodes": [
  "100-002541",
  "100-002542",
  "100-002543"
]

Based on the cc_producerCodes token, the caller would have access to claims in which the producer code for the producer of service was 100-002541, 100-002542, or 100-002543.

Uniqueness of producer codes

InsuranceSuite does not require producer codes to be unique across producers. For example, suppose you have two producers: Allrisk Insurers and Allied Assistance. Within InsuranceSuite, both of those producers could have a producer code of "All-001". If two producers have the same producer code, then information that is associated with one producer would be visible to calls made by the other producer.

To ensure that each producer can see only the information related to their policies, Guidewire recommends that all producer codes across producers are set to unique values.

Determining who the producer of service is

Every claim's policy which has a ProducerCodeOfService field. When checking to see if a given producer can access a given claim, Cloud API checks to see if one of the producer codes in the JWT matches the value of the ProducerCodeOfService field.

For producerCode access to work, the claim's ProducerCodeOfService field must be set with a value from the Policy Administration System (PAS) that identifies the producer of service at the time the claim is filed. In the base configuration, the SOAP APIs that integrate InsuranceSuite applications with one another do not pass this field from PolicyCenter to ClaimCenter. If your instance of ClaimCenter supports producer access, Guidewire recommends you ensure that you modify the integration point as needed to include this value when the policy is copied.

Large numbers of producer codes and the IExpandTokenPlugin plugin

For some insurers, a single producer can have hundreds of producer codes. The entire set of producer codes may be needed to determine which claims a producer can access. But, there can be performance issues if hundreds of producers are included in the SAML response from the IdP, or if hundreds of producers are included in a JWT that Guidewire Hub creates and hands off to ClaimCenter.

To address potential performance issues, Cloud API also supports the IExpandTokenPlugin plugin. This is a plugin that "expands" the information in the JWT with additional information from an external system. The expansion occurs after the JWT has been received from Guidewire Hub but before Cloud API process authorization. Insurers can use this plugin to retrieve additional information relevant to authorization.

Note: Most access information in a JWT can either be included in the SAML response to Guidewire Hub or can be added by the IExpandTokenPlugin plugin. However, if your producer callers require a large number of producer codes, then Guidewire recommends adding the producer codes only through the IExpandTokenPlugin plugin. This helps prevent performance issues that can occur when sending large numbers of values in a SAML response to Guidewire Hub and putting those values in the JWT Guidewire Hub sends to the caller.

Note: Guidewire does not recommend executing calls where the producerCode list has more than 1000 elements. Producer codes are added to the database query's where clause. Database queries begin to degrade when the number of values in the where clause exceeds 1000.

For more information on configuring this plugin, see Configuring the Cloud API IExpandTokenPlugin.

Filtered access to third-party data

For some types of callers, some resources contain data that is third-party data from the perspective of the caller. This applies to external users using the producerCodes strategy.

For example, suppose Karen Egerston is a producer who is managing a claim for a policyholder named Ray Newton. Ray has filed a claim. The claim involves two damaged vehicles: Ray's vehicle and one owned by a third party named Bo Simpson. Karen Egerston can access the Ray Newton ClaimContact and the information about his vehicle. But, the Bo Simpson ClaimContact and Bo Simpson's vehicle both contain third-party data. They include information such as Bo Simpson's telephone number and the value of Bo Simpson's vehicle. Karen Egerston isn't supposed to have access to this information.

To control access to third-party data, Cloud API uses additional accessible fields filters. These filters are expressions that check the business relationship a caller has with each resource. The filter can limit which fields the caller can view or edit.

For more information on filtered access to third-party data, see Filtering Cloud API access to third-party data in ClaimCenter.

The producerCodes strategy in BillingCenter

This section only applies to BillingCenter.

The producerCodes resource access strategy accepts a set of one or more producer codes.

In the base configuration, each item in the array is a producer code as a string. This string is mapped to a producer code entity in the BillingCenter database. This strategy provides callers with access to entities in BillingCenter that are associated with the producer codes. BillingCenter determines the specific resources that the caller can access based on whether the resources are related to the policy periods on which the provided producer codes earn commission.

For example, suppose a caller made a request with the following JWT.

{
    "groups" : [
        "gwa.prod.bc.Producer_Code"
    ],
    "scp": [
        "bc_producerCodes" 
    ],
    "bc_producerCodes": [
        "bc:33544",
        "bc:29120"
    ]
    ...
}

Based on the bc_producerCodes claim, the caller would have access to resources where one or both of the producer codes bc:33544 and bc:29120 had a business relationship with the resource. For example, the caller can access the producer or producers that have one of or both of these producer codes.

Mapping producer codes in the JWT to BillingCenter producer codes

In the base configuration, BillingCenter attempts to map each item in the bc_producerCodes array to some producer code in the BillingCenter database. It does this by comparing the strings provided in the array to the producerCode entity's code field.

If there is a string that does not match an existing producer code, or if there are strings that match multiple producer codes, BillingCenter throws an error.

You can configure this mapping by providing a custom implementation of the RestV1ExternalProducerCodeAuthHelperPlugin plugin.

Determining resource access

When using the producer code resource access strategy, BillingCenter grants access to resources based on whether the provided producer codes have a business relationship with the target resource.

In many cases, this business relationship is determined based on the producer code's active policy commissions and item commissions. For example, if an account owns a policy that has a policy period on which the producer code earns commission, callers with that producer code are granted access to the account. BillingCenter has built-in logic that determines these associations on a resource-by-resource basis. See Cloud API producer code access by resource for this information.

Large numbers of producer codes and the IExpandTokenPlugin plugin

For some insurers, a single producer can have hundreds of producer codes. The entire set of producer codes may be needed to determine which resources a producer can access. But, there can be performance issues if hundreds of producers are included in the SAML response from the IdP, or if hundreds of producers are included in a JWT that Guidewire Hub creates and hands off to BillingCenter.

To address potential performance issues, Cloud API also supports the IExpandTokenPlugin plugin. This is a plugin that "expands" the information in the JWT with additional information from an external system. The expansion occurs after the JWT has been received from Guidewire Hub but before Cloud API process authorization. Insurers can use this plugin to retrieve additional information relevant to authorization.

Note: Most access information in a JWT can either be included in the SAML response to Guidewire Hub or can be added by the IExpandTokenPlugin plugin. However, if your producer callers require a large number of producer codes, then Guidewire recommends adding the producer codes only through the IExpandTokenPlugin plugin. This helps prevent performance issues that can occur when sending large numbers of values in a SAML response to Guidewire Hub and putting those values in the JWT Guidewire Hub sends to the caller.

Note: Guidewire does not recommend executing calls where the producerCode list has more than 1000 elements. Producer codes are added to the database query's where clause. Database queries begin to degrade when the number of values in the where clause exceeds 1000.

For more information on configuring this plugin, see Configuring the Cloud API IExpandTokenPlugin.

Filtered access to third-party data

For some types of callers, some resources contain data that is third-party data from the perspective of the caller. This applies to external users using the producerCodes strategy.

For example, suppose that Karen Egerston is the primary producer for a policy. There are also secondary and referrer producers on the policy. All three producers can access invoice items on the policy on which they earn commission. However, the secondary and referrer producers are only able to view a limited subset of fields on the invoice items, whereas Karen Egerston is granted full access to the invoice. This is because the full invoice item schema has fields such as primaryCommissionAmount, which isn't supposed to be available to non-primary producers.

To control access to third-party data, Cloud API uses additional accessible fields filters. These filters are expressions that check the business relationship a caller has with each resource. The filter can limit which fields the caller can view or edit.

For more information on filtered access to third-party data, see Filtering Cloud API access to third-party data in ClaimCenter.

The producerCodes strategy in PolicyCenter

This section only applies to PolicyCenter.

The producerCodes resource access strategy accepts an array of one or more producer codes and roles. Each item in the array has the following format: producerCode|producerRole. This strategy provides callers with access to accounts, jobs, and policies associated with the listed producer codes and it enforces the permissions available to the listed roles.

For example, suppose a caller made a request with the following JWT.

{
    "scp": [
        "pc_producerCodes",
        "groups"
    ],
    "pc_producerCodes": [
        "ProducerABC|Producer",
        "ProducerDEF|Producer"
    ],
    "groups": [
        "gwa.lower.pc.External Producer Code"
    ]
}

Based on the pc_producerCodes token, the caller would have access to accounts, jobs, and policies associated with producer codes ProducerABC and ProducerDEF. The caller would also have permission to perform tasks available to those with the Producer role.

The policyNumbers strategy

This section only applies to ClaimCenter.

Note: Guidewire recommends insurers use the cc_contactAuthorizationIds strategy instead of the cc_policyNumbers strategy. The cc_contactAuthorizationIds strategy is more robust, as it provides additional configuration options and is appropriate for both insureds and third-party claimants. The information in the following section is intended for insurers who adopted the cc_policyNumbers strategy prior to the availability of the cc_contactAuthorizationIds strategy.

The policyNumbers resource access strategy requires an array of one or more policy numbers. It provides callers with access to resources associated with claims whose policy number is one of the provided policy numbers. This strategy is not appropriate for third-party claimants, as it assumes the caller is the policyholder of the policies listed in the JWT.

Restricted access to ClaimContacts, incidents, and exposures

This resource access strategy is intended to provide insureds with access to their claims. However, claims often contain information about third parties, such as third-party ClaimContacts, third party vehicles, and third-party exposures. Typically, insureds are not supposed to have access to third-party information.

Therefore, the policyNumbers resource access strategy enforces a special behavior around access to ClaimContacts, incidents, and exposures. Callers can view and edit only the ClaimContacts that are related to the policy with the role of Insured. They can view and edit only the incidents that are related to a ClaimContact that is related to the policy with the role of Insured. And, they can view only the exposures where the claimant is a ClaimContact with the role of Insured. They cannot view any of the following:

Information about ClaimContacts that are not related to the policy (such as a third-party ClaimContact or a vendor).
Information about ClaimContacts that are related to the policy but without this role of Insured (such as an agent).
Information about any incident that is not related to an Insured ClaimContact (such as a third-party incident).
Information about any exposure where the claimant is not a ClaimContact with the role of Insured (such as an exposure for a third-party incident).

For example, suppose Ray Newton files a claim for an accident involving himself and another driver, David Preston. Ray's vehicle is repaired by Sam's Towing and Auto Service. The claim has two vehicle incidents: one for Ray Newton's vehicle and one for David Preston's vehicle. Each incident has an exposure.

Ray Newton can do the following:
- View information about himself, as this ClaimContact is related to the policy with the role of Insured.
- View information about his vehicle incident, as this incident is related to himself, and he is related to the policy with the role of Insured.
- View information about the exposure, as he is listed as the claimant for the exposure, and he has the role of insured.
- Create new ClaimContacts and new incidents.
Ray Newton cannot do the following:
- View or edit information about David Preston
- View or edit information about Sam's Towing
- View or edit information about David Preston's vehicle incident
- View or edit information about any ClaimContacts he created that are not related to the policy with the role of Insured.
- View or edit information about any incidents he created that are not related to a ClaimContact that is an Insured on the policy.
- View information about any exposures where the claimant does not have the role of insured.

The service strategy

Most of the resource access strategies specify restrictions, which limit the resource and fields that a caller can view.

Note: Throughout this section, xc is a placeholder for the application code: cc, pc, or bc.

However, the xc.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 xc.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 xc.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 xc.service resource access strategy is not used. Rather, the call uses the xc_username resource access strategy.