Overview of authentication for standalone services

Authentication includes credentials and authorization. Authentication information for services is specified in JWTs, and information from these JWTs is recorded in the logs.

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.

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 standalone services

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.

Theoretically, a standalone service can be associated with multiple API roles. Typically, insurers create one API role for each service and this role is used only by this service.

For a standalone service call, Cloud API checks the API role or roles assigned to the service. The call has access to the endpoints, operations, and fields specified in those roles. 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

Then, suppose ACME External Document Manager service makes a standalone service call. The call would have access to GET /documents and POST /documents. But if there was a DELETE /documents endpoint, the call would not have access to it because it has not been specified in the acme_externaldocumentmanager role.

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

Resource access for standalone services

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 standalone services. But, these strategies do not involve resource access IDs or restrict the service in any way. Once a service is given access to a set of endpoints, the service can access any resource available to those endpoints. These applications are expected to be configured such that they access only the resources appropriate for the circumstance.

Strategy name Persona using this strategy The resource access ID is assumed to be... Grants access to...
pc.​service Services Not applicable All resources

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

Proxy user access for standalone services

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.

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 service user, is used for calls made by standalone services.

  • If the call creates or modifies an object, the proxy service user is recorded as the CreateUser or UpdateUser of that object.
  • If the call triggers an authority limit or domain-level system permission, the limits and permissions of the proxy service user are checked.

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

JWTs for standalone services

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 sometimes 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 standalone service call, 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 standalone service call that pertain to Cloud API authentication.

"sub": "<clientId>",
"cid": "<clientId>", 
"scp": [
  "pc.service",
  "scp.pc.<serviceAPIRole>"
]
  • 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.".

For example, the following JWT is for ACME's external billing application. (Information that is not relevant to Cloud API authorization has been omitted.) 

{
    "sub": "acme_externalbillingapp",
    "cid": "acme_externalbillingapp",
    "scp": [
        "pc.service"
        "scp.pc.acme_externalbillingapp"
    ]
}

Note the following:

  • Based on the scp token claim, this caller will be given endpoint access as defined in the role named "acme_externalbillingapp". Because of the pc.service entry, this caller uses a resource access strategy that provides access to all resources.

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 An empty string