Secrets and the managed identity

A function namespace has one managed identity, and every function in it runs as that identity: when the platform fetches a function's secrets as it starts, and when the function's own code asks for a token. Adding secret references needs functions/write; giving the identity a role needs rbac/members/write, which the Owner role has.

Add a secret reference

Open the function, its Configuration tab, section Secrets, and add a reference to a vault secret with the Environment Variable Name it should get. The steps are in Add a secret reference. Saving redeploys the function.

Give the identity access to the vault

Before the function can start with a secret, the namespace's identity needs Secrets Reader on the vault. Nothing assigns it for you.

1. Find the identity's principal ID. Open the function namespace; the Managed Identity card on its Overview shows the Principal ID. The card is shown only to people who may also read apps (apps/read); without that, use the CLI:

   bashCopy code

   stsh identity list -g my-resource-group -o json

   and take principalId from the entry whose resourceType is functionnamespace and whose resourceName is the function namespace. Functions have no identity of their own.

2. Give that principal ID Secrets Reader on the vault — see Give a workload access.

Important

The identity belongs to the function namespace, not to one function. A role you give it applies to every function in the namespace: once the identity may read a vault, the code of any of its functions can read that vault's secrets, not only the functions that reference them. Put functions that must not share access in separate function namespaces.

Read the values in your code

When a replica starts, the platform fetches the referenced values into the file /secrets/env.json, a JSON object that maps each Environment Variable Name to its value. The function's runtime then sets one environment variable per entry, named STSH_ followed by the name in capitals:

const apiKey = process.env.STSH_API_KEY;

• The file stays readable as well, on a read-only volume that lives in memory.
• If the file cannot be read or parsed, the function does not start.
• An image you build yourself gets the file but not the STSH_ variables: those are set by the platform's runtime — see Run an image from your own pipeline.

When a value changes

Values are fetched each time a replica starts: when the function is deployed, when one of its settings is saved, and each time it wakes from sleep. A replica that is already running keeps the values it started with.

Use the identity in your own code

The function's code can get a token for the namespace's identity and call platform services with it. Functions receive the same variables as other workloads — see Use a managed identity in code.

When a function does not start

A function whose secrets cannot be fetched does not start — see The function does not start. The reasons a secret cannot be fetched are the same as for other workloads — see Troubleshoot secret delivery.