| title | description | services | author | ms.service | ms.topic | ms.date | ms.author | ms.custom |
|---|---|---|---|---|---|---|---|---|
How to use named values in Azure API Management policies |
Learn how to use named values in Azure API Management policies. Named values can contain literal strings, policy expressions, and secrets stored in Azure Key Vault. |
api-management |
dlepow |
azure-api-management |
how-to |
07/11/2024 |
danlep |
engagement-fy23, devx-track-azurecli |
[!INCLUDE api-management-availability-all-tiers]
API Management policies are a powerful capability of the system that allow the publisher to change the behavior of the API through configuration. Policies are a collection of statements that are executed sequentially on the request or response of an API. Policy statements can be constructed using literal text values, policy expressions, and named values.
Named values are a global collection of name/value pairs in each API Management instance. Named values can be used to manage constant string values and secrets across all API configurations and policies.
:::image type="content" source="media/api-management-howto-properties/named-values.png" alt-text="Named values in the Azure portal":::
| Type | Description |
|---|---|
| Plain | Literal string or policy expression |
| Secret | Literal string or policy expression that is encrypted by API Management |
| Key vault | Identifier of a secret stored in an Azure key vault. |
Plain values or secrets can contain policy expressions. For example, the expression @(DateTime.Now.ToString()) returns a string containing the current date and time.
For details about the named value attributes, see the API Management REST API reference.
Secret values can be stored either as encrypted strings in API Management (custom secrets) or by referencing secrets in Azure Key Vault.
Using key vault secrets is recommended because it helps improve API Management security:
- Secrets stored in key vaults can be reused across services
- Granular access policies can be applied to secrets
- Secrets updated in the key vault are automatically rotated in API Management. After update in the key vault, a named value in API Management is updated within 4 hours. You can also manually refresh the secret using the Azure portal or via the management REST API.
Note
The secrets stored in Azure Key Vault must be between 1 and 4096 characters, as API Management can't retrieve values that exceed this limit.
- If you haven't created an API Management service instance yet, see Create an API Management service instance.
[!INCLUDE api-management-workspace-availability]
-
If you don't already have a key vault, create one. For steps to create a key vault, see Quickstart: Create a key vault using the Azure portal.
To create or import a secret to the key vault, see Quickstart: Set and retrieve a secret from Azure Key Vault using the Azure portal.
-
Enable a system-assigned or user-assigned managed identity in the API Management instance.
[!INCLUDE api-management-key-vault-secret-access]
[!INCLUDE api-management-key-vault-network]
See Prerequisites for key vault integration.
Important
When adding a key vault secret to your API Management instance, you must have permissions to list secrets from the key vault.
Caution
When using a key vault secret in API Management, be careful not to delete the secret, key vault, or managed identity used to access the key vault.
-
In the Azure portal, navigate to your API Management instance.
-
Under APIs, select Named values > +Add.
-
Enter a Name identifier, and enter a Display name used to reference the property in policies.
-
In Value type, select Key vault.
-
Enter the identifier of a key vault secret (without version), or choose Select to select a secret from a key vault.
[!IMPORTANT] If you enter a key vault secret identifier yourself, ensure that it doesn't have version information. Otherwise, the secret won't rotate automatically in API Management after an update in the key vault.
-
In Client identity, select a system-assigned or an existing user-assigned managed identity. Learn how to add or modify managed identities in your API Management service.
[!NOTE] The identity needs permissions to get and list secrets from the key vault. If you haven't already configured access to the key vault, API Management prompts you so it can automatically configure the identity with the necessary permissions.
-
Add one or more optional tags to help organize your named values, then Save.
-
Select Create.
:::image type="content" source="media/api-management-howto-properties/add-property.png" alt-text="Add key vault secret value":::
- In the Azure portal, navigate to your API Management instance.
- Under APIs, select Named values > +Add.
- Enter a Name identifier, and enter a Display name used to reference the property in policies.
- In Value type, select Plain or Secret.
- In Value, enter a string or policy expression.
- Add one or more optional tags to help organize your named values, then Save.
- Select Create.
Once the named value is created, you can edit it by selecting the name. If you change the display name, any policies that reference that named value are automatically updated to use the new display name.
To begin using Azure CLI:
[!INCLUDE azure-cli-prepare-your-environment-no-header.md]
To add a named value, use the az apim nv create command:
az apim nv create --resource-group apim-hello-word-resource-group \
--display-name "named_value_01" --named-value-id named_value_01 \
--secret true --service-name apim-hello-world --value test
After you create a named value, you can update it by using the az apim nv update command. To see all your named values, run the az apim nv list command:
az apim nv list --resource-group apim-hello-word-resource-group \
--service-name apim-hello-world --output table
To see the details of the named value you created for this example, run the az apim nv show command:
az apim nv show --resource-group apim-hello-word-resource-group \
--service-name apim-hello-world --named-value-id named_value_01
This example is a secret value. The previous command doesn't return the value. To see the value, run the az apim nv show-secret command:
az apim nv show-secret --resource-group apim-hello-word-resource-group \
--service-name apim-hello-world --named-value-id named_value_01
To delete a named value, use the az apim nv delete command:
az apim nv delete --resource-group apim-hello-word-resource-group \
--service-name apim-hello-world --named-value-id named_value_01
The examples in this section use the named values shown in the following table.
| Name | Value | Secret |
|---|---|---|
| ContosoHeader | TrackingId |
False |
| ContosoHeaderValue | •••••••••••••••••••••• | True |
| ExpressionProperty | @(DateTime.Now.ToString()) |
False |
| ContosoHeaderValue2 | This is a header value. |
False |
To use a named value in a policy, place its display name inside a double pair of braces like {{ContosoHeader}}, as shown in the following example:
<set-header name="{{ContosoHeader}}" exists-action="override">
<value>{{ContosoHeaderValue}}</value>
</set-header>In this example, ContosoHeader is used as the name of a header in a set-header policy, and ContosoHeaderValue is used as the value of that header. When this policy is evaluated during a request or response to the API Management gateway, {{ContosoHeader}} and {{ContosoHeaderValue}} are replaced with their respective values.
Named values can be used as complete attribute or element values as shown in the previous example, but they can also be inserted into or combined with part of a literal text expression as shown in the following example:
<set-header name = "CustomHeader{{ContosoHeader}}" ...>Named values can also contain policy expressions. In the following example, the ExpressionProperty expression is used.
<set-header name="CustomHeader" exists-action="override">
<value>{{ExpressionProperty}}</value>
</set-header>When this policy is evaluated, {{ExpressionProperty}} is replaced with its value, @(DateTime.Now.ToString()). Since the value is a policy expression, the expression is evaluated and the policy proceeds with its execution.
You can test this in the Azure portal or the developer portal by calling an operation that has a policy with named values in scope. In the following example, an operation is called with the two previous example set-header policies with named values. Notice that the response contains two custom headers that were configured using policies with named values.
:::image type="content" source="media/api-management-howto-properties/api-management-send-results.png" alt-text="Test API response":::
If you look at the outbound API trace for a call that includes the two previous sample policies with named values, you can see the two set-header policies with the named values inserted as well as the policy expression evaluation for the named value that contained the policy expression.
:::image type="content" source="media/api-management-howto-properties/api-management-api-inspector-trace.png" alt-text="API Inspector trace":::
String interpolation can also be used with named values.
<set-header name="CustomHeader" exists-action="override">
<value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>The value for CustomHeader will be The URL encoded value is This+is+a+header+value..
Caution
If a policy references a secret in Azure Key Vault, the value from the key vault will be visible to users who have access to subscriptions enabled for API request tracing.
While named values can contain policy expressions, they can't contain other named values. If text containing a named value reference is used for a value, such as Text: {{MyProperty}}, that reference won't be resolved and replaced.
To delete a named value, select the name and then select Delete from the context menu (...).
Important
If the named value is referenced by any API Management policies, you can't delete it until you remove the named value from all policies that use it.
- Learn more about working with policies