Cloud API authentication flow for services with user context

The following diagram identifies the flow of authentication and authorization information for services with user context. Colors are used in the following ways:

  • Orange - credentials information
  • Blue - endpoint access information
  • Green - resource access information
  • Red - proxy user and session user information

Some values are used to determine multiple types of access. These values initially appear as black (when they do not apply to a single type of access), and then later appear in one or more specific colors (to reflect the value is being used at that point in the process for a specific type of access).

Services with user context: internal users

Here is a ClaimCenter example: an API call is triggered by the Acme FNOLReporter service on behalf of Andy Applegate, who is an internal user (an adjuster).


Authentication flow for services with internal user context
  1. When FNOLReporter triggers an API call, it must first request a JWT from Guidewire Hub. The request for the JWT includes the client ID (0oaqt9pl1vZK1kybt0h7), the secret (aSecret), the application's API role (scp.cc.acme_fnolreporter), the application's resource access strategy (cc.service), the fact that the call will be made for a user (cc.allowusercontext) and additional deployment information (tenant.acme, project.default, planet_class.prod).
  2. Guidewire Hub authenticates the services based on the client ID and secret. It also verifies that the API role and resource access strategy provided in the request match what was specified when the service was registered with Guidewire Hub.
  3. Guidewire Hub generates a JWT and sends it to the service. This JWT includes the client ID (cid) and a scp token claim which names the API role (scp.cc.acme_fnolreporter), the resource access strategy (cc.service), the cc.allowusercontext value (which indicates that user information is specified in an additional user context header), and additional deployment information.
  4. The service sends the API request to ClaimCenter along with the JWT and a user context header that identifies the user (aapplegate@acme.com), the user's resource access strategy (cc_username), and resource access ID (aapplegate@acme.com).
  5. ClaimCenter extracts the information in the JWT into a token map. Then, the IExpandTokenPlugin plugin calls any relevant authorization applications to retrieve any relevant additional auth values that must be added to or modified in the token map. (The IExpandTokenPlugin plugin can affect only the information that normally comes in the JWT. It cannot affect information in a user context header. Therefore, for services with user context, an insurer could choose to retrieve either the service's API role (such as scp.cc.acme_fnolreporter) or the service's resource access strategy name (cc.service) using the IExpandTokenPlugin plugin. But the API roles and resource access IDs for the user must be in the user context header when the call is sent to ClaimCenter.)
  6. ClaimCenter must determine the endpoint access at both the service level and the user level. It starts at the service level. Based on the API role value in the JWT (scp.cc.acme_fnolreporter), the acme_fnolreporter.role.yaml API role file is used to define the service-level access.
  7. Next, ClaimCenter determines the user-level endpoint access.
    1. Using the user name in the user context header (aapplegate@acme.com), ClaimCenter queries for the user roles that this user has. One role is returned: Adjuster.
    2. Based on the returned role, the Adjuster.role.yaml API role file is used to define the user-level access.
  8. ClaimCenter must also determine the resource access at the service level and the user level. It starts with the service-level resource access strategy. Based on the resource access strategy value in the JWT (cc.service), it grants service-level resource access as defined in the serviceUser access.yaml files. (* ClaimCenter starts with serviceUser_ext-1.0.access.yaml, but this file references additional access.yaml files whose name starts with "serviceUser".)
  9. ClaimCenter determines the user-level resource access strategy. Based on the resource access strategy value in the user context header (cc_username), it grants user-level resource access as defined in the internal access.yaml files. (* ClaimCenter starts with internal_ext-1.0.access.yaml, but this file references additional access.yaml files whose name starts with "internal".)
  10. Proxy user access is not relevant for services with user context when the user is an internal user.
  11. ClaimCenter processes the request.
    1. The session user is the internal user: aapplegate@acme.com.
    2. The endpoint access is the intersection of the endpoints and operations defined granted at the service level (acme_fnolreporter.role.yaml) and at the user level (Adjuster.role.yaml). Endpoints, operations, and fields must be listed at both levels to be available to the call.
    3. The resource access is the intersection of the resources accessible to the service (as defined in the serviceUser access.yaml) and the resources available to the user (as defined in the internal access.yaml using the resource access ID of aapplegate@acme.com). In the base configuration, the serviceuser access.yaml files make all resources available. Therefore, logically speaking, the service-level resource access does not specify any restrictions. The call can access any resource provided it is available through the user-level resource access.
  12. ClaimCenter provides the response to the initial call.
Note: This ClaimCenter example uses the acme_fnolreporter.role.yaml and Adjuster.role.yaml file because those roles would be relevant to ClaimCenter. A relevant example of an intersection between role for PolicyCenter could be between acme_billingapp.role.yaml and Underwriter.role.yaml, and a elevant example of an intersection between relevant role file for BillingCenter could be between acme_lockbox.role.yaml and BillingRep.role.yaml.

