Overview of authentication for services with service account mapping

Endpoint access for services with service account mapping

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-service-account-mapping call, the system APIs map the service to a service account in the PolicyCenter database. Then, PolicyCenter queries the operational database for this service account's user roles. The service is given endpoint access to all API roles whose names corresponds to the names of the service account's user roles.

For example, suppose that the ACME QuoteAndBind service is mapped to a service account named "acmeQuoteAndBind". The acmeQuoteAndBind account has two user roles: "ACME Underwriter" and "ACME Reinsurance Manager". The ACME QuoteAndBind service triggers a system API call. PolicyCenter maps the service to the acmeQuoteAndBind account and queries the database for the service account's user roles. Two user roles are returned: "ACME Underwriter" and "ACME Reinsurance Manager". PolicyCenter then gives the service the endpoint access defined in the API roles named "ACME Underwriter" and "ACME Reinsurance Manager".

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

Resource access for services with service account mapping

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.

Resource access is controlled by two features: resource access IDs and resource access strategies.

A resource access ID is a string that defines who the caller is or what the caller owns. Resource access IDs are used to determine which resources an authenticated caller has access to through API calls.

• A resource access ID can identify who the caller is. For example, the resource access ID for a service provider is the provider's Address Book ID. Typically, a service provider can access all claims which include this ID in the list of associated contact IDs.
• A resource access ID can identify what the caller owns. For example, the resource access ID for a policyholder is a list of one or more policy numbers. Typically, a policyholder can access all policies with those policy numbers.

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 service account:

When a service makes a service-with-service-account-mapping call, the service is mapped to a service account name. This account name is used as the resource access ID, and the pc_username strategy is used. 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 services with service account mapping

Proxy user access is not applicable for services with service account mapping. The service account is used as the user for the session. Therefore, even though the call is coming from a service, there is no need to assign a proxy user.

Service account mapping

The service account mapping is a set of name/value pairs that map a service's client ID to the name of a user in the PolicyCenter database. This user is referred to as the service account.

When a service call is received, Cloud API checks to see if the client ID is listed in the service account mapping.

• If the client ID is found, the call is treated as a service-with-service-account-mapping call. The service account becomes the session user, and the access associated with the service account defines what the service can do.
• If the client ID is not found, the call is treated as either a service-with-user-context call or a standalone service call.

For example, suppose the following service account mapping exists.

Suppose a call is received from a service with a client ID of "0oaqt9pl1vZK1kybt0h7". This client ID exists in the service account mapping. Therefore, the call is treated as a service-with-service-account mapping call. The call is associated with the service account whose user name is acmeDocuments.

Similarly, suppose a call is received from a service with a client ID of "0oa33344455566677788". This client ID does not exist in the service account mapping. Therefore, the call is treated as either a service-with-user-context call or a standalone service call.

Every service has a single client ID. Therefore, for a given service, either all calls are treated as service-with-service-account-mapping calls, or none of the calls are treated as service-with-service-account-mapping calls. If the client ID is in the service account mapping, it is the former. If not, it is the latter.

Storing service account mapping

Service account mapping can be stored in different locations. For every service call, Cloud API checks all locations. Cloud API uses the first mapping it finds. So, if a client ID is mapped in multiple places, only the first mapping is used. If a client ID is not listed in any of these locations, Cloud API treats the call as a either a service-with-user-context call or a standalone service call.

From a technical perspective, service account mappings can be spread out across all of these locations. However, insurers may find it easier to manage service account mappings if a single location is used.

Storing service account mapping: Guidewire Cloud Console

The first place Cloud API checks is the Guidewire Cloud Console (GCC) configuration variables. Insurers can make these changes on their own through the GCC user interface.

Service mapping entries in GCC configuration variables use the following syntax:

PLUGIN_AUTHENTICATIONVERIFIER_SUBJECTMAPPINGS_<sub>=<username>

where:

• <sub> is the value of the JWT's sub token claim (which is set to the client ID).
• <username> is the user name of the service account.

To deploy changes to GCC configuration variables, you must restart the server.

Storing service account mapping: config.properties

The next place Cloud API checks is in the config.properties file. Entries in this file use the following syntax:

plugin.PLUGIN_AUTHENTICATIONVERIFIER_SUBJECTMAPPINGS_<sub>=<username>

where:

• <sub> is the value of the JWT's sub token claim (which is set to the client ID).
• <username> is the user name of the service account.

To deploy changes to the config.properties file, you must restart the server.

Storing service account mapping is config.properties may be appropriate in development instances. But, Guidewire does not recommend storing service account mapping is config.properties in production instances.

The service account

A service account is intended to be used only by a single external service making Cloud API calls. Typically, the service account name reflects the service (such as acmeDocuments) and does not look like a person account name (such as aapplegate).

The service account needs to have the permissions appropriate for the service.

Guidewire recommends to not use service accounts for user activity. In other words, do not have users log on to PolicyCenter using a service account.