Example flow for external users

The following diagrams identify the flow of authentication and authorization information for external users. 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).

External contact authorization ID example

In the following example, an API call is triggered by Ray Newton, who is an external user, using a browser-based application.


Authentication flow for external contact authorization id users
  1. When Ray triggers an API call, the caller application must first request a JWT from Guidewire Hub. To initiate the process of getting the JWT, the caller application submits its client ID (00ubx7m33sHP1tsew7b4), the ID of the IdP (acmeIdP_ID), the application's resource access strategy (bc_contactAuthorizationIds), and additional deployment information (tenant.acme, project.default, planet_class.prod).
  2. Guidewire Hub sends a request to the appropriate IdP to authenticate the user. The IdP authenticates the user and provides a SAML response with information about the user, such as the user's name (rnewton@email.com). If API roles and/or resource access IDs are stored in the IdP, the SAML response may also include this information (such as the role gwa.prod.bc.Account_Contact or the resource access ID ctc-11450).
  3. Guidewire Hub sends a code to the caller application. The caller application uses this code to request a JWT.
  4. Guidewire Hub generates a JWT and sends it to the caller application. This JWT includes the client ID (cid), a scp token claim which names the resource access strategy (bc_contactAuthorizationIds) and additional deployment information. The JWT also contains any relevant information Guidewire Hub received in the SAML response, such as a groups token which names the user's API roles (gwa.prod.bc.Account_Contact), or a bc_contactAuthorizationIds token which names the user's resource access IDs (ctc-11450).
  5. The caller application sends the API request to BillingCenter along with the JWT.
  6. BillingCenter 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. (For external users, this could include API roles and/or resource access IDs that are not stored in the IdP.)
  7. BillingCenter determines the endpoint access. Based on the groups listed in the token map (gwa.prod.bc.Account_Contact), the Account_Contact.role.yaml API role file is used to define the endpoint access.
  8. Next, BillingCenter determines the resource access strategy. Based on the resource access strategy value in the token map (bc_contactAuthorizationIds), it grants resource access as defined in the contactAuthorizationIds access.yaml files. (* BillingCenter starts with contactAuthorizationIds_ext-1.0.access.yaml, but this file references additional access.yaml files whose name starts with "contactAuthorizationIds".)
  9. To determine which proxy user to assign to the session, BillingCenter calls the RestAuthenticationSourceCreator plugin. The token map specified a resource access strategy of bc_contactAuthorizationIds. So, the plugin returns the proxy user for external users: extuser.
  10. BillingCenter processes the request.
    1. The session user is the proxy external user: extuser.
    2. The endpoint access is defined by Account_Contact.role.yaml.
    3. The resource access is defined by contactAuthorizationIds access.yaml using the resource access ID of ctc-11450.
  11. BillingCenter provides the response to the initial call.

External producer example

In the following example, an API call is triggered by Karen Egerston, who is a producer and external user, using a browser-based web application.


Authentication flow for external producer code users
  1. When Karen triggers an API call, the caller application must first request a JWT from Guidewire Hub. To initiate the process of getting the JWT, the caller application submits its client ID (00ubx7m33sHP1tsew7b4), the ID of the IdP (acmeIdP_ID), the application's resource access strategy (bc_producerCodes), and additional deployment information (tenant.acme, project.default, planet_class.prod).
  2. Guidewire Hub sends a request to the appropriate IdP to authenticate the user. The IdP authenticates the user and provides a SAML response with information about the user, such as the user's name (kegerston@email.com). The SAML response includes information about the resource access strategy (gwa.prod.bc.Producer_Code) and the resource access IDs (ProducerCodeABC and ProducerCodeDEF).
  3. Guidewire Hub sends a code to the caller application. The caller application uses this code to request a JWT.
  4. Guidewire Hub generates a JWT and sends it to the caller application. This JWT includes the client ID (cid), a scp token claim which names the resource access strategy (bc_producerCodes) and additional deployment information. The JWT also contains any relevant information Guidewire Hub received in the SAML response, such as a groups token which names the user's API roles (gwa.prod.bc.Producer_Code), or a bc_producerCodes token which names the user's resource access IDs (ProducerCodeABC and ProducerCodeDEF).
  5. The caller application sends the API request to BillingCenter along with the JWT.
  6. BillingCenter 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. (For external users, this could include API roles and/or resource access IDs that are not stored in the IdP.)
  7. BillingCenter determines the endpoint access. Based on the groups listed in the token map (gwa.prod.bc.Producer_Code), the Producer_Code.role.yaml API role file is used to define the endpoint access.
  8. Next, BillingCenter determines the resource access strategy. Based on the resource access strategy value in the token map (bc_producerCodes), it grants resource access as defined in the producerCodes access.yaml files. (* BillingCenter starts with producerCodes_ext-1.0.access.yaml, but this file references additional access.yaml files whose name starts with "producerCodes".)
  9. To determine which proxy user to assign to the session, BillingCenter calls the RestAuthenticationSourceCreator plugin. The token map specified a resource access strategy of bc_producerCodes. So, the plugin returns the proxy user for external users: externalProducerCodeUser.
  10. BillingCenter processes the request.
    1. The session user is the proxy external user: externalProducerCodeUser.
    2. The endpoint access is defined by Producer_Code.role.yaml.
    3. The resource access is defined by producerCodes access.yaml using an array of resource access ids with two items: ProducerCodeABC and ProducerCodeDEF.
  11. BillingCenter provides the response to the initial call.