Overview of authentication for anonymous users

Life cycle of an anonymous user

From a technical perspective, an anonymous user starts out as an unauthenticated user who creates an account using the POST /account/v1/accounts endpoint. PolicyCenter creates a self-signed JWT, which it sends with the response to the API call. The caller application can save this JWT and use it for later calls in the same session. During those later calls, the user is considered an anonymous user.

In some situations, a caller may start but not complete a submission in the first session. They wish to continue the work in some subsequent session. The second session could occur because the first session timed out, or the caller switched to a different device. The caller can execute a POST /recover-new-jobs endpoint to recover any incomplete job associated with the account and a new self-signed JWT. Note that, in the base configuration, this endpoint returns no results and no JWT. The insurer must configure the endpoint. For more information, see Configuring the reauthorize anonymous user flow.

If the user binds a policy, either in the first session or a subsequent session, then presumably the user's information is sent to the IdP. On subsequent visits, the user will be an external user. (Note that most JWTs used in bearer token authentication come from Guidewire Hub. The anonymous user flow is the one flow that uses JWTs made from somewhere other than Guidewire Hub.)

Credentials

By definition, an anonymous user does not initially have any credentials. If the user binds a policy, they logically become an external user. At this point, the user's user name and password would be stored in the IdP.

For more information on how configuration of the IdP, see Configuring the IdP.

Authorization

Endpoint access for anonymous users

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.

In the anonymous flow, when the caller makes their first Cloud API call, Cloud API automatically assigns them to the unauthenticated role. This role gives them access to endpoints for creating an account and its child objects. Once the account has been created, when the caller makes additional Cloud API calls, Cloud API automatically assigns them to the anonymous role.

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

Resource access for anonymous users

Resource access defines, for a given type of resource, which instances of that resources 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.

A resource access strategy is a set of logic that identifies the meaning of a resource access ID. Anonymous users use the same resource access strategy as that used by external users. The base configuration includes the following resource access strategies for external users:

Strategy name Persona using this strategy The resource access ID is assumed to be... Grants access to...
pc_accountNumbers Account holders (including anonymous users who have created an account) An array of account numbers Information associated with the account

For anonymous users, the pc_accountNumbers strategy is used automatically. Any resource access ID is treated as a list of account numbers. The user is given access to all accounts with these numbers.

For more information on how resource access behaves, see Resource access.

Proxy user access for anonymous users

When a caller makes a Cloud API call, the internal PolicyCenter logic may trigger checks that are unrelated to endpoint access or resource access. For example:

  • A caller may attempt to assign an activity to themselves. PolicyCenter must check to see if the caller has sufficient permission to own an activity.
  • A caller may attempt to create a collision coverage with a deductible less than $1000. PolicyCenter must check to see if the amount of the coverage term is within the caller's authority limit.

Anonymous users are not listed in the PolicyCenter operational database, and therefore do not have any system permissions or authority limits tied to them. To execute these checks, Cloud API makes use of proxy users. A proxy user is an internal user that is assigned to an external user or service when the API call is made. Whenever internal PolicyCenter logic must check to see if the caller has sufficient access, the proxy user is checked. Anonymous users are assigned proxy user access as if they were external users.

For more information on how proxy user access behaves, see Proxy user access.

JWTs for anonymous users

JSON Web Tokens (JWTs) contain token claims. (In standard JWT parlance, these are referred to simply as "claims". To avoid confusion with claims in the property and casualty insurance sense, this documentation sometimes refers to JWT claims as "token claims".) A token claim is a piece of information asserted about the bearer of the token, such as the bearer's name. For bearer token authentication, authentication information is stored in token claims.

JWTs for anonymous users include the following token claims:

  • groups - The API roles to assign to the anonymous user
  • scp - The name of the resource access strategy (pc_accountNumbers)
  • pc_accountNumbers - The resource access IDs (which are treated as account numbers)

For example, the following JWT is for an anonymous user who has created account C000999111. (Information that is not relevant to Cloud API authorization has been omitted.) 

{
    "groups" : [
        "pc.anonymous"
    ],
    "scp": [
        "pc_accountNumbers"
    ],
    "pc_accountNumbers": [
        "C000999111"
    ]
}

Note the following:

  • Based on the groups token claim, this caller will be given endpoint access as defined in the role named "anonymous".
  • Based on the scp token claim, this caller's resource access IDs will be interpreted as account numbers.
  • Based on the pc_accountNumbers token claim, this caller will have access to information related to account C000999111.