Overview of authentication for external users

Credentials

An external user's credentials consist of a user name and password. This information is stored in the IdP.

When an external user makes an API call, the caller application sends the user's credentials to Guidewire Hub. Guidewire Hub federates this information to the appropriate IdP. The IdP authenticates the user by confirming that the password is correct.

For more information on how to configure the IdP, see Configuring the IdP.

Authorization

Endpoint access for external users

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.

When an external user makes a system API call, the call includes a JWT. The JWT includes a list of one or more API roles. The user is given endpoint access to all API roles whose names correspond the roles listed in the JWT. For example, suppose that Ray Newton is a policyholder. Ray Newton triggers a system API call. The JWT identifies the Insured role. Ray Newton is given the endpoint access defined in the API role named "Insured".

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

Resource access for external users

Resource access defines, for a given type of resource, which instances of that resources 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:


Strategy name	Persona using this strategy	The resource access ID is assumed to be...	Grants access to...
`cc_policyNumbers`	Account holders and policy holders	An array of policy numbers	Information associated with any claims associated with any of the policies.
`cc_gwabuid`	Claims service providers	An ABUID (Address Book Unique IDentifier) of the service provider contact	Information associated with any claims for which this user is the assigned service provider

When an external user makes a system API call, ClaimCenter checks for a resource access token claim.

If the resource access token is cc_policyNumbers, the resource access IDs are treated as a list of policy numbers. The user is given access to all claims based on any of those policy numbers.
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.

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

If no resource strategy token is present, the caller is assigned the "default" resource access strategy. This resource strategy grants access to metadata endpoints only.
If multiple resource strategy tokens are present, the call is rejected.

For more information on how resource access behaves, see Resource access.

Proxy user access for external users

When a caller makes a system API call, the internal ClaimCenter 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. ClaimCenter 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.

External users are not listed in the ClaimCenter operational database, and therefore do not have any system permissions or authority limits tied to them. To execute these checks, the system APIs make 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 ClaimCenter 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 Proxy user access.

JWTs for external users

JSON Web Tokens (JWTs) contain token claims. (In standard JWT parlance, these are referred to simply as "claims". To avoid confusion with claims in the property and casualty insurance sense, this documentation always refers to JWT claims as "token claims".) A token claim is a piece of information asserted about the bearer of the token, such as the bearer's name. For bearer token authentication, authentication information is stored in token claims.

JWTs for external users can include the following token claims:

groups - The API roles to assign to the external user.
- In this token claim, the group name is prefixed by "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").
scp - The resource access strategy to apply to the resource access IDs
cc_policyNumbers - The resource access IDs (when scp includes cc_policyNumbers)
cc_gwabuid - The resource access IDs (when scp includes cc_gwabuid)

For example, the following JWT is for a external user who is a policyholder with two policies: 54-123456 and 54-273411. (Information that is not relevant to system API authorization has been omitted.)

{
    "groups" : [
        "gwa.prod.cc.Insured"
    ],
    "scp": [
        "cc_policyNumbers"
    ],
    "cc_policyNumbers": [
        "54-123456",
        "54-273411"
    ]
}

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 policy numbers.
Based on the cc_policyNumbers token claim, this caller will have access to information related to claims on either policy 54-123456 or policy 54-273411.

As 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.

Logging

For each call, information about the caller is logged. The following table lists the fields that provide information about who the caller is, and where the logged value comes from.


Field	Value
`sub`	The value of the `sub` token claim from the JWT
`clientId`	The value of the `cid` token claim from the JWT
`user`	The user name of the external user