# **Layer7 API Developer Portal Policy Templates Guide** Policy templates in the Layer7 API Developer Portal allow API publishers to customize how policies on the API Gateway (API proxy) process API requests . This document explains how to create, manage, and utilize policy templates to establish a governance framework in support of self-service API Publishing. ## **What are Policy Templates?** A policy template is essentially a reusable component that may be applied to an API during publishing and enforced at runtime by the API Gateway. They act as building blocks that API publishers can combine to enforce security, routing, rate limiting, and other governance rules on their APIs. ### **Why Create Policy Templates?** Creating policy templates unlocks a **self-service developer experience** for API publishers. Instead of requiring Gateway Administrators to manually craft and deploy a unique policy for every new API, publishers can simply select from a catalog of pre-approved templates in the Developer Portal. By leveraging the API Portal's **Governance capabilities** (specifically through *Policy Template Categories*), organizations can: * **Enforce Standardization**: Ensure that every published API adheres to corporate security and operational standards (e.g., mandating an OAuth template on all external APIs). * **Accelerate Time-to-Market**: Empower developers to quickly publish APIs without waiting on a central operations team to write custom Gateway policy. * **Simplify Complexity**: Abstract complex Gateway logic (like routing rules or header manipulation) into simple input fields or drop-down menus for the publisher. For example, a publisher can select "Production" or "QA" from a dropdown instead of writing a routing policy from scratch. ### **Gateway vs. Portal Published Templates** Policy templates are created using the API Gateway. When managing templates in a multi-cluster environment, it's important to distinguish between how they are published and managed: * **Gateway Published:** Templates that are created and published directly on the API Gateway. In a multi-cluster environment, if you publish an API via the Gateway, you **must** ensure those templates are migrated (i.e. using Graphman Client or GMU) and match identically across *all* clusters/gateways. Failure to do so can cause issues and will result in API deployment failures to Gateways where the template is not deployed. * **Portal Published:** Templates that are managed centrally through the API Portal. The Portal acts as the control plane, allowing you to deploy these templates specifically to the gateways that need them, directly from the Portal UI, or programmatically via the Portal API (PAPI). **Best Practice:** For optimal flexibility and streamlined administration, prioritize **Portal-published templates and APIs**. Doing so removes the manual burden of migrating policies across individual gateways. When templates are uploaded directly to the API Developer Portal, it allows the Portal to serve as a unified control plane. This empowers you to centrally manage policy deployments across multiple geographic clusters and varied environments, including Dev, Staging, and Production. ## **System-Provided Templates** When you integrate or enroll an API Gateway with the API Developer Portal, system policy templates are automatically added. These are pre-existing templates provided by the system, rather than templates you create. * **Examples**: Standard authentication, quota, and rate limit policy templates (e.g., `l7.apim.system - Rate & Quota Policy Template`). * **Usage**: Deployed automatically or by Portal Admins to enable built-in Portal features. They cannot be deleted but they may be hidden if desired by ensuring they are not assigned to any Policy Template Category. **Standard Templates** The Portal provides a set of "standard" policy templates out of the box. These include: * Standard Policy Template \- OAuth 2.0 * Standard Policy Template \- mTLS with API Key * Standard Policy Template \- API Key It is important to note that these "Standard" policy templates included out of the box provide an end-to-end flow of performing authentication, authorization, and routing in a single, monolithic template. These templates are not designed to be used in a more modular approach where multiple templates are being used for your APIs. These templates are great for getting started quickly and for scenarios where you may only need the standard capabilities. However, for more advanced use cases, where you will be creating multiple templates to separate authentication, authorization, routing, and any other capabilities, treat these standard templates as examples. While these templates cannot be uninstalled, you may hide them by ensuring they are not assigned to any Policy Template Category. Both system and standard templates are automatically installed on the Gateway as part of the enrollment process with the Portal. ## **How to Create and Add Policy Templates** Policy templates are **always** created initially using the API Gateway Policy Manager. Once created, they can be deployed either directly on the Gateway (Gateway Published) or extracted as bundles to be managed centrally by the Portal (Portal Published). As indicated earlier, it is recommended to extract your custom policy templates from the gateway where you developed them (e.g. a developer workstation gateway) as a graphman bundle and import them into the Portal (i.e. publish them). You may then deploy them to the various gateways enrolled with your Portal. Once a template is published to the Portal, it may then be assigned to a Policy Template Category to establish governance rules for its use. ### **1\. Creating the Template in API Gateway Policy Manager** API Gateway administrators must first create the custom policy template directly within the Gateway Policy Manager. Refer to the section “Capabilities and Features of Policy Templates” to learn more about how to create the policy and available capabilities. **Steps to Create:** 1. Connect to the API Gateway via Policy Manager. 2. Create a new Policy fragment (`Tasks` `> Services and APIs > Create Policy`). * **Important**: This policy fragment must *not* include or reference other policy fragments. It should contain only direct policy assertions. This avoids complex dependencies and ensures the template is a self-contained entity, preventing compatibility issues when deployed across multiple target gateways. 3. *(For Gateway Published Templates Only, NOT RECOMMENDED)*: Drag the **Set as Portal Publishable Fragment** assertion into the policy. If you plan to deploy this as a Portal Published Template, skip this step. 4. Construct your policy logic (adhering to the standalone rule mentioned in Step 2). Refer to “**Capabilities and Features of Policy Templates**” to learn more about available context variables and patterns to follow. 5. If your template sets any context variables that you wish to make available to any other templates that may be applied to the overall API policy, then you must include the “**Export Variables from Fragment**” assertion and ensure those variables are selected. 6. “Save and Activate” to save the policy. 7. Right-click the policy fragment and select **Create Encapsulated Assertion**. 8. Provide a template name and description (this is what API publishers will see in the Portal). 9. **Add Arguments**: Define input/output arguments. You can make inputs visible in the Portal and mark them as mandatory (by adding an asterisk `*` to the label). The label will be displayed in the API Portal. The input fields are accessible as context variables inside the policy on the gateway. Refer to “**Capabilities and Features of Policy Templates**” for guidance on defining inputs based on desired capabilities of the template. 10. Press OK to save the Encapsulated Assertion.. If using Gateway Published templates, the template will sync and become available in the Portal. You must ensure the Gateway Published template is properly migrated to **ALL** API Gateways enrolled with the API Portal. ### **2\. Extracting and Deploying via Gateway and Graphman Bundles (Portal Published)** After creating the encapsulated assertion in the Policy Manager (Step 1), you can export the template as a **Bundle** to be centrally managed and deployed by the Portal. This is the required path for **Portal Published Templates**. **Using Graphman Bundles:** Graphman is a modern GraphQL-based interface for managing Gateway configurations. Graphman bundles may be exported either using the Graphman client command-line interface (CLI) or the web-based Policy Manager. The bundle name must be formatted as `[BundleName]-[x.y.z]` (e.g., `MyTemplate-1.0.0`) and must not include spaces. Once you export the bundle, you may rename the file as necessary to match the correct naming convention and version number. To create your bundle and manage it in the Portal: 1. **Export** an existing encapsulated assertion to a JSON bundle. 1. Using the [Graphman CLI](https://github.com/Layer7-Community/graphman-client) 1. Example Command: ```./graphman.sh export --gateway --using encass --variables.name --output -...json``` 2. Using the web-based Policy Manager 1. Select “Export” 2. Deselect all checkboxes for the entities under “Gateway” 3. Click on the “Encapsulated Assertions” folder 4. Check the box beside the Encapsulated Assertion that represents the template you are exporting (be sure to only select **ONE**). 5. Click the “Add Dependencies” under the “Export Summary” section. Note that the “Selected” count should now be “2” to indicate that the export will include the Encapsulated Assertion and the policy. If you see more than 2, then your policy will need to be updated to remove any additional dependencies. 6. Select “XML” in the “Export Format” drop-down. 7. Click “Export” 8. You will now have a file “bundle.json” 9. Rename the file to match the template naming convention \-x.y.z 2. **Upload**: Portal Admins may now upload this JSON bundle to the Portal UI (`Manage` \> `Gateway Bundles`). 3. **Deploy**: In the Portal UI, deploy the uploaded bundle to the desired enrolled proxies. Deployment is done by clicking on the template within the (`Manage` \> `Gateway Bundles`) page, and then navigating to the **Gateway Bundle Deployments** tab. From this tab you may deploy, redeploy, and undeploy bundles to/from specific API Gateways. --- ## **Capabilities and Features of Policy Templates** ### **Input Arguments & Customization** Templates can be configured to accept dynamic input from API publishers (Strings, Integers, Decimals, Booleans). For example, you can create an input field to allow a routing policy to route to different backend URLs based on the publisher's input. The policy for the template is created much like any other policy on the API Gateway using the Gateway’s out of the box policy assertions. Any standard context variables set by the Gateway will be available to the policy. In addition, the following context variables may be used by the template: * **apiLocation** \- Represents the full backend location where the incoming API request will be routed to based on how the API is configured in the Portal. For example, “https://\/service” * **serviceUrl** \- The front end service path of the API. For example if the API is exposed at https://\/account then the serviceUrl will be set to "account" Additionally, some service properties may be set by the API Portal and referenced in templates. Note that these may only be set if the capability is enabled in the Portal. These Service Properties include: * **service.property.internal.apiTags** \- A comma separated list of tags assigned to the API in the Portal. (feature must be enabled) * **service.property.internal.portalAPIEnabled** (true/false) \- Indicates if the API is controlled by the Portal * **service.propertyinternal.apiSpec** \- The Swagger/OpenAPI Specification for the API as provided to the API Portal (feature must be enabled). * **service.property.\ \-** If you have defined custom fields for APIs, any configured custom field values will be available by referencing the custom field name **Creating a Template to Perform Routing** When an API is published to the Gateway by the Portal, a default policy that performs routing of the API request to the backend service is defined. If you desire more control (such as passing through headers, controlling specific TLS settings, etc.) of the routing policy then you may create a template that performs the routing instead of using the default routing defined by the Portal. If you are building a template to perform routing, you must ensure that you are NOT using the “standard” policy templates mentioned above as they already include routing logic that cannot be overridden. **Steps to Enable Custom Routing:** 1. Include the “`Route via HTTP`” assertion and ensure the properties of the assertion are set to meet your needs for header processing, TLS, and any other settings desired. The URL may be set to the following, assuming you wish to pass through any incoming query parameters (note however that best security practice would be to validate and restrict query parameters before passing them to the backend service). `${apiLocation}${request.url.query}` 2. Configure the template to avoid CORS issues. With custom route policies, it is possible that the `Access-Control-Allow-Origin` header may be set to a value that prevents the API from being called from the API Portal’s “Spec” page where users can interact directly with the API. To prevent this, the template must be configured to remove the CORS header. **Steps to Filter Headers:** 1. Add the “**Manage Transport Headers/Properties**” assertion to your template after the Route Via HTTP(S) assertion 2. Set **Type** to “**HTTP Header**” 3. Set **Operation** to “**Remove**” 4. Set **Property/Header Name** to “**Access-Control-Allow-Origin**” 5. Press “**OK**” 6. Ensure the assertion appears as “Response: Remove HTTP Header(s) Access-Control-Allow-Origin. In this case “Response” is the target message which is automatically set when the assertion is placed after the route assertion. If this is set to another value, right click on the assertion, choose “Select Target Message" and then select “Response” and press “OK”. Also ensure the assertion is placed after the route assertion. 7. Save and activate the policy. ### **Drop-Down Selection Fields** You can create drop-down menus for API publishers to select from predefined options instead of using open text fields. * **Creation**: Prefix the input argument name with `l7.enum.` (e.g., `l7.enum.deployment`). * **Options Definition**: Following the primary input definition, create additional inputs for each option by appending the value to the name (e.g., `l7.enum.deployment.QA`, `l7.enum.deployment.PRODUCTION`). * **Mandatory Fields**: Add an asterisk `*` to the main label (`l7.enum.deployment`) to make the selection mandatory. *(Note: You cannot add asterisks to the individual selection values).* * **Order**: The order you enter the input arguments in Policy Manager dictates the order they appear in the Portal's drop-down menu. * The input value can be referenced as a context variable i.e. ${l7.enum.deployment} in the policy in the Proxy. ### **Secure Secret Fields** You can safely pass sensitive information (like backend API keys or passwords) through policy templates without exposing them. * **Creation**: When defining an input argument in the Encapsulated Assertion, prefix the name with `l7.secure.` (e.g., `l7.secure.username`). Set the type to `string`. * **Behavior**: In the Portal UI, the user's input is masked with asterisks. * **Storage**: The value is securely encrypted and stored as a stored password in the Gateway database. * **Usage**: The secret can be referenced securely in the policy using context variables e.g., `${l7.secure.username}`, preventing exposure in logs or exported bundles. **Analytics** When creating the policy templates, there are a number of context variables that must be set in order to gather the proper analytics data for reporting purposes. The following table provides a list of these variables along with information about how they are used and how to set their values. All of these variables must be exported using the “**Export Variables from Fragment** assertion. These variables are used by a global policy applied at the end of message processing. This global policy will read these variables to collect the data for reporting analytics to the Portal for display. | Variable Name | Purpose | How to set | | :---- | :---- | :---- | | portal.analytics.action | This is the URI for REST requests or the SOAP action for SOAP requests. | For REST: set to ${request.http.uri} For SOAP: set to ${request.http.header.soapaction} | | portal.analytics.api.uuid | Identifies the API as defined in the Portal. | Set to ${portal.managed.service.apiId} in your template that does API key validation. | | portal.analytics.apikey | Identifies the client’s API Key used to make the API request | This may be set after the use of the “**Portal API Key Look Up (Generic)**” assertion by setting it to the **${apiKeyRecord.id}** | | portal.analytics.application.name | Identifies the name of the client making the request as defined in the Portal. | This may be set after the use of the “**Portal API Key Look Up (Generic)**” assertion by setting it to the **${apiKeyRecord.label}** Note: The ${apiKeyRecord.label} is formatted as \-\ in order to distinguish the API key used by the application as applications may have multiple API keys. | | portal.analytics.application.uuid | Identifies the ID of the client application making the request as defined in the Portal. | The application UUID is found in the Custom MetaData field populated by the “**Portal API Key Look Up (Generic)**” assertion. To extract the UUID, refer to the sample at the end of this table. | | portal.analytics.authType | The type of authentication performed for the request. Note that this value is not currently used for displaying reports in the Portal. | Example Values: API\_KEY NO\_AUTH OAUTH\_2 The above examples reflect values set by the sample “Standard” policy templates. You may define your own values as needed. | | portal.analytics.organization.name | Identifies the name of the Organization that owns the Application making the request. | This may be set after the use of the “**Portal API Key Look Up (Generic)**” assertion by setting it to the **${apiKeyRecord.accountPlanMappingName}** | | portal.analytics.organization.uuid | Identifies the ID of the Organization that owns the Application making the request. | This may be set after the use of the “**Portal API Key Look Up (Generic)**” assertion by setting it to the **${apiKeyRecord.accountPlanMappingId}** | | portal.analytics.response.code | Indicates the final HTTP response disposition of the request. | This may be set differently based on the policy logic. For example, if a request fails API Key validation, the response code may be set explicitly to an HTTP error code such as “400”. If a rate or quota validation fails it may be set to “503”. If the request is routed to the backend, then the HTTP response from the backend may be passed through by setting the value to **${response.http.status}** | | portal.analytics.routingTotalTime | The total amount of time (ms) spent routing the request. | Set to **${request.routingTotalTime}** after the use of the “**Route via HTTP(S)**” assertion to route the request to the backend. | The application UUID is found in the Custom MetaData field populated by the “**Portal API Key Look Up (Generic)**” assertion. To extract this value, some additional policy logic is required. The below is an example of this logic: ![image1](images/policyexample-appuuid.png) ## ## Policy Template Versioning It is important to properly version policy templates to allow for changes over time and to avoid any breaking changes that impact APIs that are using these templates. To support this, the Portal supports an x.y.z format for bundles. Both x (major) and y (minor) versions indicate that the bundle has a breaking change and will NOT be automatically applied to APIs that are using the template. The z (patch) version indicates that the version is a patch and therefore is safe to apply to all APIs that are currently using that template. The policy and resulting encapsulated assertion name must include the x.y versioning in the name (e.g **MyTemplate-1.0**). The bundle file name will include the z version (e.g., **MyTemplate-1.0.0.json**). Modifying only the z value in the file name allows for an in-place upgrade, whereas modifying the x and/or y value in the Bundle Name results in a completely new template. **To perform an in-place upgrade to an existing template:** * Ensure on the z value of the template has changed (e.g. replacing **MyTemplate-1.0.0** with **MyTemplate-1.0.1**) * Go to `Manage` \> `Gateway Bundles` and click on **Add Bundle** * Upload the bundle file (e.g. MyTemplate-1.0.1.json) and click **Save**. * The Portal will detect that this is an in-place upgrade and the current bundle version will be updated to reflect the version (e.g. 1.0.1) and you will be taken to the Gateway Bundle Details page. * Select the **Gateway Bundle Deployments** tab and deploy the update to the desired Gateways. To perform an upgrade of a template involving x or y (e.g. updating **MyTemplate-1.0.0** to **MyTemplate-1.1.0** or **MyTemplate-2.0.0**) you are essentially adding a new template. Once the template is uploaded to the Portal, you will need to associate it to one or more Policy Template Categories and then update the APIs that need to use the new version. This update is not done automatically as it assumes the new template version may break existing APIs either with new functionality or by having new required input. --- ## ## **Policy Template Categories** Policy Template Categories provide the backbone for API Governance in the API Portal. Using Policy Template Categories along with your Policy Templates unlocks the ability to define and enforce the rules for how APIs are published. This enables a true self-service API publishing experience by ensuring that any API published is required to abide by the rules established using Policy Template Categories. Creation and management of these rules are done by going to (`Manage` \> `Policy Template Categories`). ## Category Best Practices When establishing Policy Template Categories, it is important to consider how templates will be used by APIs and the rules that you need to have enforced. In some cases a category may give API publishers some options to choose from and in other cases a category may be fully mandatory with all templates being required. It is also important to ensure that the order of the categories and templates are considered. These will be enforced at runtime in the same order as they are shown in the API’s policy template configuration. For example, if you want to apply general threat protection before performing authentication, you must ensure that the threat protection template is placed before the authentication template. In some cases you may want to define some optional categories and templates that provide useful capabilities for APIs but are not necessarily critical for the overall governance of the API. It is also important to balance the granularity of templates and categories to provide the most flexibility and ease of use without sacrificing the ability to ensure APIs are properly governed by the rules. The following table provides an example of “best practice” for setting up Policy Template Categories: | Category | Template(s) | Category Usage | Template Usage | | :---- | :---- | :---- | :---- | | Threat Protection | Corporate Threat Protection | Required | All | | Authentication | OAuth 2.0 API Key/Secret mTLS with API Key | Required | At least one | | Rate and Quota Enforcement | Rate and Quota System Template | Required | All | | Message Validation | Validate OpenAPI Specification Validate JSON Schema Validate XML Schema | Required | At least one | | Routing | Route via HTTPS Route via HTTPS with JWT Route via HTTPS with mTLS | Required | At least one | | Response Processing | Capture Metrics | Required | All | | Logging | Capture Log Info | Optional and Flexible | Optional | The example above shows what Policy Template Category configuration may look like. This can be adapted to your needs based on the rules you wish to establish and the options you wish to make available to API publishers. Note that specific Policy Template Categories may be assigned to specific Organizations within the Portal as needed. This allows you to define special rules to different API Publisher Organizations to handle special requirements that may not apply to all API Publishers. ### **Accessing and Managing Categories** To access Policy Template Categories, log in to the API Portal and navigate to **Manage** \> **Policy Template Categories**. From the list page, you can view existing categories, which display the following fields: * **Name**: A unique identifier for the policy template category. * **Description**: A brief overview of the category's purpose. * **Position**: Indicates if the template order within the category is **Fixed** (must adhere to a predefined sequence) or **Flexible** (can be reordered). * **Enforcement**: Rules or constraints ensuring policies in the category are followed. * **Edit Rules**: Guidelines for modifying template parameters and reordering templates. * **Usage Rules**: Regulations dictating how and when templates should be applied. * **API Type**: The classification of APIs the templates apply to (e.g., REST, SOAP). * **API Access**: Access permissions indicating who can view and use the templates. ### **Creating a New Policy Template Category** When creating a category via **Add Category**, you configure it across several tabs: 1. **Overview**: Specify a unique category name and an optional description detailing its purpose. 2. **Templates**: Manage template availability within the category. * Click **Add Template** to assign templates. * Toggle to include templates that should be accessible to APIs. * Use the arrow icons to set the order of templates. *Note: The order determines the sequence in which templates are processed at runtime.* 3. **Management**: Configure category-specific rules and permissions: * **API Access/Type Restrictions**: Specify primary types and access restrictions. (If an API is private and its access setting mismatches the category's, applying a template returns an error). * **Template Usage Requirements**: Choose whether to include **ALL** templates (all fixed and flexible templates must be present) or **ANY** (any single template must be present). * **Publisher Editing Permissions**: Allow publishers to change the order of templates (**Flexible**) or restrict them to a fixed sequence based on the order specified (**Fixed**). * **Enforce Category Rules**: Toggle to ensure published APIs adhere to the established category criteria. 4. **APIs**: Explore the list of APIs within a specific category, showing their assignment, applicability, and compliance status. You can filter by: * **API Name**, **Managing Organization**, **Applicable**, **Assigned**, **Policy Compliance**, and **API Status** (All, Enabled, Disabled, Deprecated, Unpublished, Incomplete). ### **Default Template Assignment** * **Upgrading to Portal 5.2.3 or Later**: Existing templates are automatically placed in the "Default" category without predefined rules. You can customize this default category by renaming it or updating rules and templates. * **Default Setting (`ASSIGN_NEW_TEMPLATES_TO_DEFAULT_CATEGORY`)**: In Portal 5.2.3+, this flag in the Portal API Settings Endpoint determines if new templates are automatically assigned to the default category (`True` by default, or `False` to prevent auto-assignment). * **Changing the Default Category**: Renaming the default category does not change its default status (except via PAPI). To change the default category, use a PUT call payload to set `_defaultCategory_` to `false` for the current default, and `true` for the new desired default category. ### **Capabilities within Categories** * **Enforced Ordering**: Define whether templates in a category or categories themselves must be executed in a **Fixed** sequence or if publishers have **Flexible** reordering permissions. * **Usage Rules**: Enforce rules such as requiring an API to use **ALL** templates in a category, or at least **ANY** one template from the category. * **API Targeting**: Restrict categories to specific API types (e.g., REST vs. SOAP) or specific API Access levels (Public vs. Private). * **Default Assignment**: Configure whether new templates are automatically assigned to a default category or managed strictly. [image1]: