Security — both sides of the door

The courier has a valid subscription key and asks for another customer’s order. The gateway knows which subscription was used, but that does not establish whose order the caller may read. Ada checks the access token’s issuer, audience and permissions, then makes sure the backend enforces the order-level rule. The denied request is the point of this class: having one valid key does not satisfy every check along the route.

The gateway has two trust boundaries. At the front, APIM checks the caller’s credential and decides which operations it may use. At the back, the backend checks APIM’s credential and the network path. A signed bearer token and a client certificate solve different problems; neither automatically authorizes an order or payment. The right combination depends on the caller, data, key storage and threat model.

Subscription key

A bearer credential identifying an APIM subscription. It supports separate counters and suspension, but does not prove which person or app holds it.

OAuth2 / JWT

An access token issued by an identity provider. Configure validate-jwt to check the intended issuer, audience, expiry and required claims. A stolen bearer token can still be replayed until it expires or is otherwise blocked.

Client certificate / mTLS

A certificate presented by a client over TLS. APIM must request and validate it. The private key is not sent in the handshake, but it can be copied if poorly stored.

Managed identity

An Azure-managed identity APIM can use to obtain a backend access token without storing a long-lived password in policy. The token still needs careful forwarding and validation.

Named Values / Key Vault

Named values store configuration or reference Key Vault secrets. A vault reference avoids embedding the secret in policy text, but access permissions and refresh behavior still need review.

A caller can send a subscription key in the Ocp-Apim-Subscription-Key header. APIM can associate it with a subscription for access and usage counting. The key does not carry a signed statement about the caller, and it does not expire by itself. Protect it like a credential and combine it with application authentication when the API’s risk warrants it.

For partner operations, require an OAuth2 access token issued for this API. APIM’s validate-jwt policy can check the signature, expiry, issuer, audience and a required role or scope when you configure those checks. A valid token identifies a principal or application represented by its claims; the backend must still authorize the requested action. A stolen bearer token may be replayed during its validity period, so keep its lifetime and storage appropriate to the risk.

This is an illustrative inbound policy fragment. Replace the tenant, audience and role with values from your own app registration, then test valid, expired, wrong-audience and wrong-role tokens:

<!-- inbound: reject anything without a valid Entra token -->
<validate-jwt header-name="Authorization" require-scheme="Bearer"
    failed-validation-httpcode="401"
    failed-validation-error-message="Unauthorized">
  <openid-config url="https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration" />
  <audiences><audience>api://campux-catalog</audience></audiences>
  <required-claims>
    <claim name="roles" match="any"><value>Catalog.Read</value></claim>
  </required-claims>
</validate-jwt>

The gateway now checks more than possession of a subscription key: it validates the access token’s origin, intended API and required claim. A signed token is still a bearer credential. Keep authorization in the backend too, especially for orders, personal data or money.

Validate the credential, then authorize the action.

For a machine-to-machine integration, mTLS can authenticate the client connection using a certificate in addition to the server’s TLS certificate. The client proves possession of its private key without sending that key in the handshake. It is not theft-proof: a private key stored in an exportable file or compromised host can be copied. Plan issuance, storage, rotation and revocation with the partner.

APIM must request the client certificate and validate the certificate properties your design relies on. For Basic v2, Standard v2, Premium v2 and Consumption, Microsoft calls the hostname setting Request client certificate; classic tiers use Negotiate client certificate for the documented HTTP/2 path.¹ Verify the trusted issuer, expected subject or thumbprint, expiry and revocation requirements. Certificate validation authenticates a connection; authorize the payment operation separately.

These controls are complementary, not a universal ranking. A subscription key helps with APIM attribution. An access token carries claims for authorization. A client certificate binds a connection to a private key. A payment processor may need mTLS and a token or other transaction authorization; a public catalog still needs abuse and data-risk review.

Now secure the route from APIM to the backend. When the backend supports Microsoft Entra authentication, APIM can use a managed identity to obtain a short-lived access token for that backend.² This removes a long-lived backend password from policy. The backend must validate the token’s audience and identity and authorize only the intended operations. Restrict direct network access as Part G explains; identity alone does not make APIM the only path.

<!-- inbound: get a token for the backend as APIM's own identity -->
<authentication-managed-identity resource="api://campux-orders"
    output-token-variable-name="msi-token" />
<set-header name="Authorization" exists-action="override">
  <value>@("Bearer " + (string)context.Variables["msi-token"])</value>
</set-header>

The backend should validate the token and allow only the APIM identity intended for that operation. The managed identity removes a stored password, but the access token is still a bearer credential and policy editors can expose or misroute it. Review who can edit APIM policies and where the token is forwarded.

Some backends still require a secret. APIM Named Values can hold plain configuration, an encrypted secret, or a Key Vault secret reference used in policy as {{name}}. Prefer a vault reference for a secret and give APIM’s identity only the access it needs. Microsoft says a changed vault secret can take up to four hours to refresh in APIM, and a versioned reference does not auto-refresh. Test rotation and restrict policy-edit and tracing permissions; a reference keeps the literal secret out of policy text, not beyond reach of every administrator.

The caller-to-APIM and APIM-to-backend boundaries now have explicit checks. Subscription keys support attribution; access tokens or certificates can authenticate a caller when correctly validated; managed identity can authenticate APIM to an Entra-aware backend. None of those alone authorizes every operation or blocks a network route around APIM. Part G tests the network path.