Overview of authentication for services with user context

Credentials

When a service makes an API call, the service sends a client ID and secret to Guidewire Hub. Guidewire Hub authenticates the service by confirming that the client secret is correct. This is true for standalone services, services with user context, and services with service account mapping.

When a service authenticates with user context, it provides information about a user. However, there is no authentication at the user level. Authentication occurs only at the service level.

For more information on how client IDs and secrets are registered with Guidewire Hub, see Registering the caller application with Guidewire Hub.

Authorization

Endpoint access for services with user context

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 a service-with-user-context call, the system APIs check two sets of API roles:

The API roles assigned to the service
The API roles assigned to the user

The endpoint access granted to the call is the intersection of the endpoint access granted by these two sets. In other words, in order to access an endpoint, operation, or field, the access must be granted to at least one API role assigned to the service and at least one API role assigned to the user account.

For example, suppose that the ACME External Document Manager service has the following API role with the following endpoint access:

acme_externaldocumentmanager
- GET /documents
- POST /documents

And, suppose that Ray Newton has the following API role with the following endpoint access:

Insured
- GET /documents
- GET /coverages

Suppose ACME External Document Manager service makes a call as a service with user account using the Ray Newton user account. The call would have access to GET /documents, as this endpoint has been granted to both the service and the user account. The call would not have access to either POST /documents or GET /coverages, as neither of these endpoints have been granted to both the service and the user account.

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

Resource access for services with user context

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 which resources a caller can access. The base configuration includes resource access strategies for users and services.

Resource access strategies for users typically restrict the caller to objects owned by the user. For example, an account holder can see objects owned (directly or indirectly) by the account.
Resource access strategies for services typically do not restrict the caller in any way.

Similar the endpoint access, the resource access for a service-with-user-context call is the intersection of the resource access for the service and the resource access for the user. In the base configuration, services have access to all resources. Therefore, the resource access for a service-with-user-context call is logically equivalent to the resource access for the user.

For example, suppose that the ACME External Document Manager service has access to the following documents:

(all documents)

And, suppose that Ray Newton has access to the following documents:

Documents associated with policy 55-123456
- Document xc:127
- Document xc:356
Documents associated directly with account C000324667
- Document xc:888

If ACME External Document Manager service makes a service-with-user-account call for Ray Newton, the call would have access to document xc:127, xc:356, and xc:888, as these resources can be accessed by both the service and the user. The call would not have access to any other documents, as there are no other documents that both the service and the user have access to.

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

Proxy user access for services with user context

Every Cloud API call occurs within the context of a session. A user listed in the PolicyCenter database must be attached to this session. PolicyCenter can use this "session user" in different ways.

If the call creates or modifies an object, the session user is recorded as the CreateUser or UpdateUser of that object.
If the call triggers an authority limit check, the session user's authority limits are checked.
There is a small chance the call could trigger logic that must check to see if the caller has a specific domain-level system permission, such as the permission to own an activity. When this occurs, the session user's system permissions are checked.

When a service makes a call with a user context, the associated user could be an internal user. An internal user is a person who is listed as a user in the PolicyCenter operational database. In this case, that internal user is used as the session user.

When a service makes a call with a user context, the associated user could be an external user. 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. For example, this could be a policyholder, vendor, or account holder. When the user context specifies an external user, a proxy user must be assigned to the session.

A proxy user is an internal user that is assigned to a session for an API call made by an external user or service. Proxy users are assigned by the RestAuthenticationSourceCreatorPlugin plugin. This plugin specifies four proxy users. One of them, the proxy external user, is used for calls made either by external users or by services with user context where the user context specifies an external user.

For more information on proxy users, see Proxy user access.

JWTs for services with user context

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.

When a service makes a call with user context, only some of the information in the JWT is specific to Cloud API authentication. The following are the token claims in a JWT for a service-for-user-context call that pertain to Cloud API authentication.

"sub": "<clientId>",
"cid": "<clientId>", 
"scp": [
  "pc.service",
  "scp.pc.<serviceAPIRole>",
  "pc.allowusercontext"
]

sub is the subject of the token. This is set to the service's client ID.
cid is the client ID of the service. This is also set to the service's client ID.
The scp token claim has at least the following entries:
- The pc.service value, which specifies the caller is a service.
- A list of one or more API roles associated with the service. These roles are prefixed with "scp.pc.".
- The pc.allowusercontext value, which allows the call to specify additional user context in the header. (If the header contains a GW-User-Context header, then this is treated as a service-with-user-context call and not a standalone service call).

The pc.allowusercontext value indicates that the call is also presenting a user context. Information about the user is specified in a GW-User-Context header. For internal users, the header must specify the user name and the resource access strategy and resource access IDs. For external users, the header must specify the user name, the user roles, and the resource access strategy and resource access IDs. The header must be base64-encoded.

The header must be a JSON payload that is formatted as described in the following paragraphs.

For an internal user, the syntax of the GW-User-Context header is:

{
  "sub": "<userName>",
  "pc_username" : "<userName>"
}

Note the following:

The user name is specified in the sub token claim.
The resource access strategy is specified by the presence of the pc_username token claim.
The resource access ID is the user's name, which is specified within the pc_username token claim.

For an external user who is an account holder, the syntax of the GW-User-Context header is:

{
  "sub": "<userName>",
  "groups": [
    "<userAPIroleList>"
  ],
  "pc_accountNumbers" : [
    "<accountNumbers>"
  ]
}

Note the following:

The user name is specified in the sub token claim. (This is used for logging, but otherwise it has no functional impact.)
The user's API roles are listed in the groups token claim. Every role name must be prefixed with "gwa.<planet_class>.pc.".
The resource access strategy is specified by the presence of the pc_accountNumbers token claim.
The resource access IDs are a list of account numbers, which are specified within the pc_accountNumbers token claim.

Note: If a call includes a JWT with the pc.allowusercontext token claim, but the request object's header does not contain a user context header, Cloud API treats the call as if it were coming from a standalone service. In other words, the call will be restricted to the access provided to the service. No user-based restrictions are applied because there was no user context header specifying a user.

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`	If the user in the user context is an internal user, the user name of the internal user. If the user in the user context is an external user, the `sub` value from the user context.