Application authentication settings allow you to protect your API with a certificate, for example, by using TLS mutual authentication. You can select whether
a client certificate is sent as a TLS client certificate or in an HTTP header.
About this task
You can complete this task either by using the API Designer UI application, or by using the
browser-based API Manager UI.
At any time, you can switch directly to the underlying OpenAPI YAML
source by clicking the Source icon
.
To return to the design form, click the Form icon
.
Procedure
- Open the API for editing, as described in Editing an OpenAPI 2.0 API
definition.
- Enable application authentication, as follows:
Note: To identify the application, you must enable a security requirement of type
clientID
.
- Select the Gateway tab, expand Gateway and portal
settings, then click Application Authentication.
- Select Certificate.
- Specify how the client certificate is sent to the gateway, as follows:
- In the navigation pane, click Application Authentication
Source.
Any existing application authentication source definitions are
listed.
- Alongside Application Authentication Source, click
Add.
- Select the required option,
header or
tls-cert.
You can separately add one or both of the options.When the
API is called, an X509 client certificate must be supplied, either in
the specified HTTP header, or as a TLS client certificate from TLS mutual
authentication. For any Developer Portal
application that calls the API, the certificate must be entered in the Developer Portal user
interface; for details, see Registering an application.
The Gateway service to
which the API is published can be configured to use TLS mutual authentication to secure API calls
made to that Gateway service; for details, see Configuring the initial
Gateway service. If you select this option, continue to sub-step d.
If you are using a
load balancer, you must configure the load balancer to use the specified HTTP header to
relay the appropriate client certificate to the Gateway service after the load balancer terminates
the TLS communication.
- If you select the tls-cert option, enable
mTLS at the Gateway level.
This can be done by enabling "Mutual authentication: Required" in the TLS Server Profile
configured in the Gateway Service in the Cloud Manager Topology (requires cloud administrator
permissions). For information, see Registering a gateway service.
You can create a Truststore (with the root or intermediate CA certificate) for use with the TLS
Server Profile.
The following example cURL command uses a client-cert during SSL:
**curl -X GET 'https://GW-Server:9443/test/sandbox/mtls-testing/callmtls-call' -H 'X-IBM-Client-Id: 1872xxxxxxxxxxxxx' --cert my-leaf-cert.pem --key my-leaf-cert.key -k -v**
Note: This feature is intended for the scenario where different applications will be registered with
different end certificates in the Developer Portal, which will have the same intermediate or root CA
issuer. The certificate will pass Gateway-level mTLS if it matches the issuer available in the
Truststore, but will only allow access the to API that matches the correct end certificate.
- Click Create.
-
Click Save to save your changes.