Services with user context: external users

Here is another ClaimCenter example: an API call is triggered by the Acme FNOLReporter service on behalf of Ray Newton, who is an external user.


Authentication flow for services with external user context
  1. When FNOLReporter triggers an API call, it must first request a JWT from Guidewire Hub. The request for the JWT includes the client ID (0oaqt9pl1vZK1kybt0h7), the secret (aSecret), the application's API role (scp.cc.acme_fnolreporter), the application's resource access strategy (cc.service), the fact that the call will be made for a user (cc.allowusercontext) and additional deployment information (tenant.acme, project.default, planet_class.prod).
  2. Guidewire Hub authenticates the services based on the client ID and secret. It also verifies that the API role and resource access strategy provided in the request match what was specified when the service was registered with Guidewire Hub.
  3. Guidewire Hub generates a JWT and sends it to the service. This JWT includes the client ID (cid) and a scp token claim which names the API role (scp.cc.acme_fnolreporter), the resource access strategy (cc.service), the cc.allowusercontext value (which indicates that user information is specified in an additional user context header), and additional deployment information.
  4. The service sends the API request to ClaimCenter along with the JWT and a user context header that identifies the user (rnewton@email.com), the user's resource access strategy (cc_contactAuthorizationIds), and resource access ID (ctc-11450).
  5. ClaimCenter extracts the information in the JWT into a token map. Then, the IExpandTokenPlugin plugin calls any relevant authorization applications to retrieve any relevant additional auth values that must be added to or modified in the token map. (The IExpandTokenPlugin plugin can affect only the information that normally comes in the JWT. It cannot affect information in a user context header. Therefore, for services with user context, an insurer could choose to retrieve either the service's API role (such as scp.cc.acme_fnolreporter) or the service's resource access strategy name (cc.service) using the IExpandTokenPlugin plugin. But the API roles and resource access IDs for the user must be in the user context header when the call is sent to ClaimCenter.)
  6. ClaimCenter must determine the endpoint access at both the service level and the user level. It starts at the service level. Based on the API role value in the JWT (scp.cc.acme_fnolreporter), the acme_fnolreporter.role.yaml API role file is used to define the service-level access.
  7. Next, ClaimCenter determines the user-level endpoint access. Based on the contents of the groups token claim in the user context header (gwa.prod.cc.Claimant), the Claimant.role.yaml API role file is used to define the user-level access.
  8. ClaimCenter must also determine the resource access at the service level and the user level. It starts with the service-level resource access strategy. Based on the resource access strategy value in the JWT (cc.service), ClaimCenter grants service-level resource access as defined in the serviceUser access.yaml files. (* ClaimCenter starts with serviceUser_ext-1.0.access.yaml, but this file references additional access.yaml files whose name starts with "serviceUser".)
  9. Next, ClaimCenter determines the user-level resource access strategy. Based on the resource access strategy value in the user context header (cc_contactAuthorizationIds), it grants user-level resource access as defined in the contactAuthorizationIds access.yaml files. (* ClaimCenter starts with contactAuthorizationIds_ext-1.0.access.yaml, but this file references additional access.yaml files whose name starts with "contactAuthorizationIds".)
  10. To determine which proxy user to assign to the session, ClaimCenter calls the RestAuthenticationSourceCreator plugin. The user context header specified a resource access strategy of cc_contactAuthorizationIds. So, the plugin returns the proxy user for external users: extuser.
  11. ClaimCenter processes the request.
    1. The session user is the proxy external user: extuser.
    2. The endpoint access is the intersection of the endpoints and operations defined granted at the service level (acme_fnolreporter.role.yaml) and at the user level (Claimant.role.yaml). Endpoints, operations, and fields must be listed at both levels to be available to the call.
    3. The resource access is the intersection of the resources accessible to the service (as defined in the serviceUser access.yaml) and the resources available to the user (as defined in the contactAuthorizationIds access.yaml using the resource access ID of ctc-11450). In the base configuration, the serviceUser access.yaml files make all resources available. Therefore, logically speaking, the service-level resource access does not specify any restrictions. The call can access any resource provided it is available through the user-level resource access.
  12. ClaimCenter provides the response to the initial call.
Note: This ClaimCenter example uses the acme_fnolreporter.role.yaml and Claimant.role.yaml file because those roles would be relevant to ClaimCenter. A relevant example of an intersection between role for PolicyCenter could be between acme_billingapp.role.yaml and Account_Holder.role.yaml, and a elevant example of an intersection between relevant role file for BillingCenter could be between acme_lockbox.role.yaml and Account_Contact.role.yaml.