Configuring application authentication for an API

Using this topic, you can configure application authentication for an API.

1. Open the API for editing, as described in Editing an OpenAPI 2.0 API definition.
2. Enable application authentication, as follows:
   Note: To identify the application, you must enable a security requirement of type clientID.
   1. On the API Design page, select the Gateway tab and expand Gateway and portal settings.
   2. In the navigation pane, click Application Authentication.
3. You can select whether a client certificate is sent as a TLS client certificate or in an HTTP header. Specify how the client certificate is sent to the gateway, as follows:

   You can choose to send the client certificate as a TLS client certificate, or to include it in the API's HTTP header.

   1. In the navigation pane, click Application Authentication.
      Any existing application authentication source definitions are listed.
   2. On the Application Authentication page, select Certificate.
   3. In the Application pane, click Application authentication source.
   4. On the Application authentication source page, click Add.
   5. In the Add shema dialog box, select the required option .
      • tls-cert - When the API is called, the TLS client certificate is sent to the Gateway service and is used to verify that the API caller holds the corresponding private key.
      • header - When the API is called, an X509 client certificate must be supplied in the specified HTTP header. 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. 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.

      Attention: Sending the client certificate in an HTTP header does not allow for cryptographic verification that the caller holds the corresponding private key. The only validation performed is a string comparison of the base64-encoded PEM file against the client certificate.
   6. If you select the tls-cert option, enable mTLS at the Gateway level.

      Enable mTLS by setting "Mutual authentication: Required" (or "Requested" if not all APIs use mTLS) in the TLS Server Profile that is specified for the API invocation endpoint in your gateway service configuration. The gateway service is configured in the Cloud Manager UI (requires cloud administrator permissions). For more information, see Registering a gateway service and TLS profiles overview.

      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 are registered with different end certificates in the Developer Portal, which have the same intermediate or root CA issuer. The certificate passes Gateway-level mTLS if it matches the issuer available in the truststore, but allows access only to the API that matches the correct end certificate.
4. Click Add.
5. Click Save to save your changes.