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.

 

Posted at https://sl.advdat.com/2ZSkrry