Overview of authentication for internal users

Authentication includes credentials and authorization. Authentication information for internal users (using bearer token authentication) is specified in JWTs, and information from these JWTs is recorded in the logs.

Credentials

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

When an internal 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 internal 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 internal user makes a system 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 corresponds 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 system 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".

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

Resource access for internal 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 internal users:

Strategy name Persona using this strategy The resource access ID is assumed to be... Grants access to...
pc_username Internal users A PolicyCenter user name Any information this internal user could see in PolicyCenter based on their associated Access Control Lists (ACLs).

When an internal user makes a system API call, the user's user name is included in the JWT. The user name is used as the resource access ID. The cc_username or pc_username strategy is used automatically. This strategy consists of system API logic that matches, as closely as possible, the user's access as defined in the base configuration's Access Control Lists (ACLs).

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

Proxy user access for internal users

Proxy user access is not applicable for internal users.

JWTs for internal 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 internal users can include the following token claims:

  • scp - The resource access strategy to apply to the resource access ID. (For internal users, this is set to pc_username.)
  • pc_username - The resource access ID. (This is the user's user name)

For example, the following JWT is for an internal user whose user name is aapplegate. (Information that is not relevant to system API authorization has been omitted.) 

{
    "scp": [
        "pc_username"
    ],
    "pc_username": "aapplegate"
}

Note the following:

  • Based on the scp token claim, this caller's resource access ID will be interpreted as a user name.
  • Based on the pc_username token claim, this caller will have access to information related to what the user aapplegate can access.

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 internal user