Configuring resource access for generated endpoints

Resource access defines, for a given type of resource, which instances of that resource type the caller can access. For example, for a given caller, endpoint access might grant access to a GET /policies endpoint. But this does not necessarily mean the caller can access every policy in the database. Resource access can limit which specific policies that caller can view.

For more information on the general behavior of resource access, see Resource access.

When running the REST endpoint generator, there are no prompts that pertain to resource access. The REST endpoint generator generates resource access code in the same way for every set of generated endpoints. At the very least, the code requires review. In some cases, the code may require additional configuration. The places where coding requires review and additional configuration is flagged with the following comment:

TODO RestEndpointGenerator

You can search for these "TODO RestEndpointGenerator" comments in Studio to complete the configuration.

Code generated in access.yaml files

Every resource access strategy is defined in multiple files. In the base configuration, all of the files for a given resource access strategy start with the same name.

Broadly speaking, there are two types of access files: core and extension.

A core access file is an access file that defines one or more base configuration resource access strategies. Core access files either have core in the name, or are located in a package with core in the path.

Warning: Do not modify any core access files. Modifying these files can result in certain sets of callers being unable to execute API calls.

An extension access file is an access file that provides a location for extensions to base configuration resource access strategy behavior. Extension access files either have ext in the name, or are located in a package with ext in the path.

Code generated by the REST endpoint generator is placed in extension access files. The specific code added to each file depends on the associated type of caller.

Generated resource access code for internal users

The extension access file for internal users is named internal_ext-1.0.access.yaml.

The REST endpoint generator assumes that an internal user can access a given instance of the custom resource if the internal user can also access the resource's parent. Therefore, the filters for all operations are set to __inherit.

Stream-based collections

If you generate endpoints for a CustomEntity_Ext entity, and the entity is backed by a stream, the following is added to the internal user resource access extension file:

resources:
  CustomEntitiesExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: __inherit
      create: __inherit
  CustomEntityExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: __inherit
      edit: __inherit
      delete: __inherit

Query-based collections

If you generate endpoints for a CustomEntity_Ext entity, and the entity is backed by a query, the following is added to the internal user resource access extension file:

resources:
  CustomEntitiesExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: __inherit
      create: __inherit
    filter: __noFilter
  CustomEntityExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: __inherit
      edit: __inherit
      delete: __inherit
Note that, for query-backed collections, there is an additional filter: __noFilter line of code in the collections section. This line is needed to determine appropriate view permissions for query-backed collections.
  • This line of code does not exist for stream-backed collections because stream-backed collections load the entire collection contents into memory at one time. Cloud API can simply iterate over the entire collection using the specified view permission to determine which items in the stream can be viewed.
  • This line of code does exist for query-backed collections because query-backed collections do not load the entire collection into memory at one time. Instead, the collection is loaded one page at a time. Additional logic is required to identify the items in the collection that can be viewed. This is specified by the additional filter.

In most business circumstances, the filter can be set to __noFilter, which specifies no additional filter logic is needed. This is acceptable because, in most cases, a child object can be viewed if the parent object can be viewed.

Generated resource access code for external users

The extension access file for external users is named accountholder_ext-1.0.access.yaml.

The REST endpoint generator assumes that an external user can access a given instance of the custom resource if the external user can also access the resource's parent. Therefore, the filters for all operations are set to __inherit.

Stream-based collections

If you generate endpoints for a CustomEntity_Ext entity, and the entity is backed by a stream, the following is added to the external user resource access extension file:

resources:
  CustomEntitiesExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: "__inherit"
      create: "__inherit"
  CustomEntityExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: "__inherit"
      edit: "__inherit"
      delete: "__inherit"

Query-based collections

If you generate endpoints for a CustomEntity_Ext entity, and the entity is backed by a query, the following is added to the internal user resource access extension file:

resources:
  CustomEntitiesExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: "__inherit"
      create: "__inherit"
    filter: "__inherit"
  CustomEntityExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: "__inherit"
      edit: "__inherit"
      delete: "__inherit"

