diff --git a/docs/appendix/zowe-yaml-configuration.md b/docs/appendix/zowe-yaml-configuration.md index 5b00a74e44..8569c898a3 100644 --- a/docs/appendix/zowe-yaml-configuration.md +++ b/docs/appendix/zowe-yaml-configuration.md @@ -1,6 +1,6 @@ # Zowe YAML server configuration file reference -Zowe v2 uses a YAML configuration file for server installation, configuration, and runtime. This file is usually referred to as the Zowe configuration YAML file or the `zowe.yaml` file. YAML is a human-friendly data serialization language for all programming languages. To learn more about YAML specifications, see [https://yaml.org/](https://yaml.org/). For a free, offline YAML validator to help validate your syntax, download the [Red Hat's VS Code YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). +Zowe v3 uses a YAML configuration file for server installation, configuration, and runtime. This file is usually referred to as the Zowe configuration YAML file or the `zowe.yaml` file. YAML is a human-friendly data serialization language for all programming languages. To learn more about YAML specifications, see [https://yaml.org/](https://yaml.org/). For a free, offline YAML validator to help validate your syntax, download the [Red Hat's VS Code YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). Content within the YAML file is documented by and validated against schema files which are shipped within Zowe and extended by Zowe extensions. For details on the schema technology and where to find the schema files within our source code, see [Using the Configuration Manager](../user-guide/configmgr-using.md#json-schema-validation). @@ -64,14 +64,14 @@ The YAML configuration file has few high-level sections: ### Extract sharable configuration out of zowe.yaml -The Zowe YAML configuration file supports splitting into several files or PARMLIB members when "zowe.useConfigmgr" is set to true. This can help simplify grouping configuration changes by type or owner. +The Zowe YAML configuration file supports splitting into several files or PARMLIB members. This can help simplify grouping configuration changes by type or owner. More details can be found [in the configmgr documentation.](../user-guide/configmgr-using.md#splitting-configuration-into-multiple-storage-types) ### Creating portable references The Zowe YAML configuration file has template logic for relating one value to another, a system environment variable or symbol, or even to add conditional behavior. -This feature is available when "zowe.useConfigmgr" is set to true, and it can help to make your configuration portable between systems that need slightly different behavior while retaining the same configuration file. +It can help to make your configuration portable between systems that need slightly different behavior while retaining the same configuration file. More details can be found [in the configmgr documentation.](../user-guide/configmgr-using.md#configuration-templates) ### Configuration override @@ -370,8 +370,15 @@ The high-level configuration `java` supports these definitions: - **`home`** Defines the path to the Java runtime directory. +### YAML configurations - node + +The high-level configuration `node` supports these definitions: + +- **`home`** + Defines the path to the Node.js runtime directory. + :::tip -Ensure the value of `node.home` in the `zowe.yaml` is visible to the Zowe STC users, and contains `bin/node`. +Ensure the value of `node.home` in the `zowe.yaml` is visible to the Zowe STC users, and contains `bin/node`. **Example:** ``` node: @@ -380,15 +387,6 @@ node: The above value is valid only when the path `/usrlppSysplex/nodejs/node-v12.16.1/bin/node` exists. If you observe output of `node:...FSUM7351 not found`, check to ensure that the value contains `bin/node`. ::: - - -### YAML configurations - node - -The high-level configuration `node` supports these definitions: - -- **`home`** - Defines the path to the Node.js runtime directory. - ### YAML configurations - zOSMF The high-level configuration `zOSMF` supports these definitions: @@ -421,36 +419,32 @@ These configurations can be used under the `components.gateway` section: Defines the port which the gateway should be started on. This must be a valid port number. - **`debug`** Defines whether to enable debug mode for the Gateway. -- **`apiml.service.allowEncodedSlashes`** - When this parameter is set to `true`, the Gateway allows encoded characters to be part of URL requests redirected through the Gateway. -- **`apiml.service.corsEnabled`** - When this parameter is set to `true`, CORS are enabled in the API Gateway for Gateway routes `gateway/api/v1/**`. -- **`apiml.service.preferIpAddress`** - Set this parameter to `true` to advertise a service IP address instead of its hostname. - - :::note - - This configuration is deprecated. Zowe start script will ignore this value and always set it to `false`. - - ::: +- **`apiml.connectionTimeout`** + Specifies the value in milliseconds which corresponds to the period in which API ML should establish a single, non-managed connection with the service. If omitted, the default value specified in the API ML Gateway service configuration is used. +- **`apiml.connection.idleConnectionTimeoutSeconds`** + Specifies how long will the connection to southbound remains open without communication. The default value is 5 seconds. Unit is second. +- **`apiml.health.protected`** + This property defines whether the health check endpoint is accessible with or without authentication. - **`apiml.gateway.timeoutMillis`** Specifies the timeout for connection to the services in milliseconds. - **`apiml.security.x509.enabled`** Set this parameter to `true` to enable the client certificate authentication functionality through ZSS. - **`apiml.security.x509.externalMapperUrl`** Defines the URL where Gateway can query the mapping of client certificates. +- **`apiml.security.auth.jwt.customAuthHeader`** + Returns valid JWT header also in another header +- **`apiml.security.auth.passticket.customAuthHeader`** + Provides passtickets for the southbound service in the custom header +- **`apiml.security.auth.passticket.customUserHeader`** + Provides User Info when Passticket is provided in the custom header - **`apiml.security.auth.provider`** Defines the authentication provider used by the API Gateway. - **`apiml.security.authorization.endpoint.url`** - Defines the URL to the authorization endpoint. This endpoint tells Gateway if a user has a particular permission on SAF profile. For example, permission to the `APIML.SERVICES` profile of `ZOWE` class. -- **`apiml.security.ssl.verifySslCertificatesOfServices`** - Defines whether APIML should verify certificates of services in strict mode. Setting to `true` will enable the `strict` mode where APIML will validate if the certificate is trusted in truststore, and also if the certificate Common Name or Subject Alternate Name (SAN) matches the service hostname. -- **`apiml.security.ssl.nonStrictVerifySslCertificatesOfServices`** - Defines whether APIML should verify certificates of services in non-strict mode. Setting the value to `true` will enable the `non-strict` mode where APIML will validate if the certificate is trusted in truststore, but ignore the certificate Common Name or Subject Alternate Name (SAN) check. Zowe will ignore this configuration when strict mode is enabled with `apiml.security.ssl.verifySslCertificatesOfServices`. -- **`apiml.server.maxConnectionsPerRoute`** - Specifies the maximum connections for each service. -- **`apiml.server.maxTotalConnections`** - Specifies the total connections for all services registered under API Mediation Layer. + Defines the URL to the authorization endpoint. This endpoint tells Gateway if a user has a particular permission on SAF profile. For example, permission to the `APIML.SERVICES` profile of `ZOWE` class. +- **`apiml.security.personalAccessToken.enabled`** + Enable Personal Access Tokens +- **`apiml.security.useInternalMapper`** + This property is the global feature toggle. Set the value to true to enable Internal Mapper - **`apiml.security.oidc.enabled`** Specifies the global feature toggle. Set the value to `true` to enable OIDC authentication functionality. @@ -473,14 +467,36 @@ User authorization is required to use the `IRR.RUSERMAP` resource within the `FA ::: - **`apiml.security.oidc.identityMapperUrl`** - Defines the URL where the Gateway can query the mapping of the distributed user ID to the mainframe user ID. + Defines the URL where the Gateway can query the mapping of the distributed user ID to the mainframe user ID. This property informs the Gateway about the location of this API. ZSS is the default API provider in Zowe, but if you are using Zowe release 2.14 or a later version, we recommend you use the [API ML internal mapper](../../user-guide/authenticating-with-client-certificates.md#enabling-the-internal-api-ml-mapper). You can provide your own API to perform the mapping. In this case, it is necessary to customize this value. The following URL is the default value for Zowe and ZSS: ``` https://${ZWE_haInstance_hostname}:${GATEWAY_PORT}/zss/api/v1/certificate/dn - ``` + ```- **`apiml.security.ssl.verifySslCertificatesOfServices`** + Defines whether APIML should verify certificates of services in strict mode. Setting to `true` will enable the `strict` mode where APIML will validate if the certificate is trusted in truststore, and also if the certificate Common Name or Subject Alternate Name (SAN) matches the service hostname. +- **`apiml.security.ssl.nonStrictVerifySslCertificatesOfServices`** + Defines whether APIML should verify certificates of services in non-strict mode. Setting the value to `true` will enable the `non-strict` mode where APIML will validate if the certificate is trusted in truststore, but ignore the certificate Common Name or Subject Alternate Name (SAN) check. Zowe will ignore this configuration when strict mode is enabled with `apiml.security.ssl.verifySslCertificatesOfServices`. +- **`apiml.service.allowEncodedSlashes`** + When this parameter is set to `true`, the Gateway allows encoded characters to be part of URL requests redirected through the Gateway. +- **`apiml.service.corsEnabled`** + When this parameter is set to `true`, CORS are enabled in the API Gateway for Gateway routes `gateway/api/v1/**`. +- **`server.maxConnectionsPerRoute`** + Specifies the maximum connections for each service. +- **`server.maxTotalConnections`** + Specifies the total connections for all services registered under API Mediation Layer. +- **`server.ssl.enabled`** + This handles whether TLS is used +- **`server.webSocket.maxIdleTimeout`** + This timeout handles how long the Websocket connection remains open if there is no communication happening over the open connection. The default is one hour (3600000 milliseconds). +- **`server.webSocket.connectTimeout`** + This timeout limits how long the API Gateway waits until it drops connection if it cannot reach the target server. The default is 45 seconds (45000 milliseconds). +- **`server.webSocket.asyncWriteTimeout`** + This timeout handles how long it takes before the server fails with unsuccessful response when trying to write a message to the Websocket connection. The default is 60 seconds (60000 milliseconds). +- **`server.webSocket.requestBufferSize`** + This property handles the max request size allowed in WebSocket handshake requests. The default is 8K. + #### Configure component discovery @@ -490,14 +506,9 @@ These configurations can be used under the `components.discovery` section: Defines the port which discovery should be started on. This may be defined as a valid port number or as an offset from the Gateway component's port. To define an offset enter `"+{offset}"` or `"-{offset}"` as a string. The offset must start with `+` or `-`. - **`debug`** Defines whether to enable debug mode for the Discovery Service. -- **`apiml.service.preferIpAddress`** - Set this parameter to `true` to advertise a service IP address instead of its hostname. - - :::note - - This configuration is deprecated. The Zowe start script will ignore this value and always set it to `false`. - - ::: + +- **`apiml.health.protected`** + This property defines whether the health check endpoint is accessible with or without authentication. - **`apiml.security.ssl.verifySslCertificatesOfServices`** Defines whether APIML should verify certificates of services in strict mode. Setting to `true` will enable the `strict` mode where APIML will validate both if the certificate is trusted in turststore, and also if the certificate Common Name or Subject Alternate Name (SAN) matches the service hostname. - **`apiml.security.ssl.nonStrictVerifySslCertificatesOfServices`** @@ -509,7 +520,8 @@ These configurations can be used under the `components.discovery` section: - **`apiml.discovery.serviceIdPrefixReplacer`** Modifies the service ID of a service instance before it registers to API Mediation Layer. Using this parameter ensures compatibility of services that use a non-conformant organization prefix with v2, based on Zowe v2 conformance. - +- **`server.ssl.enabled`** + This handles whether TLS is used #### Configure component api-catalog @@ -519,14 +531,27 @@ These configurations can be used under the `components.api-catalog` section: Defines the port which API Catalog should be started on. - **`debug`** Defines if we want to enable debug mode for the API Catalog. This is equivalent to the `APIML_DEBUG_MODE_ENABLED` variable but with better granular level. -- **`environment.preferIpAddress`** - Set this parameter to `true` to advertise a service IP address instead of its hostname. - - :::note - - This configuration is deprecated. Zowe start script will ignore this value and always set it to `false`. - ::: +- **`apiml.health.protected`** + This property defines whether the health check endpoint is accessible with or without authentication. +- **`apiml.security.authorization.provider`** + Provider used for SAF resource check +- **`apiml.security.authorization.endpoint.url`** + Base path of endpoint's URL (`{base path}/{userId}/{class}/{entity}/{level}`) +- **`apiml.catalog.customStyle.logo`** + Specifies the location of the logo that will replace the default Zowe logo in the API Catalog header. The supported image formats are: `svg`, `png` and `jpg/jpeg`. +- **`apiml.catalog.customStyle.fontFamily`** + Specifies the font family to use across the API Catalog. +- **`apiml.catalog.customStyle.backgroundColor`** + Specifies the HTML color of the main background across the API Catalog +- **`apiml.catalog.customStyle.titlesColor`** + Specifies the title color. +- **`apiml.catalog.customStyle.headerColor`** + Specifies the HTML color of the header element in the API Catalog home page +- **`apiml.catalog.customStyle.textColor`** + Specifies the HTML color of the main text across the API Catalog +- **`apiml.catalog.customStyle.docLink`** + Specifies a custom link to be displayed in the header. Use this property to refer to applicable documentation. The format is `|` #### Configure component caching-service @@ -573,15 +598,6 @@ These configurations can be used under the `components.caching-service` section: Specifies the truststore file used to keep other parties public keys and certificates. - **`storage.redis.ssl.truststorePassword`** Specifies the password used to unlock the truststore. -- **`environment.preferIpAddress`** - Set this parameter to `true` to advertise a service IP address instead of its hostname. - - :::note - - This configuration is deprecated. Zowe start script will ignore this value and always set it to `false`. - - ::: - - **`apiml.security.ssl.verifySslCertificatesOfServices`** Specifies whether APIML should verify certificates of services in strict mode. Set to `true` will enable `strict` mode that APIML will validate both if the certificate is trusted in turststore, and also if the certificate Common Name or Subject Alternate Name (SAN) match the service hostname. - **`apiml.security.ssl.nonStrictVerifySslCertificatesOfServices`** diff --git a/docs/getting-started/zowe-architecture.md b/docs/getting-started/zowe-architecture.md index 83c582fad9..0e4c1ba450 100644 --- a/docs/getting-started/zowe-architecture.md +++ b/docs/getting-started/zowe-architecture.md @@ -75,7 +75,16 @@ ZIS is a z/OS native, authorized cross-memory server that allows a secure and co Unlike all of the servers described above which run under the `ZWESLSTC` started task as address spaces for USS processes, the Cross Memory server has its own separate started task `ZWESISTC` and its own user ID `ZWESIUSR` that runs the program `ZWESIS01`. -## API Gateway +## API Mediation Layer + +The API Mediation Layer is a collection of services for management and administration of APIs, and is comprised of the following components that are described in detail below: + +* API Gateway +* API Catalog +* API Discovery +* Caching service + +### API Gateway The API Gateway is a proxy server that routes requests from clients on its northbound or upstream edge, such as web browsers or the Zowe command line interface, to servers on its southbound (downstream) edge that are able to provide data to serve the request. The API Gateway is also responsible for generating the authentication token used to provide single sign-on (SSO) functionality. The API Gateway homepage is `https://:7554`. Following authentication, this URL enables users to navigate to the API Catalog. @@ -84,17 +93,17 @@ The API Gateway is a proxy server that routes requests from clients on its north When the API Gateway is running, this server is accessible at `https://:7554/`. When running on z/OS, the server uses the jobname suffix of AG. -## API Catalog +### API Catalog The API Catalog provides a list of the API services that have registered themselves as catalog tiles. These tiles make it possible to view the available APIs from Zowe's southbound (downstream) servers, as well as test REST API calls. ![Zowe API Catalog](../images/api-mediation/api-catalog.png) When the API Gateway is running, this server is accessible at `https://:7554/apicatalog/ui/v1`. -When the API Catalog is running, this server's API documentation is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://:7554/apicatalog/ui/v1/#/tile/apimediationlayer/apicatalog` +When the API Catalog is running, the API documentation of this server is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://:7554/apicatalog/ui/v1/#/tile/apimediationlayer/apicatalog` When running on z/OS, the server uses the jobname suffix of AC. -## API Discovery +### API Discovery The API Discovery server acts as the registration service broker between the API Gateway and its southbound (downstream) servers. This server can be accessed through the URL `https://:7552` making it possible to view a list of registered API services on the API discovery homepage. @@ -102,13 +111,13 @@ The API Discovery server acts as the registration service broker between the API When running on z/OS, the server uses the jobname suffix of AD. -## Caching service +### Caching service The Caching service aims to provide an API which offers the possibility to store, retrieve, and delete data associated with keys. The service is used only by internal Zowe applications and is not exposed to the internet. The Caching service URL is `https://:7555`. For more information about the Caching service, see [Using the Caching Service](../user-guide/api-mediation/api-mediation-caching-service). When the API Gateway is running, this server is accessible at `https://:7554/cachingservice/api/v1`. -When the API Catalog is running, this server's API documentation is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://:7554/apicatalog/ui/v1/#/tile/zowe/cachingservice`. +When the API Catalog is running, the API documentation of this server is accessible at the API Catalog tile `Zowe Applications` which can be viewed at `https://:7554/apicatalog/ui/v1/#/tile/zowe/cachingservice`. When running on z/OS, the server uses the jobname suffix of CS. ## Desktop Apps diff --git a/docs/images/common/zowe-architecture copy.png b/docs/images/common/zowe-architecture copy.png new file mode 100644 index 0000000000..a8e5a6ee07 Binary files /dev/null and b/docs/images/common/zowe-architecture copy.png differ diff --git a/docs/images/common/zowe-architecture-docker copy.png b/docs/images/common/zowe-architecture-docker copy.png new file mode 100644 index 0000000000..26af21a1f9 Binary files /dev/null and b/docs/images/common/zowe-architecture-docker copy.png differ diff --git a/docs/images/common/zowe-architecture-ha copy.png b/docs/images/common/zowe-architecture-ha copy.png new file mode 100644 index 0000000000..07a4d8085c Binary files /dev/null and b/docs/images/common/zowe-architecture-ha copy.png differ diff --git a/docs/images/common/zowe-architecture-k8s copy.png b/docs/images/common/zowe-architecture-k8s copy.png new file mode 100644 index 0000000000..6254ba16a6 Binary files /dev/null and b/docs/images/common/zowe-architecture-k8s copy.png differ diff --git a/docs/user-guide/api-mediation/configuration-connection-limits.md b/docs/user-guide/api-mediation/configuration-connection-limits.md index 93083dd415..b80a941b9c 100644 --- a/docs/user-guide/api-mediation/configuration-connection-limits.md +++ b/docs/user-guide/api-mediation/configuration-connection-limits.md @@ -33,8 +33,7 @@ zowe: Use the following procedure to change the limits: 1. Open the file `zowe.yaml`. -2. Find or add the property `zowe.components.gateway.server.websocket.connectTimeout`, and set the value to an appropriate positive integer. This timeout limits how long the API Gateway waits until it drops connection if it cannot reach the target server. The default is 45 seconds (45000 milliseconds). -3. Find or add the property `zowe.components.gateway.server.websocket.stopTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the API Gateway will wait for the graceful stopping of the WebSocket connection. The default is 30 seconds (30000 milliseconds). -4. Find or add the property `zowe.components.gateway.server.websocket.asyncWriteTimeout`, and set the value to an appropriate positive integer. This timeout handles how long it takes before the server fails with unsuccessful response when trying to write a message to the Websocket connection. The default is 60 seconds (60000 milliseconds). -5. Find or add the property `zowe.components.gateway.server.websocket.maxIdleTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the Websocket connection remains open if there is no communication happening over the open connection. The default is one hour (3600000 milliseconds). -6. Find or add the property `zowe.components.gateway.server.websocket.requestBufferSize` and set the value to an appropriate positive integer. This property handles the max request size allowed in WebSocket handshake requests. The default is 8K. +2. Find or add the property `components.gateway.server.websocket.connectTimeout`, and set the value to an appropriate positive integer. This timeout limits how long the API Gateway waits until it drops connection if it cannot reach the target server. The default is 45 seconds (45000 milliseconds). +3. Find or add the property `components.gateway.server.websocket.asyncWriteTimeout`, and set the value to an appropriate positive integer. This timeout handles how long it takes before the server fails with unsuccessful response when trying to write a message to the Websocket connection. The default is 60 seconds (60000 milliseconds). +4. Find or add the property `components.gateway.server.websocket.maxIdleTimeout`, and set the value to an appropriate positive integer. This timeout handles how long the Websocket connection remains open if there is no communication happening over the open connection. The default is one hour (3600000 milliseconds). +5. Find or add the property `components.gateway.server.websocket.requestBufferSize` and set the value to an appropriate positive integer. This property handles the max request size allowed in WebSocket handshake requests. The default is 8K. diff --git a/docs/user-guide/api-mediation/configuration-gateway-timeouts.md b/docs/user-guide/api-mediation/configuration-gateway-timeouts.md index 593ffb6cdf..0601201083 100644 --- a/docs/user-guide/api-mediation/configuration-gateway-timeouts.md +++ b/docs/user-guide/api-mediation/configuration-gateway-timeouts.md @@ -8,35 +8,22 @@ Use the following procedure to change the global timeout value for an API Mediat 1. Open the file `zowe.yaml`. 2. Configure the following properties: - * **components.gateway.apiml.gateway.timeoutmillis** - This property defines the global value for http/ws client timeout. - - :::note - Ribbon configures the client that connects to the routed services. - ::: - * **components.gateway.ribbon.connectTimeout** + * **components.gateway.apiml.connectTimeout** Specifies the value in milliseconds which corresponds to the period in which API ML should establish a single, non-managed connection with the service. If omitted, the default value specified in the API ML Gateway service configuration is used. + * **components.gateway.apiml.connection.idleConnectionTimeoutSeconds** - * **components.gateway.ribbon.readTimeout** - Specifies the time in milliseconds of inactivity between two packets in response from this service to API ML. If omitted, the default value specified in the API ML Gateway service configuration is used. - - * **components.gateway.ribbon.connectionManagerTimeout** - The HttpClient employs a special entity to manage access to HTTP connections called by the HTTP connection manager. The purpose of an HTTP connection manager is to serve as a factory for new HTTP connections, to manage the life cycle of persistent connections, and to synchronize access to persistent connections. Internally, the connections that are managed serve as proxies for real connections. `ConnectionManagerTimeout` specifies a period during which managed connections with API ML should be established. The value is in milliseconds. If omitted, the default value specified in the API ML Gateway service configuration is used. - - * **components.gateway.httpclient.requestConnectionTimeout** - Specifies the HTTP Client Request Connection Timeout for southbound services from the API Gateway. This setting defines the period that the API Gateway waits for a response from the southbound server before issuing a connection refused response. The value is in milliseconds. An example value of a 30 second connection timeout would be 30000. + * **components.gateway.apiml.connection.timeToLive** **Example:** ```yaml components: gateway: - ribbon: + apiml: connectTimeout: 30000 - readTimeout: 60000 - connectionManagerTimeout: 45000 - httpclient: - requestConnectionTimeout: 60000 + connection: + idleConnectionTimeoutSeconds: + timeToLive: ``` 3. Restart Zowe. diff --git a/docs/user-guide/api-mediation/configuration-health-endpoint-protection.md b/docs/user-guide/api-mediation/configuration-health-endpoint-protection.md index 2e0c05e4ae..c1a7032f22 100644 --- a/docs/user-guide/api-mediation/configuration-health-endpoint-protection.md +++ b/docs/user-guide/api-mediation/configuration-health-endpoint-protection.md @@ -1,43 +1,48 @@ -# Configuring API Gateway Health Check Protection +# Configuring Health Check Protection :::info Role: system programmer ::: -As a system programmer, you can configure the security setting for the health check endpoint of the API Gateway. This setting determines whether the health check endpoint is accessible without authentication, or alternatively requires authentication. Enabling protection for the health check endpoint can enhance the security of the API Gateway by restricting access to sensitive status information about the Gateway. +As a system programmer, you can disable the security setting for the health check endpoint of the API Gateway. This setting determines whether the health check endpoint is accessible without authentication, or alternatively requires authentication. In Zowe V2, authentication was not required. Disabling protection for the health check endpoint can limit the security of the API Gateway by allowing access to sensitive status information about the Gateway. Use the following procedure to set the value of the health check endpoint of the API Gateway: 1. Open the file `zowe.yaml`. 2. Configure the following property: -* `components.gateway.apiml.gateway.health.protected` +* `components.gateway.apiml.health.protected` This property defines whether the health check endpoint is accessible with or without authentication. :::note -The default value of this parameter is `false`. We recommend setting this parameter to `true` for production environments. +The default value of this parameter is `true`. ::: **Example:** ```yaml -zowe: - components: +components: gateway: - apiml: - gateway: - health: - protected: true + apiml: + gateway: + health: + protected: true ``` -In this example, setting `protected` to `true` protects the health check endpoint by requiring authentication. Only authenticated users can access the health check endpoint. This ensures that sensitive information about the status of the Gateway is not exposed to unauthenticated users. +In this example, setting `protected` to `true` protects the health check endpoint by requiring authentication. Only authenticated users can access the health check endpoint. Requiring authentication ensures that sensitive information about the status of the Gateway is not exposed to unauthenticated users. To allow open access to the health check endpoint, set the parameter to `false`. Setting this parameter to `false` permits access to this endpoint without authentication. In this case, anyone can access the health check endpoint and obtain information about the status of the Gateway. +* `components.discovery.apiml.health.protected` + This property defines whether the health check endpoint on Discovery service is accessible with or without authentication. +* `components.apiCatalog.apiml.health.protected` + This property defines whether the health check endpoint on API Catalog is accessible with or without authentication. + + ## Environment Recommendations When setting this parameter, we recommend applying the following values according to your environment: * **In Production Environments** -It is recommended to set `apiml.gateway.health.protected` to `true` to enhance security and protect sensitive information about the API Gateway's health status. +It is recommended to set `components.*.apiml.health.protected` to `true` to enhance security and protect sensitive information about the API Gateway's health status. This is the default. * **In Development/Testing Environments** - setting `apiml.gateway.health.protected` to `false` can simplify the testing process, reduce development overhead, and assist with debugging. + setting `components.*.apiml.health.protected` to `false` can simplify the testing process, reduce development overhead, and assist with debugging. diff --git a/docs/user-guide/api-mediation/configuration-personal-access-token.md b/docs/user-guide/api-mediation/configuration-personal-access-token.md index afe3a147da..890a9d7a71 100644 --- a/docs/user-guide/api-mediation/configuration-personal-access-token.md +++ b/docs/user-guide/api-mediation/configuration-personal-access-token.md @@ -10,18 +10,17 @@ Review this article for steps that enable single sign on via Personal Access Tok To enable Personal Access Token support when using the Caching Service, **Infinispan** is the required storage solution. Infinispan is part of Zowe installation. No additional software or installation is required when using this storage solution. -To enable this storage method, set the value of `zowe.components.caching-service.storage.mode` to `infinispan` in the `zowe.yaml` configuration file. Infinispan environment variables are not currently following the v2 naming convention, so they must be defined into `zowe.environments` section. For more information on these properties and their values see [Infinispan configuration](../../extend/extend-apiml/api-mediation-infinispan.md#infinispan-configuration). +To enable this storage method, set the value of `components.caching-service.storage.mode` to `infinispan` in the `zowe.yaml` configuration file. For more information on other properties for infinispan and their values see [Infinispan configuration](../../extend/extend-apiml/api-mediation-infinispan.md#infinispan-configuration). ``` yaml - zowe - components: - caching-service: - storage: - mode: infinispan - infinispan: - jgroups: - port: 7098 + components: + caching-service: + storage: + mode: infinispan + infinispan: + jgroups: + port: 7098 ``` ## Enabling Personal Access Tokens