Retrieve Key Vault secrets and certificates safely

Learning objective

Configure Azure Key Vault for secret and certificate retrieval with least-privilege RBAC.

Core idea

For an architect securing tool adapters, Key Vault access starts with the material the adapter actually needs. A process that reads one integration secret does not need to create, delete, or rotate secrets. A component that inspects a public certificate does not necessarily need its private key. Choose the retrieval operation, then the data-plane role and scope that permit it.

Key Vault authenticates callers through Microsoft Entra ID. Its management and data planes authorize different operations. A role that lets you configure the vault is not a grant to read its contents. See 4.1.1 for the broader principal and permission model; this lesson applies that model to secret and certificate retrieval.

How it works

Configure the vault’s authorization model

Key Vault supports Azure role-based access control (RBAC) and a legacy vault access-policy model for data-plane authorization. Select Azure role-based access control as the permission model for the role-based design taught here. The listed Key Vault data roles apply to vaults using that model; assigning them does not repair a vault configured for access policies.

Management-plane permissions control vault creation, properties, and configuration. Data-plane permissions control operations on secrets, certificates, and keys. Key Vault Contributor manages the vault but does not grant access to those contents. Key Vault Reader reads metadata but cannot read sensitive values such as secret contents or key material.

Do not solve a runtime retrieval failure by granting Key Vault Administrator. That role permits all data-plane operations on the vault’s objects. A reader that only needs an integration password should receive a read role, while a separate provisioning identity owns secret creation and maintenance.

Microsoft recommends a vault per application per environment, with roles assigned at vault scope. This makes the vault’s contents an intentional access group. If two components must not share access, design their vault placement accordingly. Individual object assignments are supported but recommended for limited cases, such as sharing a specific secret between applications. They are not Microsoft’s default isolation design for application teams.

Authenticate the runtime and retrieve a secret

The Python SDK uses SecretClient(vault_url=..., credential=...). The vault URL identifies the data-plane endpoint, in the form https://VAULT_NAME.vault.azure.net. DefaultAzureCredential supplies an Entra credential; the documented quickstart uses a local Azure CLI identity during development and can discover an assigned managed identity when deployed to supported Azure hosting.

The deployed identity still needs a role assignment. Credential discovery proves neither that the intended principal was selected nor that it can read the secret. Verify the production principal independently of the developer’s successful local call. See 0.12 for credential selection across environments.

SecretClient.get_secret(name) retrieves a KeyVaultSecret; its .value contains the secret contents. Key Vault Secrets User permits reading secret contents, including the secret portion of a certificate with a private key. Give a runtime that only reads ordinary secrets this role rather than Key Vault Secrets Officer, which permits secret management operations except permission management.

Keep the value inside the component that consumes it. Returning it as tool output would place credential material in the agent’s working context. For a custom adapter, resolve the secret within the trusted execution code and send only the business result back to the agent. For credentials stored in Foundry project connections, use the connection mechanism described in 4.1.5 instead of giving the model a secret retrieval tool.

Distinguish certificate retrieval from private-key export

A Key Vault certificate has a public X.509 certificate representation and associated key and secret objects with the same name. The Python certificate SDK uses CertificateClient(vault_url=..., credential=...) and get_certificate(name) for certificate retrieval. The secret representation is the route for exporting an exportable certificate’s private material.

Microsoft’s export documentation distinguishes az keyvault certificate download, which downloads the public portion, from az keyvault secret download, which can download the certificate and private key as secret material. A certificate retrieval operation and a secret retrieval operation therefore require different scrutiny even when they address the same certificate name.

Key Vault Certificate User permits reading the full certificate contents, including the secret and key portions. Use it for an approved runtime that needs that certificate material. Key Vault Certificates Officer is a management role, not the default choice for a consumer. If the component only requires public metadata, consider Key Vault Reader rather than granting private-material access.

The certificate’s exportability policy still controls what can be exported. When the private key is nonexportable, retrieving its secret representation does not include that private key. No broad role assignment changes this into an exportable certificate. If the design needs a private key outside the vault, explicitly review exportability and the process that receives the resulting material.

One certificate name therefore leads to public material through certificate retrieval, and to a private key only through the secret representation of an exportable certificate.

Verify allowed and denied operations

Check access using the identity and network path of the deployed adapter. Successful retrieval with your development credentials is not evidence for the runtime assignment. Network controls are a separate requirement; see 4.1.2.

For a secret consumer, verify that get_secret returns the intended value without writing it to logs. Also verify that the same identity cannot create, delete, or retrieve material outside its approved vault scope. For a certificate consumer, test the exact representation needed: public certificate retrieval and private-material export are different acceptance cases.

An authorization failure should lead to inspection of principal, permission model, role, and scope. Do not widen every axis simultaneously. That can produce a working call while losing the evidence of which permission was actually necessary.

Key distinctions and trade-offs

Vault management versus content access: Key Vault Contributor manages the resource; Key Vault Secrets User reads secret contents. One does not imply the other.

Consumer versus operator: Read roles belong to runtime consumers. Officer roles belong to identities that maintain the relevant objects. Separate those responsibilities even if one application team owns both.

Vault scope versus object scope: A deliberately grouped application vault makes vault-scoped assignments understandable. Object-level exceptions support specific sharing cases but should not replace application and environment isolation.

Architecture / decision scenario

A document-signing workflow has a tool adapter that reads a partner API secret and a certificate loader that needs an exportable client certificate. A separate deployment process provisions both. A monitoring component needs only certificate metadata.

A shared vault with a vault-scoped Key Vault Secrets User assignment would let the adapter read the exportable certificate’s private material as well as the partner secret. Give the adapter and certificate-loading application separate vaults for each environment. Assign Key Vault Secrets User to the adapter on its secret vault, Key Vault Certificate User to the loader on its certificate vault, and Key Vault Reader to monitoring on the certificate vault. Neither runtime receives access to the other’s vault. Keep the provisioning identity’s officer permissions separate from those runtime grants.

The adapter calls SecretClient.get_secret; the loader retrieves the approved certificate’s secret representation for private material; monitoring retrieves public certificate information. Verify each call under its deployed principal and test denied management operations. If export fails because the certificate key is nonexportable, reassess the certificate design rather than granting the loader administrator permissions.

Common exam traps

• Granting Key Vault Contributor and expecting secret retrieval to work.
• Treating Key Vault Reader as a secret-value reader.
• Using officer or administrator roles for a read-only runtime.
• Assuming certificate download includes a private key.
• Expecting RBAC to override a certificate’s nonexportable private-key policy.
• Testing only with the developer identity that provisioned the vault.

What to remember

Select the material and retrieval operation first. Configure the RBAC permission model, grant the deployed principal a suitable data-plane read role, and keep operators separate. Public certificate access, secret access, and exportable private material are distinct requirements.

Knowledge check

References

• Microsoft, Use Azure RBAC to control access to keys, certificates, and secrets
• Microsoft, Quickstart: Azure Key Vault secret client library for Python
• Microsoft, Quickstart: Azure Key Vault certificate client library for Python
• Microsoft, Export certificates from Azure Key Vault