Note that, for query-backed collections, there is an additional filter: __inherit line of code in the collections section. This line is needed to determine appropriate view permissions for query-backed collections.

  • This line of code does not exist for stream-backed collections because stream-backed collections load the entire collection contents into memory at one time. Cloud API can simply iterate over the entire collection using the specified view permission to determine which items in the stream can be viewed.
  • This line of code does exist for query-backed collections because query-backed collections do not load the entire collection into memory at one time. Instead, the collection is loaded one page at a time. Additional logic is required to identify the items in the collection that can be viewed. This is specified by the additional filter.

Generated resource access code for services

The extension access file for internal users is named service_ext-1.0.access.yaml.

The REST Endpoint Generator assumes that services are not restricted by resource access. Therefore, the filters for all operations are set to true.

Stream-based collections

If you generate endpoints for a CustomEntity_Ext entity, and the entity is backed by a stream, the following is added to the service resource access extension file:

resources:
  CustomEntitiesExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: true
      create: true
  CustomEntityExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: true
      edit: true
      delete: true

Query-based collections

If you generate endpoints for a CustomEntity_Ext entity, and the entity is backed by a query, the following is added to the internal user resource access extension file:

resources:
  CustomEntitiesExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: true
      create: true
    filter: __noFilter
  CustomEntityExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: true
      edit: true
      delete: true

Note that, for query-backed collections, there is an additional filter: __noFilter line of code in the collections section. This line is needed to determine appropriate view permissions for query-backed collections.

  • This line of code does not exist for stream-backed collections because stream-backed collections load the entire collection contents into memory at one time. Cloud API can simply iterate over the entire collection using the specified view permission to determine which items in the stream can be viewed.
  • This line of code does exist for query-backed collections because query-backed collections do not load the entire collection into memory at one time. Instead, the collection is loaded one page at a time. Additional logic is required to identify the items in the collection that can be viewed. This is specified by the additional filter.

If services are not restricted by resource access, then no additional filter logic is needed. The filter: __noFilter line of code specifies this.

Generated resource access code for special use cases

There are two resource access strategies used for special cases.
  • Unauthenticated user resource access is used for unauthenticated users. This access is defined in unauthenticated_ext-1.0.access.yaml.
  • Default resource access is used for callers who have been authenticated but specify no resource access strategy with the call. This access is defined in default_ext-1.0.access.yaml.

The REST endpoint generator assumes that no resource access is provided to unauthenticated or default users. Therefore, the filters for all operations are set to false.

Stream-based collections

If you generate endpoints for a CustomEntity_Ext entity, and the entity is backed by a stream, the following is added to the unauthorized access extension file:
resources:
  CustomEntitiesExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: "false"
      create: "false"
  CustomEntityExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: "false"
      edit: "false"
      delete: "false"

Query-based collections

If you generate endpoints for a CustomEntity_Ext entity, and the entity is backed by a query, the following is added to the unauthorized access extension file:

resources:
  CustomEntitiesExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: "false"
      create: "false"
    filter: __noFilter
  CustomEntityExt:
    # TODO RestEndpointGenerator : Update the default generated access here
    permissions:
      view: "false"
      edit: "false"
      delete: "false"

Note that, as is the case for the other caller types, query-backed collections have an additional "filter:" line of code in the collections section.

Configuring generated resource access code

Depending on the business needed, the following resource access configuration may be required:

  • Guidewire recommends removing the TODO RestEndpointGenerator comments.
  • The default resource access for internal users is "you can access the custom entity if you can access its parent." If this is not appropriate or sufficient, you must configure the internal resource strategy extension file.
  • The default resource access for services is "you can access all custom entities." If this is not appropriate or sufficient, you must configure the service resource strategy extension file.
  • There is no default resource access for external users, unauthenticated users, or callers with default access. If your endpoints support any of these types of callers, you must configure the corresponding resource strategy extension file.

For more information on how to configure resource access files, see Resource access.