Sending authenticated calls for services with user context

Requesting codes and JWTs from Guidewire Hub

For more information on how to request JWTs from Guidewire Hub, refer to Authentication with Guidewire Identity Federation Hub in the Guidewire Cloud Platform documentation set.

Including JWTs with API calls

Once a JWT has been received from Guidewire Hub, it must be sent to PolicyCenter in the request object's Authorization header. The header must use this format:

Authorization: Bearer <token>

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.

Including the GW-UserContext header with API calls

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.
- Must be base64-encoded
For external users, the header:
- Must specify the user name, the user roles, and the resource access strategy and resource access IDs
- Must be base64-encoded

Syntax for the JSON object

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.

Making the JSON object base64-encoded

The JSON object cannot be added to the header as JSON. It must be base64-encoded.

For example, suppose you had the following JSON object for internal user aapplegate:

{
        "sub": "aapplegate@acme.com",
        "pc_username" : "aapplegate@acme.com"
        }

The header must contain the base64-encoded version of this object, as shown below.

ewogICJzdWIiOiAiYWFwcGxlZ2F0ZUBhY21lLmNvbSIsCiAgInBjX3VzZXJuYW1lIiA6ICJhYXBw
        bGVnYXRlQGFjbWUuY29tIgp9

Adding the base64-encoded object to the header

Finally, this object must be attached to a request header named "GW-User-Context". For example, if you were sending the previous request through Postman, the values would be as follows:

Key: GW-User-Context
Value: ewogICJzdWIiOiAiYWFwcGxlZ2F0ZUBhY21lLmNvbSIsCiAgInBjX3VzZXJuYW1lIiA6ICJhYXBw bGVnYXRlQGFjbWUuY29tIgp9

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.

Authentication failure error messages

For endpoints that return an individual element, when the resource exists but the user lacks authorization to access it, Cloud API throws the following user message. This is the same message that is returned when the resource does not exist.

"status": 404,
        "errorCode": "gw.api.rest.exceptions.NotFoundException",
        "userMessage": "No resource was found at path <path>"

For endpoints that return collections, Cloud API returns all resources that meet the criteria and for which the user has sufficient resource access. If a resource exists, but the user lacks sufficient authorization, Cloud API omits it from the results.

These approaches are considered to be more secure as they prevent malicious callers from being able to verify the existence of data that they are not authorized to access.