Skip to main content
Version: v2.8.x LTS

Zowe API Mediation Layer Security Overview

Last updated
:  |
... min read
|
Edit this page
PDF
Open doc issue

Zowe API Mediation Layer Security Overview

Review this article to learn about topics which address security features in Zowe API Mediation Layer.

How API ML transport security works​

Security within the API Mediation Layer (API ML) is performed on several levels. This article describes how API ML uses Transport Layer Security (TLS). As a system administrator or API developer, use this guide to familiarize yourself with the following security concepts:

Transport layer security​

The TLS protocol should be used to ensure secure data-transport for all connections to API Mediation Layer services. While it is possible to disable the TLS protocol for debugging purposes or other use-cases, the enabled TLS protocol is the default mode.

Authentication​

Authentication is how an entity, whether it be a user (API Client), or an application (API Service), proves its true identity.

API ML uses the following authentication methods:

  • User ID and password

    • The user ID and password are used to retrieve authentication tokens
    • Requests originate from a user
    • The user ID and password are validated by a z/OS security manager whereby a token is issued that is then used to access the API service

  • TLS client certificates

    • Certificates are used for service-only requests

Zowe API ML services​

The following range of service types apply to the Zoweâ„¢ API ML:

  • Zowe API ML services

    • Gateway Service (GW)
      The Gateway is the access point for API clients that require access to API services. API services can be accessed through the Gateway by API Clients. The Gateway receives information about an API Service from the Discovery Service.

    • Discovery Service (DS)
      The Discovery Service collects information about API services and provides this information to the Gateway and other services. API ML internal services also register to the Discovery Service.

    • API Catalog (AC)
      The Catalog displays information about API services through a web UI. The Catalog receives information about an API service from the Discovery Service.

  • Authentication and Authorization Service (AAS)
    AAS provides authentication and authorization functionality to check user access to resources on z/OS. The API ML uses z/OSMF API for authentication.

  • API Clients
    API Clients are external applications, users, or other API services that access API services through the API Gateway

  • API Services
    API services are applications that are accessed through the API Gateway. API services register themselves to the Discovery Service and can access other services through the Gateway. If an API service is installed so that direct access is possible, API services can access other services without the Gateway. When APIs access other services, they can also function as API clients.

Zowe API ML TLS requirements​

The API ML TLS requires servers to provide HTTPS ports. Each API ML service has the following specific requirements:

  • API Client

    • The API Client is not a server
    • Requires trust of the API Gateway
    • Has a truststore or SAF keyring that contains certificates required to trust the Gateway

  • Gateway Service

    • Provides an HTTPS port
    • Has a keystore or SAF keyring with a server certificate
      • The certificate needs to be trusted by API Clients
      • This certificate should be trusted by web browsers because the API Gateway can be used to display web UIs
    • Has a truststore or SAF keyring that contains certificates needed to trust API Services

  • API Catalog

    • Provides an HTTPS port
    • Has a keystore or SAF keyring with a server certificate
      • The certificate needs to be trusted by the API Gateway
      • This certificate does not need to be trusted by anyone else

  • Discovery Service

    • Provides an HTTPS port
    • Has a keystore or SAF keyring with a server certificate
    • Has a truststore or SAF keyring that contains certificates needed to trust API services

  • API Service

    • Provides an HTTPS port
    • Has a keystore or SAF keyring with a server and client certificate
      • The server certificate needs to be trusted by the Gateway
      • The client certificate needs to be trusted by the Discovery Service
      • The client and server certificates can be the same
      • These certificates do not need to be trusted by anyone else
    • Has a truststore or SAF keyring that contains one or more certificates that are required to trust the Gateway and Discovery Service

Setting ciphers for API ML services​

You can override ciphers that are used by the HTTPS servers in API ML services by configuring properties of the Gateway, Discovery Service, and API Catalog.

Note: You do not need to rebuild JAR files when you override the default values in shell scripts.

The application.yml file contains the default value for each service, and can be found here. The default configuration is packed in .jar files. On z/OS, you can override the default configuration in <RUNTIME_DIR>/components/<APIML_COMPONENT>/bin/start.sh. Add the launch parameter of the shell script to set a cipher:

-Dapiml.security.ciphers=<cipher-list>

On localhost, you can override the default configuration in config/local/gateway-service.yml (including other YAML files for development purposes).

The following list shows the default ciphers. API ML services use the following cipher order:

Note: Ensure that the version of Java you use is compatible with the default cipherset.

   TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
   TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
   TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,
   TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384

Only IANA ciphers names are supported. For more information, see Cipher Suites or List of Ciphers.

JWT Token​

The JWT secret that signs the JWT Token is an asymmetric private key that is generated during Zowe keystore configuration. The JWT token is signed with the RS256 signature algorithm.

You can find the JWT secret, alias localhost, in the PKCS12 keystore that is stored in ${KEYSTORE_DIRECTORY}/localhost/localhost.keystore.p12. The public key necessary to validate the JWT signature is read from the keystore.

You can also use the /gateway/api/v1/auth/keys/public/all endpoint to obtain all public keys that can be used to verify JWT tokens signature in standard JWK format.

z/OSMF JSON Web Tokens Support​

Your z/OSMF instance can be enabled to support JWT tokens as described at Enabling JSON Web Token support. In this case, the Zowe API ML uses this JWT token and does not generate its own Zowe JWT token. All authentication APIs, such as /gateway/api/v1/login and /gateway/api/v1/check function in the same way as without z/OSMF JWT. Gateway service endpoint /gateway/api/v1/auth/keys/public/all serves the z/OSMF JWK that can be used for JWT signature validation.

On this page