Overview of Cloud API authentication for external users

Endpoint access

Endpoint access defines the aspects of an endpoint's behaviors that are available to a caller. This includes:

• What endpoints and resource types are available to the caller?
• What operations can a caller call on the available endpoint?
• What fields can the caller specify in a request payload or get in a response payload?

Endpoint access is controlled by API roles. An API role is a list of endpoints, operations, and fields that are available to a set of callers through API calls. API roles act as allowlists. By default, a caller has no endpoint access. When the caller is associated with one or more API roles, they gain access to the endpoints, operations, and fields allowlisted in each of those API roles.

For more information on how API roles are configured, see Cloud API endpoint access.

Resource access for external users

Resource access defines, for a given type of resource, which instances of that resource the caller can access. For example, suppose there is a GET /claims endpoint that is available to policyholders, underwriters, adjusters, and service vendors. All of these callers can use the endpoint to access resources whose type is claim, but none of the callers can access all of the claims. For example:

• A policyholder may be able to see only the claims associated with the policies they hold.
• An underwriter may be able to see only the claims for policies assigned to them.
• An adjuster may be able to see only the claims assigned to them.
• A service vendor may be able to see only the claims that have a service request assigned to them.

A resource access strategy is a set of logic that identifies the meaning of a resource access ID. The base configuration includes the following resource access strategies for external users:

When an external user makes a Cloud API call, the InsuranceSuite application checks for a resource access token claim.

• ClaimCenter:
  • If the resource access token is cc_contactAuthorizationIds, the resource access IDs are treated as a list of IDs for one or more contacts. The user is given access to claims and information on those claims where the contact has an appropriate business relationship with the data.
  • If the resource access token is cc_producerCodes, the resource access IDs are treated as a list of producer codes. The user is given access to all claims for which the producer code for the producer of service matches one of the provided values.
  • If the resource access token is cc_gwabuid, the resource access ID is treated as an Address Book identifier. The user is given access to all claims where at least one of the service providers has the ID.
• PolicyCenter:
  • If the resource access token is pc_accountNumbers, the resource access IDs are treated as a list of account numbers. The user is given access to all accounts with these numbers.
  • If the resource access token is pc_producerCodes, the resource access IDs are treated as one or more pair of producer codes and roles (producerCode|role). The user is given access to account, job, and policy APIs where the producer code in the token matches the producer code for the account, job, or policy. And then, the role determines the types of permissions the producers have on the resources.
• BillingCenter:
  • If the resource access token is bc_contactAuthorizationIds, the resource access IDs are treated as a list of IDs for one or more contacts. The user is given access to accounts and information related to those accounts where the contact has an appropriate business relationship with the data.
  • If the resource access token is bc_producerCodes, the resource access IDs are treated as a list of producer codes as strings. The user is given access to resources which they have an appropriate business relationship with. Typically, these are resources related to policy periods on which their producer codes earn commission.

Cloud API requires that the token map have no more than one resource access strategy token.

For more information on how resource access behaves, see Cloud API resource access.

Proxy user access for external users

When a caller makes a Cloud API call, the internal InsuranceSuite application logic may trigger checks that are unrelated to endpoint access or resource access. For example:

• A caller may attempt to assign an activity to themselves. The InsuranceSuite application must check to see if the caller has sufficient permission to own an activity.
• A caller may attempt to create a payment for $2000. ClaimCenter must check to see if the amount of the payment exceeds the caller's authority limit.
• A caller may attempt to create a collision coverage with a deductible less than $1000. PolicyCenter must check to see if the amount of the coverage term is within the caller's authority limit.
• A caller may attempt to create a disbursement for $2000. BillingCenter must check to see if the amount of the disbursement exceeds the caller's authority limit.

External users are not listed in the InsuranceSuite application operational database, and therefore do not have any system permissions or authority limits tied to them. To execute these checks, Cloud API makes use of proxy users. A proxy user is an internal user that is assigned to an external user or service when the API call is made. Whenever internal InsuranceSuite application logic must check to see if the caller has sufficient access, the proxy user is checked.

For more information on how proxy user access behaves, see Cloud API proxy user access.

ClaimCenter examples

Here is an example: the following JWT is for an external user who is a contact whose authorization ID is cc:33544. (Information that is not relevant to Cloud API authorization has been omitted.)

{
    "groups" : [
        "gwa.prod.cc.Insured"
    ],
    "scp": [
        "cc_contactAuthorizationIds"
    ],
    "cc_contactAuthorizationIds": [
        "cc:33544"
    ]
}

Note the following:

• Based on the groups token claim, this caller will be given endpoint access as defined in the role named "Insured".
• Based on the scp token claim, this caller's resource access IDs will be interpreted as contact authorization IDs.
• Based on the cc_contactAuthorizationIds token claim, this caller will have access to information that is visible to contact cc:33544. For example, for a claim where contact cc:33544 is the insured, they are able to see all information about a vehicle where the driver was contact cc:33544. But they would be able to see only a limited amount of information on a vehicle where the driver was a third party (a contact other than cc:33544).

Here is a second example: the following JWT is for a external user who is a vendor. The vendor's Guidewire Address Book unique identifier is cc:demo_4532. (Information that is not relevant to system API authorization has been omitted.)

{
    "groups" : [
        "gwa.prod.cc.ServiceRequestSpecialist"
    ],
    "scp": [
        "cc_gwabuid"
    ],
    "cc_gwabuid": "cc:demo_4532"
}

Note the following:

• Based on the groups token claim, this caller will be given endpoint access as defined in the role named "ServiceRequestSpecialist".
• Based on the scp token claim, this caller's resource access IDs will be interpreted as a Guidewire Address Book unique identifier.
• Based on the cc_gwabuid token claim, this caller will have access to information related to claims where one of the service providers is a contact whose ID is cc:demo_4532.

PolicyCenter examples

Here is an example: the following JWT is for an external user who is a policyholder with two accounts: C000456352 and C000456377. (Information that is not relevant to Cloud API authorization has been omitted.)

{
    "groups" : [
        "gwa.prod.pc.Account_Holder"
    ],
    "scp": [
        "pc_accountNumbers"
    ],
    "pc_accountNumbers": [
        "C000456352",
        "C000456377"
    ]
}

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

BillingCenter examples

Here is an example: the following JWT is for a external user who is a contact whose authorization ID is bc:33544. (Information that is not relevant to Cloud API authorization has been omitted.)

{
    "groups" : [
        "gwa.prod.bc.Account_Contact"
    ],
    "scp": [
        "bc_contactAuthorizationIds"
    ],
    "bc_contactAuthorizationIds": [
        "bc:33544"
    ]
}

Note the following:

• Based on the groups token claim, this caller will be given endpoint access as defined in the role named "Account_Contact".
• Based on the scp token claim, this caller's resource access IDs will be interpreted as contact authorization IDs.
• Based on the bc_contactAuthorizationIds token claim, this caller will have access to information that is accessible to contact bc:33544. For example, if the user is accessing an account and if contact bc:33544 is the account owner, they have view and edit access to the account. But, if contact bc:33544 is only an account payer and not the account owner, they have view only access to the account.

{
    "scp": [
        "bc_producerCodes"
    ],
    "bc_producerCodes": [
        "ProducerCode1"
    ],
    "groups": [
        "gwa.lower.bc.Producer_Code"
    ]
}