The blog of a cloud agnostic professional and craft beer connoisseur

Using Certificates in Azure API Management

Azure API Management exposes existing back-end services as APIs. Each API Management service is composed of the following key components:

Management plane, exposed as an API, used to configure the service via the Azure portal, PowerShell, and other supported mechanisms.
Gateway (or data plane) is responsible for proxying API requests, applying policies, and collecting telemetry
Developer portal used by developers to discover, learn, and onboard to use the APIs

 

Each of the points of interaction are exposed through a hostname and require a certificate for secure communication. This article lists all possible ways certificates may be used with APIM.

 

APIM uses certificates for

As a hostname certificate for
Management, Cloud Gateway, Source Control, Developer Portal
Self-hosted gateway

As a CA certificate inside the trusted root and intermediate certificate stores
For the Cloud Instance
For self-hosted gateway

As a client certificate
To Authenticate with the backend service
To secure access to APIs

 

Certificated can be signed by a well-known CA or Custom signed. Below sections outlines the steps required for each CA type across the various components

 

Custom Domain with Well-known CA for Cloud Gateway                          

Server certificate associated with the custom domain should be configured on the Custom domain blade in the portal.
The certificate can be uploaded (Custom) or referenced from a Key Vault within the same blade.
This needs to be repeated for each of the component in Management, Cloud Gateway, Source Control and Developer Portal that requires a Custom Domain.

 

Custom Domain with Well-known CA for Self-hosted Gateway

Server certificate associated with the custom domain should be configured on the Custom domain blade in the portal.
The certificate can be uploaded (Custom) or referenced from a Key Vault within the same blade.
Repeat the steps for each of the component in Management, Cloud Gateway, Source Control and Developer Portal that requires a Custom Domain.
Custom domain for self-hosted gateway should be configured in the Hostnames blade on the Self-hosted Gateway in the “Gateways” blade on the portal.
The certificate used in this step should be available in the Certificates tab of the Certificates blade. The certificate can be uploaded (Custom) or referenced from a Key Vault.
The custom domain name for the management endpoint need to be updated for config.service.endpoint of the ConfigMap in the <gateway-name>.yaml file

 

Custom Domain with Custom CA for Cloud Gateway

Server certificate associated with the custom domain should be configured on the Custom domain blade in the portal
The certificate can be uploaded (Custom) or referenced from a Key Vault within the same blade.
Root and intermediate certificates should be uploaded to the CA certificates tab of the Certificates blade
This needs to be repeated for each of the component in Management, Cloud Gateway, Source Control and Developer Portal that requires a Custom Domain.

 

Custom Domain with Custom CA for Self-hosted Gateway

Server certificate associated with the custom domain should be configured on the Custom domain blade in the portal
The certificate can be uploaded (Custom) or referenced from a Key Vault within the same blade.
Root and intermediate certificates should be uploaded to the CA certificates tab of the Certificates blade
This needs to be repeated for each of the component in Management, Cloud Gateway, Source Control and Developer Portal that requires a Custom Domain.
Custom domain for self-hosted gateway should be configured in the Hostnames blade on the Self-hosted Gateway in the Gateways blade on the portal.
The certificate used in this step should be available in the Certificates tab of the Certificates blade. The certificate can be uploaded (Custom) or referenced from a Key Vault.
The custom domain name for the management endpoint need to be updated for config.service.endpoint of the ConfigMap in the <gateway-name>.yaml file
Combined Root and intermediate certificate of the management endpoint should be mounted to the selfhosted gateway container. This is required as the container needs to reach the management endpoint to bootstrap the configuration.
†† If the Root and intermediate certificates of the other endpoints (Cloud Gateway, Source Control, Developer Portal and Self-hosted gateway) are different from the management endpoint, combined root and intermediate certificate for each of those hostnames should be uploaded to the Certificates tab of the Certificates blade and referenced from the REST API as outlined in the Create custom CA for self-hosted gateway section.

 

Client certificate to secure access to the APIs for Cloud Gateway

Select the Negotiate client certificate in the Custom domains blade
Use the validate-client-certificate policy.
If client certificate is self-signed, root (or intermediate) CA certificate(s) must be uploaded to the CA certificates tab of the Certificates blade

 

Client certificate to secure access to the APIs for Self-hosted Gateway

Select the Negotiate client certificate checkbox in the Hostnames blade on the Self-hosted Gateway in the Gateways blade on the portal.
Use the validate-client-certificate policy.
If client certificate is self-signed, combined root and intermediate certificate for each of those hostnames should be uploaded to the Certificates tab of the Certificates blade and referenced from the REST API as outlined in the Create custom CA for self-hosted gateway section.

 

Client certificate to authenticate with backend services (both Cloud and Self-Hosted Gateways)

Set the Gateway credentials to Client cert and select the Client certificate in the backend configuration
The certificate used in this step should be available in the Certificates tab of the Certificates blade. The certificate can be uploaded (Custom) or referenced from a Key Vault.
If client certificate is self-signed, cert chain validation should be disabled using PowerShell cmdlets

 

Backend TLS certificates for Cloud Gateway

If the backend is using self-signed certificates, root (or intermediate) CA certificate(s) of the backend must be uploaded to the CA certificates tab of the Certificates blade

 

Backend TLS certificates for Self-hosted Gateway

†† If the backend is using self-signed certificates, combined root and intermediate certificate of the backend must be uploaded to the CA certificates tab of the Certificates blade and referenced from the REST API as outlined in the Create custom CA for self-hosted gateway section.

Note: APIM supports Basic Auth, Client Cert and Managed Identity for backend authentication.

 

Mounting certificates on the gateway container

Create a configmap with the combined root and intermediate CA certificate

 

kubectl create configmap ca-pemstore –from-file=<myrootca.crt>

 

Update the **{gateway-name}.yml** to mount the configmap. The spec should look like the outline below:

 

spec:
containers:
– name: hosted-apim
image: mcr.microsoft.com/azure-api-management/gateway:latest
volumeMounts:
– name: ca-pemstore
mountPath: /etc/ssl/certs/<myrootca.crt>
subPath: <myrootca.crt>
readOnly: false
ports:
– name: http
containerPort: 8080
– name: https
containerPort: 8081
env:
– name: config.service.auth
valueFrom:
secretKeyRef:
name: hosted-apim-token
key: value
envFrom:
– configMapRef:
name: hosted-apim-env
volumes:
– name: ca-pemstore
configMap:
name: ca-pemstore

 

†† Alternatively, the combined root and intermediate certificates can be mounted to the gateway container.

 

OpenSSL reference commands for self-signed certificates

 

Create self-signed certificates
Conversions

 

## CER to PEM
openssl x509 -inform der -in cert.cer -outform pem -out cert.pem

## CER to PFX without Key
openssl pkcs12 -export -nokeys -in rootca.cer -out rootca.pfx

## CRT to PFX
openssl pkcs12 -export -out cer.pfx -inkey cer.key -in cer.crt

## CRT to PEM
openssl x509 -in cer.crt -out cer.pem

 

Conclusion

Since there are many touchpoints and as the complexity increases with a self-hosted gateway, it is recommended to have all the certificate assets within the APIM instance so that the dependencies can be tracked.