Configuring the IExpandTokenPlugin plugin

The getTokenExpansions method

When a Cloud API call using bearer token authentication is received, PolicyCenter extracts the information from the JWT into a "token map". Then, it calls the getTokenExpansions method. This method returns a "token expansions map" which contains the key/value pairs to add to the initial token map, or to override in the initial token map.

• If the token expansions map specifies a claim that is not in the original token map, Cloud API adds it to the original token map.

• If the token expansions map specifies a claim that is already in the original token map, Cloud API replaces the original claim with the expansions claim. Thus, if a given claim must have both values from the JWT and values retrieved from the external system, this method must merge the two sets into a single claim.

override function getTokenExpansions(map : Map<String, Object>) : Map<String, Object> {
 return map
}

The method receives the original token map in the map object, which contains all the key/value pairs from the JWT as received from the caller.

The method must do the following:

1. Extract any appropriate lookup values from the original token map

2. Call the appropriate system of record to retrieve the relevant additional authorization values

3. Construct a "token expansions" map return value that specifies all claims to add to the original token map, and all claims already in the original token map that must be replaced

The method cannot return null. If there are no required changes, return an empty map.

Formats for values in the token expansions map

For internal users, there is no need to specify API roles in either the JWT or the token expansions map. API roles are retrieved by querying the database for the user roles assigned to the user. For more information, see OAuth2 authorization code flow: Internal users.

For external users, API roles must be specified in either the JWT or the token expansions map. When they are specified in the expansions map:

• The key must be set to "groups".

• The value must be of type List<String>, where each string has the following format:

  • It starts with "gwa.<planetclass>.pc.", where <planetclass> is set to either "prod", "preprod", or "lower".

  • It ends with the Cloud API role name.

"groups": [
  "gwa.prod.pc.Account_Holders"
]

Resource access IDs

For both internal and external users, resource access IDs must be specified in either the JWT or the token expansions map. When they are specified in the expansions map:

• The key must be set to the name of the resource access strategy. This must be one of the following:

  • pc_username
  • pc_accountNumbers

• If the resource access strategy requires a single resource access ID, the key's value must be set to that ID.

• If the resource access strategy permits one or more resource access IDs, the key's value must be set to an array storing the IDs.

"pc_username": "aapplegate@acme.com"

"pc_accountNumbers": [
  "C000123",
  "C000456"
]

Performance considerations

This plugin is called during Cloud API authentication. Guidewire recommends that insurers confirm that the SLA with their authorization system of record is sufficient for such a heavily used case.

Guidewire recommends against adding more than 1000 elements in a List or Array that is the value for a key. Such a large number of entries can result in performance issues when GenericCenter passes queries to the database that contain filtering logic with more than 1000 values.

The getTokenExpansions method example: producer codes

For callers using the producerCodes access strategy, suppose you store producer codes in an external producer system. In order to identify the correct producer codes to grant to a caller, the external system must have uniquely identifying information about the caller, such as the value in the caller's sub claim.

"sub": "kegerston@allrisk.com",
"scp": [
  "cc_producerCodes",
  "tenant.acme",
  "project.default",
  "planet_class.prod"
],
"groups": [
  "gwa.prod.cc.Producer"
],

The method then does the following:

1. Extracts the lookup value (kegerston@allrisk.com)

2. Sends this value to the external producer system

3. Puts the returned values in an expansion tokens map with a cc_producerCodes claim.

"cc_producerCodes": [
  "100-002541",
  "100-002542",
  "100-002543"
]

"sub": "kegerston@allrisk.com",
"scp": [
  "cc_producerCodes",
  "tenant.acme",
  "project.default",
  "planet_class.prod"
],
"groups": [
  "gwa.prod.cc.Producer"
],
"cc_producerCodes": [
  "100-002541",
  "100-002542",
  "100-002543"
]

Example implementation

package gw.acme.rest.internal.pc.dgc.plugin

uses gw.api.modules.rest.framework.v1.plugin.security.IExpandTokenPlugin

uses javax.annotation.Nonnull

class ExpandTokenDGCPlugin implements IExpandTokenPlugin {

  @Nonnull
  override function getTokenExpansions(map : Map<String, Object>) : Map<String, Object> {

    //Map to be merged to original one
    var dgcMap = new HashMap<String, Object>()
    dgcMap.put("groups", {"gwa.dev.cc.Producer"})
    dgcMap.put("cc_producerCodes", {"100-002541"})
    dgcMap.put("cc_producerCodes", {"100-002542"})
    dgcMap.put("cc_producerCodes", {"100-002543"})

    return dgcMap
  }
}