diff --git a/docs/appendix/zowe-yaml-configuration.md b/docs/appendix/zowe-yaml-configuration.md index fc123fe615..b81e12dcd0 100644 --- a/docs/appendix/zowe-yaml-configuration.md +++ b/docs/appendix/zowe-yaml-configuration.md @@ -442,13 +442,43 @@ These configurations can be used under the `components.gateway` section: - **`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 turststore, and also if the certificate Common Name or Subject Alternate Name (SAN) matches the service hostname. + 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 turststore, 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`. + 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. +- **`apiml.security.oidc.enabled`** + Specifies the global feature toggle. Set the value to `true` to enable OIDC authentication functionality. + +- **`apiml.security.oidc.registry`** + Specifies the SAF registry used to group the identities recognized as having an OIDC identity mapping. The registry name is the string used during the creation of the mapping between the distributed and mainframe user identities. For more information, see the [ESM configuration](#esm-configuration). + +- **`apiml.security.oidc.jwks.uri`** + Specifies the URI obtained from the authorization server's metadata where the Gateway will query for the JWK used to sign and verify the access tokens. + +- **`apiml.security.oidc.jwks.refreshInternalHours`** + Specifies the frequency in hours to refresh the JWK keys from the OIDC provider. Defaults to one hour. + +- **`apiml.security.oidc.identityMapperUser`** + (Optional) If the userId is different from the default Zowe runtime userId (`ZWESVUSR`), specify the `identityMapperUser` userId to configure API ML access to the external user identity mapper. + +:::note + +User authorization is required to use the `IRR.RUSERMAP` resource within the `FACILITY` class. The default value is `ZWESVUSR`. Permissions are set up during installation with the `ZWESECUR` JCL or workflow. To authenticate to the mapping API, a JWT is sent with the request. The token represents the user that is configured with this property. + +::: + +- **`apiml.security.oidc.identityMapperUrl`** + 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 + ``` #### Configure component discovery @@ -512,6 +542,18 @@ These configurations can be used under the `components.caching-service` section: Specifies eviction strategy to be used when the storage size is achieved. - **`storage.vsam.name`** Specifies the data set name of the caching service VSAM data set. +- **`storage.infinispan.initialHosts`** + + This property specifies the list of cluster nodes (members). In case of multiple instances, the value for each Caching Service instance can be either a list of all the members, separated by a comma, or just the replica. The format is `${haInstance.hostname}[${zowe.components.caching-service.storage.infinispan.jgroups.port}]`. + +- **`storage.infinispan.persistence.dataLocation`** + + The path where the Soft-Index store keeps its data files for the Infinispan Soft-Index Cache Store. + The default value is `data`. If you run the Caching Service in Highly Available mode and the instances use the same filesystem, you have to specify a different value of the `CACHING_STORAGE_INFINISPAN_PERSISTENCE_DATALOCATION` property for each instance. For more information, see the [Soft-Index File Store](https://infinispan.org/blog/2014/10/31/soft-index-file-store). + +- **`storage.infinispan.jgroups.port`** + + The port number used by Infinispan to synchronise data among caching-service instances. - **`storage.redis.masterNodeUri`** Specifies the URI used to connect to the Redis master instance in the form `username:password@host:port`. - **`storage.redis.timeout`** diff --git a/docs/contribute/contributing.md b/docs/contribute/contributing.md index 1ced6a027f..fc431b7ff5 100644 --- a/docs/contribute/contributing.md +++ b/docs/contribute/contributing.md @@ -10,7 +10,7 @@ Before contributing a documentation change to the repository, you should be fami * Slack: The Zowe Documentation team communicates using the Slack application. To learn about Slack, refer to the [Slack Help Center](https://slack.com/help). The Zowe team is part of the [Open Mainframe Project](https://openmainframeproject.slack.com) channel. * Markdown Language: The Zowe documentation is written in Markdown language. To learn about Markdown, refer to [The Markdown Guide](https://www.markdownguide.org/). -In addition to being familiar with the Zowe community and how we work together, you will need to sign the CNCF Contributor License Agreement. The Contributor License Agreement defines the terms under which you contribute to Zowe documentation. Contributions to Zowe documentation are reviewed before being committed to the repository. Committing changes to the Zowe repository requires additional access rights. See https://github.com/zowe/community/blob/master/COMMITTERS.md. Also see Participating in Zowe Documentation for more details about roles and permissions. +Contributions to Zowe documentation are reviewed before being committed to the repository. Commits needs to have Developer Certificate of Origin (DCO). Committing changes to the Zowe repository requires additional access rights. See https://github.com/zowe/community/blob/master/COMMITTERS.md. Also see Participating in Zowe Documentation for more details about roles and permissions. ## Getting started checklist diff --git a/docs/contribute/guidelines-code/categories.md b/docs/contribute/guidelines-code/categories.md index 30a534e380..bce5a942f8 100644 --- a/docs/contribute/guidelines-code/categories.md +++ b/docs/contribute/guidelines-code/categories.md @@ -17,9 +17,13 @@ For each area of the codebase, there are established and favored programming lan - **CLI** - Node.js, TypeScript - **Desktop UI** - Node.js, JavaScript - **APIs** - C, Assembler, Java, Spring -- **API Mediation Layer** - Java, Spring +- **API Mediation Layer** - Java, Spring, JavaScript -**Note:** JavaScript is not recommended and should be avoided in favor of Typescript to utilize typing. +:::note + +JavaScript is not recommended and should be avoided in favor of Typescript to utilize typing. + +::: ## Component-specific guidelines and tutorials diff --git a/docs/extend/dynamic-static-registration-overview.md b/docs/extend/dynamic-static-registration-overview.md deleted file mode 100644 index 272a5f6fa1..0000000000 --- a/docs/extend/dynamic-static-registration-overview.md +++ /dev/null @@ -1,21 +0,0 @@ -# Dynamic and static registrtion overview - -Zowe API Mediation Layer extenders can build and onboard additional API services to the API ML microservices ecosystem. REST APIs can register with the API Mediation Layer, which makes them available in the API Catalog and for routing through the API Gateway. - -To register a z/OS service with the API Mediation Layer, there are two approaches: -- [Dynamic API registration](#dynamic-api-registration) -- [Static API registration](#static-api-registration) - -For information about how to onboard REST APIs, see the [Onboarding Overview](extend-apiml/onboard-overview.md). - -To streamline the process of onboarding new REST API services to the API Mediation Layer, see [Onboarding a REST API service with the YAML Wizard](../user-guide/onboard-wizard.md). - -### Dynamic API registration - -Registration of a REST API service to the API ML is performed through a call to the Discovery Service by sending registration data and metadata for the service being registered. Registration requires that the z/OS service must know the web address of the API ML Discovery Service. When Dynamic registration is performed, the service that performs the registration must periodically send heartbeat requests to the Discovery Service for each registered service instance. These heartbeat requests serve to renew the corresponding service instance registration with API ML. These requests enable the Discovery Service to monitor the availability of registered service instances. Services that are registered dynamically display the status of the service in the API Catalog after initial service registration. - -For more information about how to build a service which is able to register, see the [Onboarding Overview](extend-apiml/onboard-overview.md). - -### Static API registration - -For services that cannot be modified to be dynamically discoverable, it is possible onboard them to the API ML by providing the API ML a static definition file with API service details. This registration method does not require modifications to the existing API service code. For more information, see [Onboard a REST API without code changes required](extend-apiml/onboard-static-definition.md). Unlike services that use Dynamic API registration, the status of services onboarded through Static API registration is not displayed in the API Catalog. diff --git a/docs/extend/extend-api/ReactJSUI.md b/docs/extend/extend-api/ReactJSUI.md deleted file mode 100644 index cc66b211b4..0000000000 --- a/docs/extend/extend-api/ReactJSUI.md +++ /dev/null @@ -1,192 +0,0 @@ -# Creating a Zowe integrated ReactJS UI - -One of the great things about working with Zowe is that you can include any UI's that you have already developed in your Zowe Virtual Desktop. In this blog we look at how we do this and also show how to take advantage of a Restful API created on a JEE server within the Zowe environment. - -![](../../images/samples/reactjs/overview.png) - -Take a look at the [Creating a RestAPI with Swagger documentation using Liberty](./libertyAPI) tutorial for the background to the Restful API with Swagger documentation we will be using. - -## Prerequisite skills - -Knowledge of the following development technologies is beneficial: - -- React -- Redux -- Consuming Rest API's - -## Examining the App Structure - -First download the sample app found [here](https://github.com/zowe/webui-scenarios/tree/master/basic-react). We will not be examining the entire sample, but it is included as an example and boilerplate that can be built off of. - -Looking at the sample app their are 2 main sections that are important to us: - -- Constants.js -- actions/actions.js. - -### Constants.js - -Lets first examine Constants.js. - -```javascript -let host = ':' -if (typeof location !== 'undefined') { - const hostname = location.hostname - if (hostname !== 'localhost') { - host = location.host - } -} - -export const BASE_SERVER_URL = host -export const BASE_URL = `https://${host}` -export const BASE_WS_URL = `wss://${host}` -``` - -Notice that here we are setting our 'host' for the app. We are connecting to hypothetical server and the default port for the MVD 7445. This host then gets wrapped in a 'BASE_URL' constant that we can use in other sections of our app. Change this line to connect to your own server and port. - -### Actions.js - -Next lets look at calling our API created in the [creating a RestAPI with Swagger documentation using Liberty](./libertyAPI) tutorial. Following Redux structure, this call will be in our action.js file. We won't be looking at the entire file, but instead the relevant fetch request. - -```javascript -function fetchPosts(subreddit) { - return dispatch => { - dispatch(requestPosts(subreddit)) - let header = new Headers({ - 'Access-Control-Allow-Origin': '*', - 'Content-Type': 'multipart/form-data' - }) - return fetch(`${BASE_URL}/jzos/environmentVariable`, { - header: header, - credentials: 'include' - }) - .then(response => response.json()) - .then(json => dispatch(receivePosts(subreddit, json))) - .catch(error => console.log(error)) - } -} -``` - -Note that we are using the [fetch api](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to the grab the `environmentVariable` from the host that we defined before. We then make the rest of our app aware of the response using Redux's 'dispatch' method. - -## Adding your App to the MVD - -While the zlux environment comes with predefined "apps" and explorers, you also have the ability to extend the system and add your own apps. - -### Building your App for the MVD. - -Before we can place our app on the MVD, we need to first 'build' a production version of it and place it in a folder where Zowe can read it. -Zowe looks in a folder called 'web' when looking for an entry point to new apps. - -In order to build and prepare your app: - -1. Run the `build` script in `package.json` using: - - - `npm run build` - -2. Create a folder for your project and a new `web` folder inside it. - - - EX: `/Desktop/` and `Desktop//web` - -3. Copy built project into `Desktop//web` - - If using the sample, copy `app.min.js` , `index.html` , `icon.png` and `css` into to `/Desktop//web/` - -### Configuring your app for Zowe - -In order for Zowe to be aware of an app, a pluginDefintion.json file must be included in the root of the project. This file lets Zowe know information about the framework used, reference files, and basic configuration for the app. Lets take a look at our pluginDefinition: - -```json -{ - "identifier": "com.rs.basic-react", - "apiVersion": "1.0", - "pluginVersion": "1.0", - "pluginType": "application", - "webContent": { - "framework": "iframe", - "launchDefinition": { - "pluginShortNameKey": "basic-react", - "pluginShortNameDefault": "IFrame", - "imageSrc": "icon.png" - }, - "descriptionKey": "Sample App Showcasing IFrame Adapter", - "descriptionDefault": "Sample App Showcasing IFrame Adapter", - "startingPage": "index.html", - "isSingleWindowApp": true, - "defaultWindowStyle": { - "width": 800, - "height": 420, - "x": 200, - "y": 50 - } - }, - "dataServices": [] -} -``` - -Next add this pluginDefinition to the root of your project: - -- EX: `Desktop//` - -### Explaining the Plugin file system - -To add new apps, files must be added in two locations. - -- Zowe root (`/zaas1/zowe/`) -- Plugins Folder (`/zaas1/zowe//zlux-example-server/plugins`) - -Inside the 'Plugins Folder' we will add our identifier named `com.basic-react.json`. Inside this json file the **plugin location** and the **identifier name** are specified. Our identifier will look like this: - -```json -{ - "identifier": "com.rs.basic-react", - "pluginLocation": "../../" -} -``` - -To add our app to the file system: - -1. Copy project from `/Desktop` to `/` on your server - - - Use `scp @ /Users/path/to/files /` - - Alternatively this can be done using SFTP or the ZOS Explorer in binary mode. - -2. Create our identifier within the plugins folder (`/zlux-example-server/plugins`): - - - `touch com.basic-react.json` - -3. Edit file with vi to read: - -```json -{ - "identifier": "com.", - "pluginLocation": "../../" -} -``` - -### Deploying your App - -In order to deploy our newly added app, - -1. Run `./deploy.sh` found in `/zaas1/zowe//zlux-build` -2. Run `./zowe-stop.sh` found in `/zaas1/zowe//scripts` -3. Run `./zowe-start.sh` found in `/zaas1/zowe//scripts` - -## Setting up the server for Development - -:::warning -This next section should only be changed for development purposes. -::: - -While not necessary depending on your system configuration, often will need to allow our server to accept incoming connections and avoid CORS errors. - -In order to update the server to accept all connections: - -- Navigate to `/explorer-server/wlp/usr/servers/Atlas/server.xml` -- Open the file with vi and paste the following code in. - -```javascript - - - -``` - -After adding this section, navigate to `https://:/ZLUX/plugins/com.rs.mvd/web/` and you should see your new app added to the MVD! diff --git a/docs/extend/extend-api/api-intro.md b/docs/extend/extend-api/api-intro.md deleted file mode 100644 index a8cf14ddf8..0000000000 --- a/docs/extend/extend-api/api-intro.md +++ /dev/null @@ -1,3 +0,0 @@ -# API Extension Samples - -These samples show users how to create their own API's using a Node or Liberty Server. diff --git a/docs/extend/extend-api/existingAPI.md b/docs/extend/extend-api/existingAPI.md deleted file mode 100644 index 9507e3a311..0000000000 --- a/docs/extend/extend-api/existingAPI.md +++ /dev/null @@ -1,128 +0,0 @@ -# Onboarding existing Rest API Script - -(WORK IN PROGRESS) - -In this tutorial we consider how an organization with a product or tool with an existing Rest API can be rapidly Onboarded to Zowe™ by getting that product or tool registered with the API Gateway. This would then allow the product to be available from a central location and benefit from other Zowe API Mediation layer functionality. To do this we need a method for defining the service to the gateway - -As the example product we are using a simple Spring Boot sample app that can be downloaded here: [spring-boot-jzos-sample](https://github.com/zowe/spring-boot-jzos-sample). If you have your own example skip the "Get your app running" section we can adapt your script for that. - -## Overview -Apart from accessing your API's centrally through the Gateway, the Gateway provides manifest information about all accessible API's in it's catalog. For our static definition this information is retrieved from api definitions stored in yaml files. Although these files are simple in structure they would add more complexity for your customers when it comes to installing your product. Therefore we have developed a script that you can include with your product to simplify the process. - -### The Api definition file - -Key to registering your product to the gateway is the following file structure which is installed in the API mediation layer. It's not critical to understand everything here but provided for anyone who wishes to grasp every detail. - -```yaml -services: - - serviceId: jzos # internal id for the service - title: IBM z/OS jzos # Title as used in the Catalog information tiles - description: IBM z/OS jzos REST API service # Title as used in the Catalog information tiles - catalogUiTileId: jzos # internal id Catalog information tiles - instanceBaseUrls: - - https://host.my.com:2956/ # location of service - homePageRelativeUrl: # home page, leave blank if instanceBaseUrls is the same - routedServices: - - gatewayUrl: api/v1 # [api/ui/ws]/v{majorVersion} convention - serviceRelativeUrl: jzos # added to location - apiInfo: - - apiId: com.ibm.jzos # internal id - gatewayUrl: api/v1 # main reference - version: 1.0.0 # version of API on Gateway - documentationUrl: https://host.my.com:2956/swagger-ui.html # Applies if no swagger ui - swaggerUrl: https://host.my.com:2956/v2/api-docs # provides a link and generates swagger info - -catalogUiTiles: - jzos: # as per serviceId - internal id for the service - title: z/OS jzos services # tile label - description: IBM z/OS jzos REST services # tile description -``` - -This information together creates the catalog tile information -![](../../images/extender/tile.png) - - -By clicking on the tile the following information is presented. Note the swagger is generated from the swaggerUrl link which needs to be v2 swagger -![](../../images/extender/service.png) - -Although the most critical information, the redirection of the urls is under routed services along with the service id. -``` -routedServices.gatewayUrl+serviceId will point at instanceBaseUrls+serviceRelativeUrl -/jzos/api/v1 ==> https://host.my.com:2956/jzos -``` -## Getting the sample app running - -If you are using the sample follow the instructions in the readme to get it up and running on your z/OS machine. If using your own go to section 2. The sample generates swagger 2 documentation. - -## Modifying the Gateway script - -As described earlier we are registering our application with the API Catalog by way of a file that is read by the Gateway when it's started. We think of this as a static definition as the details of the service won't change whilst the gateway is running. To achieve a more dynamic relationship between the application and registry, one that can respond to changes in one or the other e.g. for load balancing purposes we need to construct the product differently. See [Onboarding from scratch](./existingApp). - -The information contained in the yaml definitions file abover requires input from both the onboarding organization (you) and the end user. Therefore the intent is to provide as much of the onboarder information into the script template so the end user has fewer choices to make. Therefore the script should be updated. - -[Onboard-to-gateway](https://github.com/zowe/Onboarding-scripts) - -The following fields need to be set - -````properties -################################################################################ -# The following fields to be filled in by implementing extenders team -################################################################################ -defaultServiceId="xtdrsvcid" # lowercase only -defaultTitle="Product name" -defaultDescription="Product description" -defaultCatalogUiTileId="xtdrCatalogUiTileId" -defaultHomePageRelativeUrl="" # Usually home page is the same as the base URL - -defaultGatewayUrl1="api/v1" -defaultServiceUrl1="api/v1/xtdrServiceId" -defaultGatewayUrl2="ui/v1" -defaultServiceUrl2="ui/v1/xtdrServiceId" -# Additional gateway and services will require further changes to script later - -defaultApiId="no.id.ea" -defaultGatewayUrl=$defaultGatewayUrl1 -defaultApiVersion="1.0.0" - -defaultCatalogTileTitle="My Product in catalog" -defaultCatalogTileDescription="My Product description in catalog" -```` - -##### defaultServiceId -This field is an internal identifier that needs to be unique across product instances. Therefore if you install multiple instances of your product this will also need to be incremented. Note it must be lowercase and is also used as part of the gateway uri -##### defaultTitle - -##### defaultDescription - -##### defaultCatalogUiTileId -This is the name that appears on the tab of the opened service - -##### defaultHomePageRelativeUrl -If the home page is not same as the base url add it in here - -##### defaultGatewayUrl(n) -This is the the gateway url that you want your redirect to work from. -You can create several defaultGatewayUrl/defaultServiceUrl pairings. Normally this would cater for api, web socket (ws) and ui. - -##### defaultServiceUrl(n) -The target url of the service - -##### defaultApiId -An internally used id. Suggest using com.co.yourprod etc. - -##### defaultGatewayUrl -Main url redirection for documentation - -##### defaultApiVersion -Version number of API if you wish to use it - -##### defaultCatalogTileTitle -The title that is displayed in the catalog pages - -##### defaultCatalogTileDescription -The description that is displayed in the catalog pages - -## How the Script works -Your updated shell script can now be run. This is how the process will appear to the end user. - - diff --git a/docs/extend/extend-api/existingApp.md b/docs/extend/extend-api/existingApp.md deleted file mode 100644 index 986062f158..0000000000 --- a/docs/extend/extend-api/existingApp.md +++ /dev/null @@ -1,7 +0,0 @@ -# Onboarding from scratch - -In this tutorial we consider how an organization with a product existing or under development with no pre-existing Rest API can be Onboarded to Zowe™. This would then allow the product to be available from a central location and benefit from other Zowe API Mediation layer functionality. - -At this stage of your development you have more options and can design with Zowe in mind. - -As the example product we are using a simple Spring Boot sample app that can be downloaded here: [spring-boot-jzos-sample](https://github.com/zowe/spring-boot-jzos-sample) \ No newline at end of file diff --git a/docs/extend/extend-api/liberty-api-sample.md b/docs/extend/extend-api/liberty-api-sample.md deleted file mode 100644 index 72c6fc520a..0000000000 --- a/docs/extend/extend-api/liberty-api-sample.md +++ /dev/null @@ -1,44 +0,0 @@ -# Provide Liberty API Sample - -:::tip Github Sample Repo: -[rest-api-jzos sample](https://github.com/zowe/spring-boot-jzos-sample) -::: - -This sample is a boilerplate for creating Rest API's using a liberty. For more information, visit [Creating a RestAPI with Swagger documentation using Liberty](./libertyAPI). - -## To Install - -After creating or obtaining the REST API war file: - -1. Stop the Zowe server. - - - Navigate to `/scripts/` - - Run `./zowe-stop.sh` - -2. Push the war file up to the dropins folder using SCP, SFTP, or on Windows with Putty SCP (PSCP). - - _EX_: - `scp /path/to/warfile @:/explorer-server/wlp/usr/servers/Atlas/dropins/` - -:::tip -Use the USS, IDZ, or IBM Explorer for z/OS to confirm that your files have transferred. -::: - -3. Restart the Zowe server. - - - Navigate to `/scripts/` - - Run `./zowe-start.sh` - -## Verify Install - -1. Check the Browser to see if the REST APIs have been added. - - _EX_: `:/ibm/api/explorer/#/` - -view - -:::tip -Make sure to set file transfer mode to binary before the transfer. -After transferring the WAR file, check the permission on the file by running -ls -la -If the read permission is not set, turn on the read permission by running, -chmod +r javazos-sample.war -::: diff --git a/docs/extend/extend-api/libertyAPI.md b/docs/extend/extend-api/libertyAPI.md deleted file mode 100644 index 0837ca9525..0000000000 --- a/docs/extend/extend-api/libertyAPI.md +++ /dev/null @@ -1,127 +0,0 @@ -# Creating a RestAPI with Swagger documentation using Liberty - -This tutorial will show you how to develop your own Zowe API's with Swagger notation. Although the resulting War file is "dropped into" a Liberty server, the same principles can be applied for other JEE servers. - -The source repo for the project can be found at the [rest-api-jzos sample](https://github.com/zowe/spring-boot-jzos-sample). -This document describes how we can add new function and UI's to run alongside Zowe. - -So for example, as a team with an established z/OS application we may want to provide wider access to that functionality so that it can be exploited by different applications and organizations. This can include making functionality available to company DevOps processes or for inclusion in UI's. - -## Prerequisite skills - -Developers should be familiar with the following technologies: - -- Java -- Git and GitHub -- Maven - -Knowledge of the following development technologies is beneficial: - -- J2E -- Liberty or WebSphere Application Server -- Eclipse/z/OS Explorer -- RestAPI's -- zSystems development - -## Zowe API Architecture Overview - -Much of the Zowe infrastructure builds upon functionality provided by different applications and systems in z/OS some of which are microservices deployed on a Liberty server running on the Z system. As an example Zowe can access z/OSMF services that are aggregated with other functionality that provides new or more comprehensive functionality that allows new services to be created that also benefit from single-sign using **Lightweight Third Party** Authentication (LTPA) keys and centralized logging functions. - -The API for Zowe is written in Java utilizing JAX-RS: Java API for RESTful Web Services (JAX-RS). JAX-RS uses Java annotations to simplify the development and deployment of web service clients and endpoints and ultimately become rendered into swagger interfaces. - -## Building your own Microservice - -There are many publications and blogs regarding Microservice design -available and it's beyond our scope to attempt to cover here. Fundamentally, however you have most likely already performed an analysis of your product and have identified several notional business -areas or components that you are most interested in. One of the recommendations in developing Microservices is not to have one massive service but several services that represent component areas. One reason -would be Microservices that are not used or function is considered restricted can be excluded without affecting other function. - -Once you have identified areas of the functionality Microservices for the API's can be designed. Once again there are an -enormous amount of guidelines, Best practices, strict rules and design guides out there and I won't be prescriptive how you do this except to -say that you will spend a lot of time teasing out your API object names and considering how the REST functions (GET, PUT, POST and DELETE) apply -to these objects. Once ready or as long as we have the most basic Get Object API defined we can make a start at coding. - -An example below is intended to show how we apply the definitions of -the Rest API as Java Annotations around a Java method. - -```java - @PUT - @Path(value = "{attribute}") - @Produces(MediaType.APPLICATION_JSON) - @ApiOperation(value = "Updates the value of an existing environment variable", - notes = "This API uses JZOS to perform the process.") - @ApiResponses({ - @ApiResponse(code = 200, message = "Updated the environment variable")}) - public Response update( - @ApiParam(value = "Environment variable name", required = true) @PathParam("attribute") String attribute, - @ApiParam(value = "Value of an environmental variable") ValueParameter parameter) - { - jzosService.updateProperty(attribute, parameter) ; - return Response.status(Status.OK).build(); - } -``` - -Within the Liberty server we have configured a function "APIDiscovery" which at run time converts this into swagger format. - -![](../../images/guides/libertyAPI/swag.png) - -## Anatomy of a project - -Using [rest-api-jzos sample](https://github.com/zowe/spring-boot-jzos-sample) as a guide. Create a Dynamic web project (don't specify it as part of an EAR if using the wizard), or if using a -Maven archetype choose one containing a simplified sample J2EE application. - -_Alternatively, use the project as a template. Download the code, rename it and use as the basis of your new project._ - -The image below indicates the type of structure you should be seeing although this contains more files and folders than you will have -initially it should give you the general idea. Don't worry about git or target at this stage they will appear later as you develop your project. - -![](../../images/guides/libertyAPI/struct1.png) - -Your project should be developed as a standalone war file and deployed either to a local server if you have no z dependencies (Hint: good to -start with). If using Eclipse and not yet using z/OS specific functionality consider setting up a test server within Eclipse and -automatically deploying your war to it. Fantastic for debugging. - -The alternative is to drop the war into the Dropins folder of an existing Zowe installation. - -It is possible to debug remotely using Eclipse but personally I have found this can lead to issues such as corrupt process locks in z/OS -requiring SysProg intervention. If you have quick access to SysProg rights you may be comfortable with this but often good old sysout is the -best debug support - -The example project uses Maven for its build process which will run locally or as part of a Jenkins build process. - -Further examples of implementations can be found looking at the code for the Zowe microservice. - -### Eclipse hint.. - -Using Maven to build in an Eclipse environment can leave your files full of red x's. Generally this is caused because the Eclipse compiler -mechanism has no visibility of dependencies described in the pom.xml file. There is a magic function to help with this. Right click on your -project and select the Maven Update option. This will allow the Eclipse project to be updated and get rid of many of the x's. - -![](../../images/guides/libertyAPI/menu1.png) - -### Generic jar files - -It is likely that the Zowe team will provide utility jar files that will either be present on the server or require specific inclusion as -described in 'Additional Jars'. Currently generic jar files such as Zowe utilities should be included in your war file. This may be revised -later based upon future requirements. - -## Unit Testing - -Aim for 100% coverage. In many cases it may be impossible or impractical to achieve either because code is auto-generated or covered in other -tests. Use Jacoco to highlight where there are gaps. - -Note the references to Jacoco in the atlas-jzos-sample pom.xml file. Remember it operates in two phases, initializing before the unit tests -are run and reporting afterwards. - -Examples of unit testing, the use of Mockito and PowerMock are in the src/test/java folder for the jzos sample. - -### FV testing - -For the purpose of testing applications in a live fully configured environment scenario it is necessary to create another testing specific -project. You will notice that only the src/main/tests folder is populated. When running a Maven build the tests contained here are -exercised. - -- Using the maven-archetype-quickstart as your Maven template or by creating a new Java project and adding the pom.xml file in Eclipse, - create a project to contain FV and/or Integration tests. - -- Alternatively, you can always download the code, rename it and use as the basis of your new project. diff --git a/docs/extend/extend-apiml/api-mediation-components-of-URL.md b/docs/extend/extend-apiml/api-mediation-components-of-URL.md deleted file mode 100644 index e4f3d9c7d1..0000000000 --- a/docs/extend/extend-apiml/api-mediation-components-of-URL.md +++ /dev/null @@ -1,100 +0,0 @@ -# Components of a URL - -This page provides definitions and a diagram to make sure everyone is using the same terms. To maintain consistency of the structure of URLs, Zowe seeks to establish standards around URLs and the elements that make up a URL. This article presents the standard terminology used in Swagger documentation. - -## Definitions - -REST APIs have a _baseUrl_ to which the endpoint paths are appended. The base URL is defined by _scheme_, _host_, _port_ and _basePath_ - -where: - -- **`baseUrl`** -Specifies an absolute URL prefix that is different for each instance of the service, or when the service is accessed via the API Gateway. - -The endpoint paths are relative paths that follow the documentation of the REST API. - -- **`scheme`** -Specifies the transfer protocols used by the API. API ML supports the `http`, `https`, and WebSocket schemes - `ws` and `wss`. - -- **`host`** -Specifies the domain name or IP address (IPv4) of the host that serves the API. It may include the port number if it is different from the scheme's default port (80 for HTTP and 443 for HTTPS). Note that this must be the host only, without a scheme or sub-paths. - -- **`basePath`** -Specifies the URL prefix for all API paths, relative to the host root. It must start with a leading slash `/`. If basePath is not specified then all endpoint paths start at the host root. - -When a service is accessed without the API Gateway then the format the `basePath` depends on the service. It can be empty or have several parts (e.g. `/fileMasterPlus/api/v1`). - -When a service is accessed via the API Gateway, the format of the URL is standardized in one of the following formats: - -- Using `serviceId`, service type (`t`) and major version (`v`) -- Using `serviceId` and service type (`t`) - -where: - -- **`serviceId`** -Specifies a unique name of the service that is set during the installation of the service. - -- **`t`** -Specifies the type of the service. It can be `api`, `ui`, or `ws` - -- **`v`** -Specifies the major version the REST API. - - **Example:** `v1`, `v2`. It is optional since some existing services can have versioning in the endpoint path. - -The fundamental principle is that by changing the base URL you can access different services with the same API because the structure after the base URL is the same. - -The base URL is the parameter the can be set in Zowe CLI in order to access the service. The endpoint path is prepared by the Zowe CLI plug-in but the base URL needs to be provided by the user based on installation of the REST API service. - -## Examples - -### URL to a service endpoint without API gateway - -```markup -http://ca11.ca.com:19876/fileMasterPlus/api/v1/mvs/dataSets/test/ping -\_____/\_______________/\____________________/\_____________________/ -scheme host basePath endpointPath -\____________________________________________/ - baseUrl -``` - -### URL with empty basePath - -```markup -https://ca32.ca.com:1443/zosmf/info -\_____/\_______________/\_________/ -scheme host endpointPath -\______________________/ - baseUrl -``` - -### URL to a service endpoint via API gateway - -```markup -https://ca3x.ca.com:10310/cafilemasterplus/api/v1/mvs/dataSets/test/ping -\______/\_______________/\______________________/\_____________________/ -scheme host basePath endpointPath - \______________/\__/\/ - serviceId t v - -\_______________________________________________/ - baseUrl - -``` - -### URL to a service endpoint via API gateway without version - -```markup -https://ca3x.ca.com:10310/zosmfca32/api/zosmf/info -\_____/\________________/\____________/\_________/ -scheme host basePath endpointPath - \________/\_/ - serviceId t - -\______________________/ - baseUrl -``` - -### Resources - -- For more information, see the documentation for [swagger specifications](https://swagger.io/docs/specification/2-0/api-host-and-base-path/) in the Swagger product documentation. diff --git a/docs/extend/extend-apiml/api-mediation-layer-development-setup.md b/docs/extend/extend-apiml/api-mediation-layer-development-setup.md index d20657e13f..7080cd3472 100644 --- a/docs/extend/extend-apiml/api-mediation-layer-development-setup.md +++ b/docs/extend/extend-apiml/api-mediation-layer-development-setup.md @@ -10,5 +10,5 @@ The `Dummy Authentication Provider` implements simple authentication for develop Use the following property of the API Gateway to enable the `Dummy Authentication Provider`: ``` -components.gateway.security.auth.provider: dummy +components.gateway.apiml.security.auth.provider: dummy ``` diff --git a/docs/extend/extend-apiml/api-mediation-vsam.md b/docs/extend/extend-apiml/api-mediation-vsam.md index 837de1e7ab..04646ee257 100644 --- a/docs/extend/extend-apiml/api-mediation-vsam.md +++ b/docs/extend/extend-apiml/api-mediation-vsam.md @@ -1,4 +1,6 @@ -# Using VSAM as a storage solution through the Caching service +# Using VSAM as a storage solution through the Caching service **Deprecated** + +The VSAM as a storage solution is deprecated in V3, please use [Infinispan](./api-mediation-infinispan), which is packaged as part of the Caching Service. As an API developer, you can configure VSAM as a storage solution through the Caching service. The procedure in this article describes how to configure your storage solution for VSAM. Configuring VSAM ensures that you do not lose data if you need to restart. Configuring VSAM also makes it possible to leverage multiple caching services concurrently, whereby clients can retreive data through VSAM. diff --git a/docs/extend/extend-apiml/onboard-direct-eureka-call.md b/docs/extend/extend-apiml/onboard-direct-eureka-call.md deleted file mode 100644 index 89183d49de..0000000000 --- a/docs/extend/extend-apiml/onboard-direct-eureka-call.md +++ /dev/null @@ -1,371 +0,0 @@ -# Onboarding a service with the Zowe API Mediation Layer without an onboarding enabler - -This article is part of a series of guides to onboard a REST service with the Zowe API Mediation Layer (API ML). Onboarding with API ML makes services accessible through the API Gateway and visible in the API Catalog. Once a service is successfully onboarded, users can see if the service is currently available and accepting requests. - -This guide describes how a REST service can be onboarded with the Zowe API ML independent of the language used to write the service. As such, this guide does not describe how to onboard a service with a specific enabler. Similarly, various Eureka client implementations are not used in this onboarding method. - -**Tip:** If possible, we recommend that you onboard your service using the API ML enabler libraries. The approach described in this article should only be used if other methods to onboard your service are not suitable. - -For more information about how to onboard a REST service, see the following links: - -- [API ML onboarding overview](onboard-overview.md) -- [python-eureka-client](https://pypi.org/project/py-eureka-client/) -- [eureka-js-client](https://www.npmjs.com/package/eureka-js-client) -- [Rest API developed based on Java](onboard-overview.md#sample-rest-api-service) - -This article outlines a process to make an API service available in the API Mediation Layer by making a direct call to the Eureka Discovery Service. - -* [Introduction](#introduction) -* [Registering with the Discovery Service](#registering-with-the-discovery-service) - * [API Mediation Layer Service onboarding metadata](#api-mediation-layer-service-onboarding-metadata) - * [Catalog parameters](#catalog-parameters) - * [Service parameters](#service-parameters) - * [Routing parameters](#routing-parameters) - * [API Info Parameters](#api-info-parameters) -* [Sending a heartbeat to API Mediation Layer Discovery Service](#sending-a-heartbeat-to-api-mediation-layer-discovery-service) -* [Validating successful onboarding with the API Mediation Layer](#validating-successful-onboarding-with-the-api-mediation-layer) -* [External Resources](#external-resources) - -## Introduction - -The API ML Discovery Service uses [Netflix/Eureka](https://github.com/Netflix/eureka) as a REST services registry. Eureka is a REST-based service that is primarily used to locate services. - -Eureka [endpoints](https://github.com/Netflix/eureka/wiki/Eureka-REST-operations) are used to register a service with the API ML Discovery Service. Endpoints are also used to send a periodic heartbeat to the Discovery Service to indicate that the onboarded service is available. - -**Note:** Required parameters should be defined and sent at registration time. - -## Registering with the Discovery Service - -Begin the onboarding process by registering your service with the API ML Discovery Service. - -Use the `POST` Http call to the Eureka server together with the registration configuration in the following format: - -``` -https://{eureka_hostname}:{eureka_port}/eureka/apps/{serviceId} -``` - -The following code block shows the format of the parameters in your `POST` call, which are sent to the Eureka registry at the time of registration. - -```xml - - - {serviceId} - {ipAddress} - {port} - {port} - {hostname} - {serviceId} - {serviceId} - {instanceId} - - MyOwn - - - ... - - -``` - -where: - - * **app** - uniquely identifies one or more instances of a microservice in the API ML. - - The API ML Gateway uses the `serviceId` for routing to the API service instances. - As such, the `serviceId` is part of the service URL path in the API ML Gateway address space. - - **Important!** Ensure that the service ID is set properly with the following considerations: - - * The service ID value contains only lowercase alphanumeric characters. - * The service ID does not contain more than 40 characters. - * The same service ID is only set for multiple API service instances to support API scalability. When two API services use the same service ID, the API Gateway considers the services as clones of each other. An incoming API request can be routed to either instance through load balancing. - - **Example:** - * If the `serviceId` is `sampleservice`, the service URL in the API ML Gateway address space appears as: - - ``` - https://gateway-host:gateway-port/sampleservice/api/v1/... - ``` - - * **ipAddr** - specifies the IP address of this specific service instance. - - * **port** - specifies the port of the instance when you use Http. For Http, set `enabled` to `true`. - -* **securePort** -specifies the port of the instance for when you use Https. For Https, set `enabled` to `true`. - - * **hostname** - specifies the hostname of the instance. - - * **vipAddress** - specifies the `serviceId` when you use Http. -**Important!** Ensure that the value of `vipAddress` is the same as the value of `app`. In addition, be sure not to omit `vipAddress`, even if you provided `secureVipAddress`. Due to -a current limitation in Spring Cloud Netflix, routes are created only for instances in which `vipAddress` is defined. - - * **secureVipAddress** - specifies the `serviceId` when you use Https. - **Important!** Ensure that the value of `secureVipAddress` is the same as the value of `app`. - - * **instanceId** - specifies a unique id for the instance. Define a unique value for the `instanceId` in the following format: - - ```{hostname}:{serviceId}:{port}``` - * **metadata** - specifies the set of parameters described in the following section addressing API ML service metadata. - -### API Mediation Layer Service onboarding metadata - -At registration time, provide metadata in the following format. Metadata parameters contained in this code block are described in the following section. - -```xml - - - samples - Sample API Mediation Layer Applications - Applications which demonstrate how to make a service integrated to the API Mediation Layer ecosystem - 1.0.1 - Sample Service - Sample API service showing how to onboard the service - false - api/v1 - /sampleclient/api/v1 - /sampleclient - ui/v1 - ws/v1 - /sampleclient/ws - httpBasicPassTicket - ZOWEAPPL - zowe.apiml.sampleclient - https://hostname/sampleclient/api-doc - api/v1 - https://www.zowe.org - - -``` - -Metadata parameters are broken down into the following categories: - -* [Catalog parameters](#catalog-parameters) -* [Service parameters](#service-parameters) -* [Routing parameters](#routing-parameters) -* [Authentication parameters](#authentication-parameters) -* [API Info parameters](#api-info-parameters) - -#### Catalog parameters -Catalog parameters are grouped under the prefix: `apiml.catalog.tile`. - -The API ML Catalog displays information about services registered with the API ML Discovery Service. -Information displayed in the Catalog is defined in the metadata provided by your service during registration. -The Catalog groups correlated services in the same tile when these services are configured with the same `catalog.tile.id` metadata parameter. - -The following parameters are used to populate the API Catalog: - -* **apiml.catalog.tile.id** -This parameter specifies the specific identifier for the product family of API services. This is a value used by the API ML to group multiple API services into a single tile.Each identifier represents a single API dashboard tile in the Catalog. -**Important!** Specify a value that does not interfere with API services from other products. We recommend that you use your company and product name as part of the ID. - -* **apiml.catalog.tile.title** -This parameter specifies the title of the API services product family. This value is displayed in the API Catalog dashboard as the tile title. - -* **apiml.catalog.tile.description** -This parameter is the detailed description of the API services product family. This value is displayed in the API Catalog UI dashboard as the tile description. - -* **apiml.catalog.tile.version** -This parameter specifies the semantic version of this API Catalog tile. -**Note:** Ensure that you increase the version number when you introduce changes to the API service product family details. - -#### Service parameters -Service parameters are grouped under the prefix: `apiml.service` - -The following parameters define service information for the API Catalog: - -* **apiml.service.title** -This parameter specifies the human-readable name of the API service instance. This value is displayed in the API Catalog when a specific API service instance is selected. - -* **apiml.service.description** -This parameter specifies a short description of the API service. -This value is displayed in the API Catalog when a specific API service instance is selected. - -* **apiml.enableUrlEncodedCharacters** -When this parameter is set to `true`, the Gateway allows encoded characters to be part of URL requests redirected through the Gateway. The default setting of `false` is the recommended setting. Change this setting to `true` only if you expect certain encoded characters in your application's requests. -**Important!** When the expected encoded character is an encoded slash or backslash (`%2F`, `%5C`), make sure the Gateway is also configured to allow encoded slashes. For more info see [Installing the Zowe runtime on z/OS](../../user-guide/install-zos.md). - -* **apiml.connectTimeout** -The value in milliseconds that specifies a period in which API ML should establish a single, non-managed connection with this service. If omitted, the default value specified in the API ML Gateway service configuration is used. - -* **apiml.readTimeout** -The value in milliseconds that specifies maximum time 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. - -* **apiml.connectionManagerTimeout** -HttpClient employs a special entity to manage access to HTTP connections called by 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, an HTTP connection manager works with managed connections, which serve as proxies for real connections. `ConnectionManagerTimeout` specifies a period in 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. - -* **apiml.okToRetryOnAllOperations** -Specifies whether all operations can be retried for this service. The default value is `false`. The `false` value allows retries for only GET requests if a response code of `503` is returned. Setting this value to `true` enables retry requests for all methods, which return a `503` response code. Enabling retry can impact server resources resulting from buffering of the request body. - -* **apiml.service.corsEnabled** -When this parameter is set to `true`, CORS is enabled on the service level for all service routes. The same parameter can also be set on the service level, by providing the parameter as `customMetadata` as shown in the [Custom Metadata](./custom-metadata.md). - -* **apiml.response.compress** -When this parameter is set to `true`, API ML compresses content for all responses from these services using GZIP. API ML also adds the `Content-Encoding` header with the value `gzip` to responses. - -* **customMetadata.apiml.response.compressRoutes** -When the `customMetadata.apiml.response.compress` parameter is set to `true`, this parameter allows the services to further limit the compressed routes. The parameter accepts [ant style](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/util/AntPathMatcher.html) routes deliminated by `,` . The expectation is to provide the absolute paths. If relative paths are provided, the starting `/` is added. If the beginning of the pattern does not require specification, use `**/{pathYouAreInterestedIn}` - - **Examples:** - - * `/service/**` - Compresses all paths starting with `/service/` - - * `/service/api/v1/compress,/service/api/v1/custom-compress` - Compresses the specific two routes - - * `/\*\*/compress/\*\*` - Compresses all paths that contain `compress` as a specific path - - -#### Routing parameters -Routing parameters are grouped under the prefix: `apiml.routes` - -The API routing group provides necessary routing information used by the API ML Gateway when routing incoming requests to the corresponding service. -A single route can be used to make direct REST calls to multiple resources or API endpoints. The route definition provides rules used by the API ML Gateway to rewrite the URL -in the Gateway address space. - -Routing information consists of two parameters per route: - - * `gatewayUrl` - * `serviceUrl` - -These two parameters together specify a rule of how the API service endpoints are mapped to the API Gateway endpoints. - -The following snippet is an example of the API routing information properties. - -**Example:** - -``` -api/v1 -/sampleclient/api/v1 -``` -where: - -* **apiml.routes.\{route-prefix\}.gatewayUrl** -The `gatewayUrl` parameter specifies the portion of the gateway URL which is replaced by the `serviceUrl` path. - -* **apiml.routes.\{route-prefix\}.serviceUrl** -The `serviceUrl` parameter provides a portion of the service instance URL path which replaces the `gatewayUrl` part. -**Note:** The routes configuration used for a direct REST call to register a service must also contain a prefix before the `gatewayUrl` and `serviceUrl`. -This prefix is used to differentiate the routes. This prefix must be provided manually when _XML_ configuration is used. - -#### Authentication parameters -Authentication parameters are grouped under the prefix: `apiml.authentication`. When unspecified, the default values are used. - -This parameter enables a service to accept the Zowe JWT token. The API Gateway translates the token to an authentication method supported by a service. - -The following parameters define the service authentication method: - -* **apiml.authentication.scheme** -This parameter specifies a service authentication scheme. The following schemes are supported by the API Gateway: - - * **bypass** - This value specifies that the token is passed unchanged to the service. - **Note:** This is the default scheme when no authentication parameters are specified. - - * **zoweJwt** - This value specifies that a service accepts the Zowe JWT token. No additional processing is done by the API Gateway. - - * **httpBasicPassTicket** - This value specifies that a service accepts PassTickets in the Authorization header of the HTTP requests using the basic authentication scheme. It is necessary to provide a service APPLID in the `apiml.authentication.applid` parameter. - **Tip:** For more information, see [Enabling PassTicket creation for API Services that Accept PassTickets](authentication-for-apiml-services.md#authentication-with-passtickets). - - * **zosmf** - This value specifies that a service accepts z/OSMF LTPA (Lightweight Third-Party Authentication). This scheme should only be used for a z/OSMF service used by the API Gateway Authentication Service, and other z/OSMF services that are using the same LTPA key. - **Tip:** For more information about z/OSMF Single Sign-on, see [Establishing a single sign-on environment](https://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zosmfcore.multisysplex.help.doc/izuG00hpManageSecurityCredentials.html). - - * **safIdt** - This value specifies that the application recognizes the SAF IDT scheme and fills the `X-SAF-Token` header with the token produced by the Saf IDT provider implementation. For more information, see [Implement a New SAF IDT provider](./implement-new-saf-provider.md) - - * **x509** - This value specifies that a service accepts client certificates forwarded in the HTTP header only. The Gateway service extracts information from a valid client certificate. For validation, the certificate needs to be trusted by API Mediation Layer. Extended Key Usage must either be empty or needs to contain a Client Authentication (1.3.6.1.5.5.7.3.2) entry. To use this scheme, it is also necessary to specify which headers to include. Specify these parameters in `headers`. This scheme does not relate to the certificate used in the TLS handshake between API ML and the southbound service, but rather the certificate that is forwarded in the header that authenticates the user. - - -* **authentication.headers** - - When the `x509` scheme is specified, use the `headers` parameter to select which values to send to a service. Use one of the following values: - - * `X-Certificate-Public` - The public part of the client certificate base64 encoded - - * `X-Certificate-DistinguishedName` - The distinguished name the from client certificate - - * `X-Certificate-CommonName` - The common name from the client certificate - -* **apiml.authentication.applid** -This parameter specifies a service APPLID. This parameter is valid only for the `httpBasicPassTicket` authentication scheme. - -#### API Info parameters -API Info parameters are grouped under the prefix: `apiml.apiInfo`. - -REST services can provide multiple APIs. Add API info parameters for each API that your service wants to expose on the API ML. These parameters provide information for API (Swagger) documentation that is displayed in the API Catalog. - -The following parameters provide the information properties of a single API: - -* **apiml.apiInfo.\{api-index\}.apiId** -The API ID uniquely identifies the API in the API ML. -Multiple services can provide the same API. The API ID can be used -to locate the same APIs that are provided by different services. -The creator of the API defines this ID. -The API ID needs to be a string of up to 64 characters -that uses lowercase alphanumeric characters and a dot: `.`. -**Tip:** We recommend that you use your organization as the prefix. - -* **apiml.apiInfo.\{api-index\}.version** -This parameter specifies the API version. This parameter is used to correctly retrieve the API documentation according to the requested version of the API. - -* **apiml.apiInfo.\{api-index\}.gatewayUrl** -This parameter specifies the base path at the API Gateway where the API is available. Ensure that this value is the same path as the `gatewayUrl` value in the `routes` sections for the routes, which belong to this API. - -* **apiml.apiInfo.\{api-index\}.swaggerUrl** -(Optional) This parameter specifies the Http or Https address where the Swagger JSON document is available. - -* **apiml.apiInfo.\{api-index\}.documentationUrl** -(Optional) This parameter specifies the link to the external documentation. A link to the external documentation can be included along with the Swagger documentation. - -* **apiml.apiInfo.\{api-index\}.defaultApi** -(Optional) This parameter specifies if the API is the default one shown in the API Catalog. If no API has this parameter set to `true`, or multiple APIs have it set to `true`, then the default API becomes the API with the highest major version seen in `apiml.apiInfo.{api-index}.version`. -**Note:** The `{api-index}` is used to differentiate the service APIs. This index must be provided manually when _XML_ configuration is used. In the following example, `0` represents the `api-index`. - -``` -zowe.apiml.sampleclient -https://hostname/sampleclient/api-doc -api/v1 -https://www.zowe.org -``` - -## Sending a heartbeat to API Mediation Layer Discovery Service - -After registration, a service must send a heartbeat periodically to the Discovery Service to indicate that the service is available. When the Discovery Service does not receive a heartbeat, the service instance is deleted from the Discovery Service. - -If the server does not receive a renewal in 90 seconds, it removes the instance from its registry. - -**Note:** We recommend that the interval for the heartbeat is no more than 30 seconds. - - Use the Http `PUT` method in the following format to tell the Discovery Service that your service is available: - -```https://{eureka_hostname}:{eureka_port}/eureka/apps/{serviceId}/{instanceId}``` - -## Validating successful onboarding with the API Mediation Layer -Ensure that you successfully onboarded a service with the API Mediation Layer. - -**Follow these steps:** - 1. [Validate successful onboarding](./onboard-overview.md#verify-successful-onboarding-to-the-api-ml) - - 2. Check that you can access your API service endpoints through the Gateway. - - 3. (Optional) Check that you can access your API service endpoints directly outside of the Gateway. - -## External Resources - - - https://github.com/Netflix/eureka/wiki/Eureka-REST-operations diff --git a/docs/extend/extend-apiml/websocket.md b/docs/extend/extend-apiml/websocket.md deleted file mode 100644 index 7139fcd47b..0000000000 --- a/docs/extend/extend-apiml/websocket.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Using WebSocket support in API Gateway - -The API Gateway includes a basic WebSocket proxy which enables the Gateway to access applications that use the WebSocket protocol together with a web UI and a REST API. - -The service defines which WebSocket endpoints are exposed by using Eureka metadata. - -**Example:** -``` -eureka: - instance: - metadata-map: - apiml: - routes: - ws_v1: - gatewayUrl: "ws/v1" - serviceUrl: /${serviceId}/ws -``` - -These metadata make it possible for requests from `wss://gatewayHost:gatewayPort/${serviceId}/ws/v1/path` to map to `wss://serviceHost:servicePort/${serviceId}/ws/v1/path`. - -* **`serviceId`** - Specifies the service ID of the service. - -* **`path`** - Specifies the remaining path segment in the URL. - diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md index c31ed8c86e..f90cbfc802 100644 --- a/docs/getting-started/overview.md +++ b/docs/getting-started/overview.md @@ -51,11 +51,7 @@ API ML consists of these core components: the API Gateway, the Discovery Service - The API Gateway provides secure routing of API requests from clients to registered API services. - The Discovery Service allows dynamic registration of microservices and enables their discoverability and status updates. - The API Catalog provides a user-friendly interface to view and try out all registered services, read their associated APIs documentation in OpenAPI/Swagger format. -- The API ML Caching Service allows components to store, search and retrieve their state. The Caching service can be configured to store the cached data in-memory or using Redis, or VSAM storage. - -Core Zowe also provides out of the box services for working with MVS Data Sets, JES, as well as working with z/OSMF REST APIs. - -**Note:** The MVS datasets and JES services are deprecated and will not be available in Zowe V3. +- The API ML Caching Service allows components to store, search and retrieve their state. The Caching service can be configured to store the cached data using various backends. Recommended is usage of Inifinispan packaged with the Caching Service. The API Mediation Layer offers enterprise, cloud-like features such as high-availability, scalability, dynamic API discovery, consistent security, a single sign-on experience, and API documentation. @@ -68,7 +64,7 @@ The API Mediation Layer offers enterprise, cloud-like features such as high-avai * High-Availability: API Mediation Layer is designed with high-availability of services and scalability in mind. * Caching Service: This feature is designed for Zowe components in a high availability configuration, and supports high availability of all components within Zowe. As such, components can remain stateless whereby the state of the component is offloaded to a location accessible by all instances of the service, including those which just started. * Redundancy and Scalability: API service throughput is easily increased by starting multiple API service instances without the need to change configuration. -* Presentation of Services: The API Catalog component provides easy access to discovered API services and their associated documentation in a user-friendly manner. Access to the contents of the API Catalog is controlled through a z/OS security facility. +* Presentation of Services: The API Catalog component provides easy access to discovered API services and their associated documentation in a user-friendly manner. * Encrypted Communication: API ML facilitates secure and trusted communication across both internal components and discovered API services. #### API Mediation Layer structural architecture @@ -79,32 +75,39 @@ The following diagram illustrates the single point of access through the Gateway #### Components The API Layer consists of the following key components: -**API Gateway** +**Gateway Service** -Services that comprise the API ML service ecosystem are located behind a gateway (reverse proxy). All end users and API client applications interact through the Gateway. Each service is assigned a unique service ID that is used in the access URL. Based on the service ID, the Gateway forwards incoming API requests to the appropriate service. Multiple Gateway instances can be started to achieve high-availability. The Gateway access URL remains unchanged. The Gateway is built using Netflix Zuul and Spring Boot technologies. +Services that comprise the API ML service ecosystem are located behind a gateway (reverse proxy). All end users and API +client applications interact through the Gateway. Each service is assigned a unique service ID that is used in the access URL. +Based on the service ID, the Gateway forwards incoming API requests to the appropriate service. Multiple Gateway instances +can be started to achieve high-availability. The Gateway access URL remains unchanged. The Gateway Service is built on Spring +Cloud Gateway and Spring Boot technology. **Discovery Service** -The Discovery Service is the central repository of active services in the API ML ecosystem. The Discovery Service continuously collects and aggregates service information and serves as a repository of active services. When a service is started, it sends its metadata, such as the original URL, assigned serviceId, and status information to the Discovery Service. Back-end microservices register with this service either directly or by using a Eureka client. Multiple enablers are available to help with service on-boarding of various application architectures including plain Java applications and Java applications that use the Spring Boot framework. The Discovery Service is built on Eureka and Spring Boot technology. - -**Discovery Service TLS/SSL** - -HTTPS protocol can be enabled during API ML configuration and is highly recommended. Beyond encrypting communication, the HTTPS configuration for the Discovery Service enables heightened security for service registration. Without HTTPS, services provide a username and password to register in the API ML ecosystem. When using HTTPS, only trusted services that provide HTTPS certificates signed by a trusted certificate authority can be registered. +The Discovery Service is the central repository of active services in the API ML ecosystem. The Discovery Service +continuously collects and aggregates service information and serves as a repository of active services. When a service is +started, it sends its metadata, such as the original URL, assigned serviceId, and status information to the Discovery Service. +Back-end microservices register with this service either directly or by using a Eureka client. Multiple enablers are +available to help with service on-boarding of various application architectures including plain Java applications and +Java applications that use the Spring Boot framework. The Discovery Service is built on Eureka and Spring Boot technology. **API Catalog** -The API Catalog is the catalog of published API services and their associated documentation. The Catalog provides both the REST APIs and a web user interface (UI) to access them. The web UI follows the industry standard Swagger UI component to visualize API documentation in OpenAPI JSON format for each service. A service can be implemented by one or more service instances, which provide exactly the same service for high-availability or scalability. - -**Catalog Security** - -Access to the API Catalog can be protected with an Enterprise z/OS Security Manager such as IBM RACF, ACF2, or Top Secret. Only users who provide proper mainframe credentials can access the Catalog. Client authentication is implemented through the z/OSMF API. +The API Catalog is the catalog of published API services and their associated documentation. The Catalog provides both +the REST APIs and a web user interface (UI) to access them. The web UI follows the industry standard Swagger UI component +to visualize API documentation in OpenAPI JSON format for each service. A service can be implemented by one or more service +instances, which provide exactly the same service for high-availability or scalability. API Catalog requires authentication +from the accessing user. **Caching Service** -An API is provided in high-availability mode which offers the possibility to store, retrieve, and delete data associated with keys. The service can only be used by internal Zowe services and is not exposed to the internet. +An API is provided in high-availability mode which offers the possibility to store, retrieve, and delete data associated +with keys. #### Onboarding APIs -Essential to the API Mediation Layer ecosystem is the API services that expose their useful APIs. Use the following topics to discover more about adding new APIs to the API Mediation Layer and using the API Catalog: +Essential to the API Mediation Layer ecosystem is the API services that expose their useful APIs. Use the following topics +to learn more about adding new APIs to the API Mediation Layer and using the API Catalog: * [Onboarding Overview](../extend/extend-apiml/onboard-overview.md) * [Onboard an existing Spring Boot REST API service using Zowe API Mediation Layer](../extend/extend-apiml/onboard-spring-boot-enabler.md) diff --git a/docs/getting-started/user-roadmap-apiml.md b/docs/getting-started/user-roadmap-apiml.md index fdc841346f..c3630a9cbe 100644 --- a/docs/getting-started/user-roadmap-apiml.md +++ b/docs/getting-started/user-roadmap-apiml.md @@ -28,11 +28,11 @@ The following definition of skill levels about Zowe assist you with gathering th Review this topic to ensure that your system meets the requirements for installing the API Mediation Layer. The API Mediation Layer is one of the server-side components. -- [**Planning**](../user-guide/installandconfig.md#planning-the-installation-of-zowe-server-components) +- [**Planning**](../user-guide/installandconfig.md) This article includes details about planning for installation, the Zowe z/OS launch process, and information about the Zowe runtime directory, instance directory, and keystore directory. -- [**Installing API Mediation Layer**](../user-guide/install-zos.md#z-os-installation-roadmap) +- [**Installing API Mediation Layer**](../user-guide/install-zos.md#end-to-end-installation) This article provides an overview of the essential steps involved in installing the API Mediation Layer. @@ -42,9 +42,9 @@ The following definition of skill levels about Zowe assist you with gathering th - **Configuring API Mediation Layer** - - [Advanced Gateway features configuration](../user-guide/advanced-apiml-configuration.md) + - [Advanced API Mediation Layer features configuration](../user-guide/advanced-apiml-configuration.md) - This article is for system programmers who want to configure advanced Gateway features of the API Mediation Layer, such as the Gateway retry policy, connection limits, Gateway timeouts, and other advanced Gateway features. + This article is for system programmers who want to configure advanced features of the API Mediation Layer, such as the Gateway retry policy, connection limits, Gateway timeouts, and other advanced features. ## Using Zowe API Mediation Layer @@ -98,7 +98,8 @@ The following definition of skill levels about Zowe assist you with gathering th This blog takes a deeper dive into the SSO feature of API ML. -- [**Blog: Zowe client certificate authentication**](https://medium.com/zowe/zowe-client-certificate-authentication-5f1c7d4d579) +- [**Blog: Zowe client certificate authentication**](https://medium.com/zowe/zowe-client-certificate-authentication-5f1c7d4d579) +- [**Blog: CLI and Client Certificates](https://medium.com/zowe/zowe-cli-and-client-certificates-dae341f8f52a) ## Contributing to Zowe API Mediation Layer diff --git a/docs/getting-started/zowe-high-availability.md b/docs/getting-started/zowe-high-availability.md index e90cdaa827..dbc37749d0 100644 --- a/docs/getting-started/zowe-high-availability.md +++ b/docs/getting-started/zowe-high-availability.md @@ -30,7 +30,7 @@ If you are running the Caching Service on z/OS, there are three storage methods - Part of the Caching service - Does not need separate processes - Highly performant -- [VSAM](../user-guide/configure-caching-service-ha.md#vsam) +- [VSAM (*deprecated*)](../user-guide/configure-caching-service-ha.md#vsam) - Familiar to z/OS engineers - Slow - [Redis](../extend/extend-apiml/api-mediation-redis.md#redis-configuration) diff --git a/docs/getting-started/zowe-resources.md b/docs/getting-started/zowe-resources.md index 4e082d85d8..ec07932851 100644 --- a/docs/getting-started/zowe-resources.md +++ b/docs/getting-started/zowe-resources.md @@ -23,6 +23,8 @@ As well as [Zowe videos](https://www.youtube.com/embed?listType=playlist&list=PL Find out what's happening with Zowe in the Zowe Quarterly Update Webinar Series. +- [Zowe Quarterly Update Webinar: May 2024](https://youtu.be/57IKsRfM_F0) +- [Zowe Quarterly Update Webinar: February 2024](https://youtu.be/d9eA9eZRREI) - [Zowe Quarterly Update Webinar: October 2021](https://youtu.be/b0Xo6WIy3vc) - [Zowe Quarterly Update Webinar: July 2021](https://youtu.be/T3Z4hMwElII) - [Zowe Quarterly Update Webinar: April 2021](https://youtu.be/9rQCcZGVDzQ) diff --git a/docs/getting-started/zowe-security-authentication.md b/docs/getting-started/zowe-security-authentication.md index e38b6d6858..3de6fbfbd8 100644 --- a/docs/getting-started/zowe-security-authentication.md +++ b/docs/getting-started/zowe-security-authentication.md @@ -4,7 +4,6 @@ The API Mediation Layer provides multiple methods which clients can use to authe * [Authentication with JSON Web Tokens (JWT)](#authentication-with-json-web-tokensjwt) * [Authentication with client certificates](#authentication-with-client-certificates) * [Authentication with Personal Access Token (PAT)](#authentication-with-personal-access-token-pat) -* [Authentication with SAF Identity Tokens](#authentication-with-saf-identity-tokens) * [Multi-factor authentication (MFA)](#multi-factor-authentication-mfa) * [Certificate Authority Advanced Authentication Mainframe (CA AAM)](#certificate-authority-advanced-authentication-mainframe-ca-aam) @@ -32,11 +31,6 @@ A Personal Access Token (PAT) is a specific scoped JWT with a configurable valid For more information about PAT, see [Authenticating with a Personal Access Token documentation](../user-guide/api-mediation/authenticating-with-personal-access-token.md). -## Authentication with SAF Identity Tokens -The SAF Authentication Provider allows the API Gateway to authenticate the user directly with the z/OS SAF provider that is installed on the system. - -For more information about configuring the token, see [Configure signed SAF Identity tokens (IDT)](../user-guide/configure-zos-system.md#configure-signed-saf-identity-tokens-idt). - ## Multi-factor authentication (MFA) Multi-factor authentication is provided by third-party products which Zowe is compatible with. The following are known to work with Zowe: diff --git a/docs/getting-started/zowe-security-overview.md b/docs/getting-started/zowe-security-overview.md index e0ead2e71c..5adacfcde8 100644 --- a/docs/getting-started/zowe-security-overview.md +++ b/docs/getting-started/zowe-security-overview.md @@ -3,7 +3,7 @@ Zowe implements comprehensive measures to secure mainframe services and data resources in transition and in rest: - Digital certificates are used by Zowe to facilitate secure electronic communication and data exchange between people, systems, and devices online. -- User identity is authenticated through modern authentication methods such as OIDC/Oauth2, Multi-Factor Authentication (MFA), JWT, or Personal Access Token (PAT). +- User identity is authenticated through modern authentication methods such as OIDC/Oauth2, JWT, or Personal Access Token (PAT). Potentially with added Multi-Factor Authentication (MFA). - User access is authorized by System Authorization Facility (SAF) / External Security Manager (ESM). Before installation and use of Zowe server-side components, it is practical to first learn about the core security features built into the Zowe architecture. @@ -28,11 +28,18 @@ A certificate contains an identity (a hostname, or an organization, or an indivi A certificate can be self-signed or issued by a Certificate Authority (CA). A CA is a trusted organization which provides infrastructure for creation, validation and revocation of the certificates according to the contemporary security standards. -**Note:** -For testing purposes of Zowe, it is acceptable to use certificates issued and signed either by the company's local CA, or even self-signed certificates issued by Zowe security tools specific for the target technology platform. -Use of self-signed certificates, however, is not recommended for production environments. +:::note -**Tip:** Review digital certificates terminology in the [Zowe security glossary](../appendix/zowe-security-glossary#certificate-concepts) before getting started with configuring certificates. +For testing purposes of Zowe, it is acceptable to use certificates issued and signed either by the company's local Certificate Authority (CA), or even certificates issued by Zowe security tools and signed by generated CA specific for the target technology platform. +Use of certificates signed by generated CA, however, is not recommended for production environments. + +::: + +:::tip + +Review digital certificates terminology in the [Zowe security glossary](../appendix/zowe-security-glossary#certificate-concepts) before getting started with configuring certificates. + +::: ### Digital certificates usage Zowe uses digital certificates to secure the communication channel between Zowe components as well as between Zowe clients and Zowe services. Digital client certificates can also be used to validate that a client-user (the service user) identity is known to the mainframe security facility. @@ -44,9 +51,9 @@ Zowe uses digital certificates to secure the communication channel between Zowe ## User Authentication Zowe always authenticates the users accessing its interfaces and services. -Zowe API ML implements a Singls-Sign-On feature which allows users to authenticate once, whereby users can access all mainframe resources that they are granted access rights to for the period in which the Zowe credentials remain valid. +Zowe API ML implements a Single-Sign-On feature which allows users to authenticate once, whereby users can access all mainframe resources that they are granted access rights to for the period in which the Zowe credentials remain valid. -API ML uses multiple authentication methods - from Basic Auth (username-password), to external Multi-Factor Authentication providers, and modern authentication protocols, such as OIDC/OAuth2. +API ML uses multiple authentication methods - Basic Auth (username-password), OIDC/OAuth2, Client certificates and Personal Access Tokens with possibility of strengthening of the security by adding external Multi-Factor Authentication provider. **Next steps:** - For more details on the authentication methods used by Zowe, see the dedicated [API ML User Authentication](./zowe-security-authentication) article. @@ -68,7 +75,7 @@ Access to a SAF resource is checked with the installed z/OS External Security Ma For detailed information, see the [SAF resource checking documentation](../user-guide/api-mediation/configuration-saf-resource-checking). ## Additional resources -For more information about getting started with certificates including dertermining your certificate configuration use case, importing certificates, generating certificates and using certificates, see the following resources: +For more information about getting started with certificates including determining your certificate configuration use case, importing certificates, generating certificates and using certificates, see the following resources: - [Use-case based certificates configuration scenarios](../user-guide/certificate-configuration-scenarios.md) - [Generate certificates for Zowe servers](../user-guide/generate-certificates.md) diff --git a/docs/getting-started/zowe_faq.md b/docs/getting-started/zowe_faq.md index 2c33ff02b7..051d3ea1e8 100644 --- a/docs/getting-started/zowe_faq.md +++ b/docs/getting-started/zowe_faq.md @@ -34,7 +34,7 @@ Zowe technology can be used by a variety of mainframe IT and non-IT professional -Zowe consists of several components. The primary languages are Java and JavaScript. Zowe CLI and Desktop are written in TypeScript. ZSS is written in C, while the cross memory server is written in metal C. +Zowe consists of several components. The primary languages for API Mediation Layer are Java and JavaScript. Zowe CLI, Explorer for VSCode and Desktop are written in TypeScript. Explorer for IntelliJ is written in Kotlin, ZSS is written in C, while the cross memory server is written in metal C. diff --git a/docs/images/api-mediation/api-catalog.png b/docs/images/api-mediation/api-catalog.png index 68032a4c36..8a75cb1ba1 100644 Binary files a/docs/images/api-mediation/api-catalog.png and b/docs/images/api-mediation/api-catalog.png differ diff --git a/docs/troubleshoot/troubleshoot-apiml.md b/docs/troubleshoot/troubleshoot-apiml.md index 782aa39bf9..dd6d3f01ed 100644 --- a/docs/troubleshoot/troubleshoot-apiml.md +++ b/docs/troubleshoot/troubleshoot-apiml.md @@ -327,7 +327,7 @@ The API ML services are running but they are in the DOWN state and not working p See the following message for full exceptions. ``` -org.springframework.web.client.ResourceAccessException: I/O error on GET request for "https://USILCA32.lvn.broadcom.net:7553/eureka/apps/apicatalog": USILCA32.lvn.broadcom.net; nested exception is java.net.UnknownHostException: USILCA32.lvn.broadcom.net +org.springframework.web.client.ResourceAccessException: I/O error on GET request for "https://system.lvn.broadcom.net:7553/eureka/apps/apicatalog": system.lvn.broadcom.net; nested exception is java.net.UnknownHostException: USILCA32.lvn.broadcom.net .at org.springframework.web.client.RestTemplate.doExecute(RestTemplate.java:732) ~Ýspring-web-5.0.8.RELEASE.jar!/:5.0.8.RELEASE¨ @@ -352,7 +352,7 @@ main¨ o.a.http.impl.client.DefaultHttpClient : Retrying connect to {s}->https The Zowe started task needs to run under a user with sufficient privileges. As a workaround, you can try to run the started task under the same user ID as z/OSMF (typically IZUSVR). -The hostname that is displayed in the details of the exception is a valid hostname. You can validate that the hostname is valid by using `ping` command on the same mainframe system. For example, `ping USILCA32.lvn.broadcom.net`. If it is valid, then the problem can be caused by insufficient privileges of your started task that is not allowed to do network access. +The hostname that is displayed in the details of the exception is a valid hostname. You can validate that the hostname is valid by using `ping` command on the same mainframe system. For example, `ping system.lvn.broadcom.net`. If it is valid, then the problem can be caused by insufficient privileges of your started task that is not allowed network access. You can fix it by setting up the security environment as described in the [Zowe documentation](../user-guide/configure-zos-system#configure-security-environment-switching). diff --git a/docs/user-guide/api-mediation-change-password-via-catalog.md b/docs/user-guide/api-mediation-change-password-via-catalog.md index c05cf3b24a..1d8ab29056 100644 --- a/docs/user-guide/api-mediation-change-password-via-catalog.md +++ b/docs/user-guide/api-mediation-change-password-via-catalog.md @@ -1,6 +1,6 @@ # Changing an expired password via API Catalog -In case of expiration of a mainframe password, the API Catalog offers the possibility to set a new password. When your password expires, you are prompted with a form and a warning message: +In case of expiration of a mainframe password, the API Catalog, when using SAF as authentication provider offers the possibility to set a new password. When your password expires, you are prompted with a form and a warning message: api refresh error diff --git a/docs/user-guide/api-mediation/api-gateway-rest-apis-documentation.md b/docs/user-guide/api-mediation/api-gateway-rest-apis-documentation.md deleted file mode 100644 index 97d9256a24..0000000000 --- a/docs/user-guide/api-mediation/api-gateway-rest-apis-documentation.md +++ /dev/null @@ -1,7 +0,0 @@ -# API Gateway REST APIs - -The API Gateway provides different functionalities and implements several REST APIs to leverage these functionalities: - -* [Update User Password](api-mediation-update-password.md) -* [JWT token refresh endpoint](api-mediation-jwt-token-refresh.md) -* [Personal Access Tokens](../api-mediation/authenticating-with-personal-access-token) diff --git a/docs/user-guide/api-mediation/api-mediation-caching-service.md b/docs/user-guide/api-mediation/api-mediation-caching-service.md index 4af56e5e27..3b4b34d2a1 100644 --- a/docs/user-guide/api-mediation/api-mediation-caching-service.md +++ b/docs/user-guide/api-mediation/api-mediation-caching-service.md @@ -1,13 +1,14 @@ # Using the Caching Service -As an API developer, you can use the Caching Service as a storage solution to enable resource sharing between service instances, thereby ensuring High Availability of services. The Caching Service makes it possible to store, retrieve, and delete data associated with keys. The Caching Service is designed to make resource sharing possible for services that cannot be made stateless in two ways: +As an API developer, you can use the Caching Service as a storage solution to enable resource sharing between service instances, thereby ensuring High Availability of services. The Caching Service makes it possible to store, retrieve, and delete data associated with keys. The Caching Service is designed to make resource sharing possible for services that cannot be made stateless by using following backends: -- Using VSAM to store key/value pairs for production - -- Using InMemory +- Using Infinispan that is part of Caching Service +- Using Redis running off-platform +- \{Deprecated\} Using VSAM +- \{Development Use Only\} Using InMemory :::note -In the current implementation of the Caching Service, VSAM is required for the storage of key/value pairs for production, as VSAM is a native z/OS solution for storing key/value pairs. +In the current implementation of the Caching Service, Infinispan is recommended for the storage of key/value pairs for production, as it has the best performance characteristics without additional services. ::: The Caching Service is available only for internal Zowe applications, and is not exposed to the internet. The Caching service supports a hot-reload scenario in which a client service requests all available service data. @@ -48,7 +49,7 @@ Infinispan is a storage solution that can also run on the z/OS platform. It can For more information about the Infinispan storage access method, see [Using Infinispan as a storage solution through the Caching service](../../extend/extend-apiml/api-mediation-infinispan.md). -### VSAM +### VSAM (deprecated) VSAM can be used to organize records into four types of data sets: key-sequenced, entry-sequenced, linear, or relative record. Use VSAM as the storage solution for production. VSAM is used primarily for applications and is not used for source programs, JCL, or executable modules. ISPF cannot be used to display or edit VSAM files. @@ -60,7 +61,6 @@ Redis is a common storage solution that runs outside of the z/OS platform. It ca For more information about the Redis storage access method, see [Using Redis as a storage solution through the Caching Service](../../extend/extend-apiml/api-mediation-redis.md). - ### InMemory The InMemory storage method is a method suitable for testing and integration verification. Be sure not to use InMemory storage in production. diff --git a/docs/user-guide/api-mediation/api-mediation-overview.md b/docs/user-guide/api-mediation/api-mediation-overview.md index 9bec6ddfbc..0b12957d25 100644 --- a/docs/user-guide/api-mediation/api-mediation-overview.md +++ b/docs/user-guide/api-mediation/api-mediation-overview.md @@ -1,14 +1,14 @@ # API Mediation Layer -The API Mediation Layer provides a single point of access for mainframe service REST APIs. The layer offers enterprise, cloud-like features such as high-availability, scalability, dynamic API discovery, consistent security, a single sign-on experience, and documentation. The API Mediation Layer facilitates secure communication across loosely coupled microservices through the API Gateway. The API Mediation Layer consists of three components: the Gateway, the Discovery Service, and the Catalog. The Gateway provides secure communication across loosely coupled API services. The Discovery Service enables you to determine the location and status of service instances running inside the API ML ecosystem. The Catalog provides an easy-to-use interface to view all discovered services, their associated APIs, and Swagger documentation in a user-friendly manner. +The API Mediation Layer provides a single point of access for mainframe service REST APIs. The layer offers enterprise, cloud-like features such as high-availability, scalability, dynamic API discovery, consistent security, a single sign-on experience, and documentation. The API Mediation Layer facilitates secure communication across loosely coupled microservices through the API Gateway. The API Mediation Layer consists of four components: the Gateway, the Discovery Service, the Catalog and the Caching Service. The Gateway provides secure communication across loosely coupled API services. The Discovery Service enables you to determine the location and status of service instances running inside the API ML ecosystem. The Catalog provides an easy-to-use interface to view all discovered services, their associated APIs, and Swagger documentation in a user-friendly manner. The Caching Service provides stateful storage of key/value pairs. ## Key features * Consistent Access: API routing and standardization of API service URLs through the Gateway component provides users with a consistent way to access mainframe APIs at a predefined address. -* Dynamic Discovery: The Discovery Service automatically determines the location and status of API services. * High-Availability: API Mediation Layer is designed with high-availability of services and scalability in mind. * Redundancy and Scalability: API service throughput is easily increased by starting multiple API service instances without the need to change configuration. * Presentation of Services: The API Catalog component provides easy access to discovered API services and their associated documentation in a user-friendly manner. Access to the contents of the API Catalog is controlled through a z/OS security facility. * Encrypted Communication: API ML facilitates secure and trusted communication across both internal components and discovered API services. +* Service registry: Registry of available services with the status of the services. ## API Mediation Layer architecture The following diagram illustrates the single point of access through the Gateway, and the interactions between API ML components and services: @@ -24,26 +24,21 @@ Services that comprise the API ML service ecosystem are located behind a gateway ### Discovery Service -The Discovery Service is the central repository of active services in the API ML ecosystem. The Discovery Service continuously collects and aggregates service information and serves as a repository of active services. When a service is started, it sends its metadata, such as the original URL, assigned serviceId, and status information to the Discovery Service. Back-end microservices register with this service either directly or by using a Eureka client. Multiple enablers are available to help with service on-boarding of various application architectures including plain Java applications and Java applications that use the Spring Boot framework. The Discovery Service is built on Eureka and Spring Boot technology. - -#### Discovery Service TLS/SSL - -HTTPS protocol can be enabled during API ML configuration and is highly recommended. Beyond encrypting communication, the HTTPS configuration for the Discovery Service enables hightened security for service registration. Without HTTPS, services provide a username and password to register in the API ML ecosystem. When using HTTPS, only trusted services that provide HTTPS certificates signed by a trusted certificate authority can be registered. +The Discovery Service is the central repository of active services in the API ML ecosystem. The Discovery Service continuously collects and aggregates service information and serves as a repository of active services. When a service is started, it sends its metadata, such as the original URL, assigned serviceId, and status information to the Discovery Service. Back-end microservices register with this service. Multiple enablers are available to help with service on-boarding of various application architectures including plain Java applications and Java applications that use the Spring Boot framework. The Discovery Service is built on Eureka and Spring Boot technology. ### API Catalog -The API Catalog is the catalog of published API services and their associated documentation. The Catalog provides both the REST APIs and a web user interface (UI) to access them. The web UI follows the industry standard Swagger UI component to visualize API documentation in OpenAPI JSON format for each service. A service can be implemented by one or more service instances, which provide exactly the same service for high-availability or scalability. +The API Catalog is the catalog of published API services and their associated documentation. The Catalog provides both the REST APIs and a web user interface (UI) to access them. The web UI follows the industry standard Swagger UI component to visualize API documentation in OpenAPI JSON format for each service. -#### Catalog Security - Access to the API Catalog can be protected with an Enterprise z/OS Security Manager such as IBM RACF, ACF2, or Top Secret. Only users who provide proper mainframe credentials can access the Catalog. Client authentication is implemented through the zOSMF API. -## Onboarding APIs +### 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 URL of the Caching service is `https://:7555`. +For more information, see [Using the Caching Service](../api-mediation/api-mediation-caching-service). + +## Extending API ML by Onboarding new APIs The most important part of the ecosystem are the real API services that provide useful APIs. Use the following topics to understand what options you have for adding new APIs to the Mediation Layer: * [Onboarding Overview](../../extend/extend-apiml/onboard-overview.md) -## 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 URL of the Caching service is `https://:7555`. -For more information, see [Using the Caching Service](../api-mediation/api-mediation-caching-service). diff --git a/docs/user-guide/api-mediation/api-mediation-update-password.md b/docs/user-guide/api-mediation/api-mediation-update-password.md index badd80e069..a3d6985539 100644 --- a/docs/user-guide/api-mediation/api-mediation-update-password.md +++ b/docs/user-guide/api-mediation/api-mediation-update-password.md @@ -51,8 +51,4 @@ Use the following request body format in the `POST` REST call against the URL `/ "password" : "", "newPassword" : "" } -``` - -:::note -In order to use the password change functionality via z/OSMF, it is necessary to install the PTF for APAR PH34912. -::: \ No newline at end of file +``` \ No newline at end of file diff --git a/docs/user-guide/api-mediation/authenticating-with-personal-access-token.md b/docs/user-guide/api-mediation/authenticating-with-personal-access-token.md index 5ba6fa5850..f52007770d 100644 --- a/docs/user-guide/api-mediation/authenticating-with-personal-access-token.md +++ b/docs/user-guide/api-mediation/authenticating-with-personal-access-token.md @@ -6,6 +6,8 @@ You can use API Mediation Layer to generate, validate, and invalidate a **Personal Access Token (PAT)** that can enable access to tools such as VCS without having to use credentials of a specific person. The use of PAT does not require storing mainframe credentials as part of the automation configuration on a server during application development on z/OS. Additionally, using a PAT makes it possible to limit access to specific services and users by means of token revocation when using a token. +To enable the Personal Access Token functionality read: [Enable Personal Access Token](./configuration-personal-access-token.md) + Gateway APIs are available to both users as well as security administrators. APIs for users can accomplish the following functions: diff --git a/docs/user-guide/api-mediation/configuration-api-mediation-standalone.md b/docs/user-guide/api-mediation/configuration-api-mediation-standalone.md index 72943a5307..4b5eec43ce 100644 --- a/docs/user-guide/api-mediation/configuration-api-mediation-standalone.md +++ b/docs/user-guide/api-mediation/configuration-api-mediation-standalone.md @@ -8,7 +8,7 @@ By default, the Gateway, Zowe System Services, and Virtual Desktop start when support this setup. Once Zowe is installed, use the following procedure to limit which components start. Keep in mind that Zowe System Services are needed -for some of the functionalities of the API Mediation Layer such as Client Certificates or OIDC +for some of the functionalities of the API Mediation Layer such as SAF IDT tokens. **Follow these steps:** diff --git a/docs/user-guide/api-mediation/configuration-at-tls.md b/docs/user-guide/api-mediation/configuration-at-tls.md index ac9abbf33d..5972dfcdde 100644 --- a/docs/user-guide/api-mediation/configuration-at-tls.md +++ b/docs/user-guide/api-mediation/configuration-at-tls.md @@ -18,15 +18,11 @@ Review this article for descriptions of the configuration parameters required to ## AT-TLS configuration for Zowe -:::tip -Support for AT-TLS was introduced in Zowe v1.24. In this early version, startup was not possible in some versions of Zowe. For full support, we recommend that you upgrade to v2.13 or a later version of Zowe. -::: - Follow these steps to configure Zowe to support AT-TLS: 1. Enable the AT-TLS profile and disable the TLS application in API ML. -Update `zowe.yaml` with the following values under `gateway`, `discovery`, `api-catalog`, `caching-service` and `metrics-service` in the `zowe.components` section. +Update `zowe.yaml` with the following values under `gateway`, `discovery`, `api-catalog`, `caching-service` and `zaas` in the `zowe.components` section. **Example:** @@ -64,7 +60,7 @@ zowe: server: ssl: enabled: false - metrics-service: + zaas: spring: profiles: active: attls @@ -78,8 +74,6 @@ While API ML does not handle TLS on its own with AT-TLS enabled, API ML requires If there is an outbound AT-TLS rule configured for the link between the API Gateway and z/OSMF, set the `zowe.zOSMF.scheme` property to `http`. :::note Notes -* AT-TLS is supported in the API Cloud Gateway Mediation Layer component beginning with version 2.17. - * As the Gateway is a core component of API ML, other components that need to interact with the Gateway, such as Zowe ZLUX App Server, also require AT-TLS configuration. ::: @@ -136,13 +130,13 @@ TTLSConnectionAction ApimlServerConnectionAction The `PortRange` of this inbound rule is taken from the list of API Mediation Layer components in the `zowe.yaml` file. The `PortRange` should cover the following components: -| Component | Port | -|----|-----------------------| -| Gateway | default port 7554 | -| Discovery | default port 7553 | -|Caching Service | 7555 | -|API Catalog | default port 7552 | -| Metrics Service | default port 7551 | +| Component | Port | +|-----------------|-------------------| +| Gateway | default port 7554 | +| Discovery | default port 7553 | +| Caching Service | default port 7555 | +| API Catalog | default port 7552 | +| ZAAS | default port | **Follow this step:** diff --git a/docs/user-guide/api-mediation/configuration-client-certificates.md b/docs/user-guide/api-mediation/configuration-client-certificates.md index 9c13ed8e79..652bcb45f0 100644 --- a/docs/user-guide/api-mediation/configuration-client-certificates.md +++ b/docs/user-guide/api-mediation/configuration-client-certificates.md @@ -6,9 +6,9 @@ You can authenticate against API ML onboarded APIs. This functionality is disabled by default. Follow the steps in this article to enable authentication against API ML onboarded APIs. There are two methods to enable client certificate functionality: -* The original and default method via ZSS -* The newer and recommended method via the internal mapper component of API Mediation Layer +* The default and recommended method via the internal mapper component of API Mediation Layer The internal API ML mapper is simpler to configure and provides more functionality than ZSS. +* The older and deprecated method via ZSS Review this article to learn about the required configuration to authenticate with either method. @@ -64,7 +64,7 @@ Ensure that you have the Issuer certificate imported in the truststore or in the ::: :::tip -There is a limitation with respect to performing authentication using Z Secure Services (ZSS) with ACF2 systems. If you are using ACF2, and are using Zowe v2.14 or a later version, use the recommended internal API ML mapper. +There is a limitation with respect to performing authentication using Z Secure Services (ZSS) with ACF2 systems. If you are using ACF2, use the recommended internal API ML mapper. ::: ### Enabling zowe.yaml to use a client certificate diff --git a/docs/user-guide/api-mediation/configuration-customizing-java-heap-sizes.md b/docs/user-guide/api-mediation/configuration-customizing-java-heap-sizes.md index 1f167ab8c5..84591b468b 100644 --- a/docs/user-guide/api-mediation/configuration-customizing-java-heap-sizes.md +++ b/docs/user-guide/api-mediation/configuration-customizing-java-heap-sizes.md @@ -17,6 +17,7 @@ Specifies one of the following services: - `discovery` - `caching-service` - `api-catalog` + - `zaas` **Example with Gateway Service:** diff --git a/docs/user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits.md b/docs/user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits.md index a2808c0e6a..a58d091713 100644 --- a/docs/user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits.md +++ b/docs/user-guide/api-mediation/configuration-customizing-management-of-apiml-load-limits.md @@ -9,7 +9,3 @@ As a system programmer, you can customize your configuration for how API ML mana * To change the global Gateway timeout value for the API ML instance, see [Customizing Gateway timeouts](./configuration-gateway-timeouts.md). - * Also see the following properties in API Gateway configuration parameters: - * `server.maxTotalConnections` - * `server.maxConnectionsPerRoute` - diff --git a/docs/user-guide/api-mediation/configuration-customizing-the-api-catalog-ui.md b/docs/user-guide/api-mediation/configuration-customizing-the-api-catalog-ui.md index 6d4501c14e..7658e54c8e 100644 --- a/docs/user-guide/api-mediation/configuration-customizing-the-api-catalog-ui.md +++ b/docs/user-guide/api-mediation/configuration-customizing-the-api-catalog-ui.md @@ -13,7 +13,7 @@ As a system administrator, you can customize the API Catalog UI to have a simila It is possible to customize the logotype and selected style options directly in `zowe.yaml`. 1. Open the file `zowe.yaml`. -2. Configure the following properties by setting them under `ZWE_configs_apiml_catalog_customStyles`: +2. Configure the following properties by setting them under `configs.apiml.catalog.customStyles`: - **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`. diff --git a/docs/user-guide/api-mediation/configuration-distributed-load-balancer-cache.md b/docs/user-guide/api-mediation/configuration-distributed-load-balancer-cache.md index 1a19517c58..fcd62fb230 100644 --- a/docs/user-guide/api-mediation/configuration-distributed-load-balancer-cache.md +++ b/docs/user-guide/api-mediation/configuration-distributed-load-balancer-cache.md @@ -3,7 +3,7 @@ :::info Role: system programmer ::: -You can choose to distribute the load balancer cache between instances of the API Gateway. To distribute the load balancer cache, it is necessary that the caching service is running. Gateway service instances are reuqired to have the same DN (Distinguished name) on the server certificate. This may be relevant for the HA setups. +You can choose to distribute the load balancer cache between instances of the API Gateway. To distribute the load balancer cache, it is necessary that the caching service is running. Gateway service instances are required to have the same DN (Distinguished name) on the server certificate. This may be relevant for the HA setups. Use the following procedure to distribute the load balancer cache between instances of the API Gateway. 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 55474f4cf2..9cdb37ceaa 100644 --- a/docs/user-guide/api-mediation/configuration-personal-access-token.md +++ b/docs/user-guide/api-mediation/configuration-personal-access-token.md @@ -4,6 +4,8 @@ :::info Roles: system programmer, system administrator, security administrator ::: +For Personal Access Token functionality to work properly, Caching Service with Infinispan ad backedn provider needs to be started. + Use the following procedure to enable personal access tokens. 1. Open the file `zowe.yaml`. diff --git a/docs/user-guide/api-mediation/configuration-set-consistent-service-id.md b/docs/user-guide/api-mediation/configuration-set-consistent-service-id.md index 59f962b5ac..0331445d2a 100644 --- a/docs/user-guide/api-mediation/configuration-set-consistent-service-id.md +++ b/docs/user-guide/api-mediation/configuration-set-consistent-service-id.md @@ -3,9 +3,9 @@ :::info Role: API service extender ::: -As an API service extender you can modify the service ID to ensure compatibility of services that use a non-conformant organization prefix with Zowe v2. +As an API service extender you can modify the service ID to ensure compatibility of services that use a non-conformant organization prefix. For more information, see the following parameter in the article Discovery Service configuration parameters: * **components.discovery.apiml.discovery.serviceIdPrefixReplacer** - This parameter is used to modify the service ID of a service instance, before it registers to API ML. Using this parameter ensures compatibility of services that use a non-conformant organization prefix with v2, based on Zowe v2 conformance. \ No newline at end of file + This parameter is used to modify the service ID of a service instance, before it registers to API ML. Using this parameter ensures compatibility of services that use a non-conformant organization prefix with. \ No newline at end of file diff --git a/docs/user-guide/api-mediation/diagrams/service-relationship-diagram.png b/docs/user-guide/api-mediation/diagrams/service-relationship-diagram.png index ddf6741773..65886a4144 100644 Binary files a/docs/user-guide/api-mediation/diagrams/service-relationship-diagram.png and b/docs/user-guide/api-mediation/diagrams/service-relationship-diagram.png differ diff --git a/docs/user-guide/api-mediation/discovery-service-configuration.md b/docs/user-guide/api-mediation/discovery-service-configuration.md index e5b50218e9..2b38398331 100644 --- a/docs/user-guide/api-mediation/discovery-service-configuration.md +++ b/docs/user-guide/api-mediation/discovery-service-configuration.md @@ -2,7 +2,7 @@ ## Zowe runtime configuration parameters -As an application developer who wants to run Zowe, set the following parameters during the Zowe runtime configuration by modifying the `/components/discovery/bin/start.sh` file: +As an application developer who wants to run Zowe, set the following parameters during the Zowe runtime configuration by modifying the `zowe.yaml` file: * **[API ML configuration](#api-ml-configuration)** @@ -13,24 +13,24 @@ As an application developer who wants to run Zowe, set the following parameters 1. Open the file `zowe.yaml`. 2. Configure the following properties: -* **apiml.service.hostname** +* **haInstance.hostname** - This property is used to set the Discovery Service hostname. The value can be set by defining the `ZWE_haInstance_hostname` property in the `zowe.yaml` file. + This property is used to set the Discovery Service hostname. The value can be set by defining the `haInstance.hostname` property in the `zowe.yaml` file. -* **apiml.service.port** +* **components.discovery.port** - This property is used to set the Discovery Service port. The value can be set by defining the `ZWE_configs_port` property in the `zowe.yaml` file. + This property is used to set the Discovery Service port. The value can be set by defining the `components.discovery.port` property in the `zowe.yaml` file. -* **apiml.discovery.staticApiDefinitionsDirectories** +* **environments.ZWE_STATIC_DEFINITIONS_DIR** - The value of `apiml.discovery.staticApiDefinitionsDirectories` can be set by defining the `ZWE_STATIC_DEFINITIONS_DIR` property in `zowe.yaml`. The static definition directories can be specified as a parameter at startup and will be scanned by the Discovery Service. These directories contain the definitions of static services. + The static definition directories can be specified as a parameter at startup and will be scanned by the Discovery Service. These directories contain the definitions of static services. **Example:** ```yaml - ZWE_STATIC_DEFINITIONS_DIR: config/local/api-defs;config/local2/api-defs + environments: + ZWE_STATIC_DEFINITIONS_DIR: config/local/api-defs;config/local2/api-defs ``` -* **apiml.discovery.allPeersUrls** +* **environments.ZWE_DISCOVERY_SERVICES_LIST** - The value of `apiml.discovery.allPeersUrls` can be set by defining the `ZWE_DISCOVERY_SERVICES_LIST` property in `zowe.yaml`. This parameter contains the list of URLs of the Discovery Service in case of multiple instances of the service on different host. **Example:** ```yaml diff --git a/docs/user-guide/api-mediation/routing-requests-to-rest-apis.md b/docs/user-guide/api-mediation/routing-requests-to-rest-apis.md index a9bcb49c03..79d97e32f8 100644 --- a/docs/user-guide/api-mediation/routing-requests-to-rest-apis.md +++ b/docs/user-guide/api-mediation/routing-requests-to-rest-apis.md @@ -84,8 +84,6 @@ The configuration entries of each LPAR in the `zowe.yaml` file control which com The caching services for each Zowe instance, whether on the same LPAR, or distributed across the sysplex, are connected to each other by the same shared VSAM data set. This arrangement allows state sharing so that each instance behaves similarly to the user irrespective of where their request is routed. -For simplification of the preceding diagram, the Jobs and Files API servers are not shown as being started. If the user defines Jobs and Files API servers to be started in the `zowe.yaml` configuration file, these servers behave the same as the servers that are illustrated. In other words, these services register to their API discovery server which then communicates with other discovery servers on other Zowe instances on either the same or other LPARs. The API traffic received by any API Gateway on any Zowe instance is routed to any of the Jobs or Files API components that are available. - To learn more about Zowe with high availability enablement, see [Configuring Sysplex for high availability](../configure-sysplex). ## API Versioning diff --git a/docs/user-guide/authenticating-with-client-certificates.md b/docs/user-guide/authenticating-with-client-certificates.md index 9e2564deb8..27b58d2be8 100644 --- a/docs/user-guide/authenticating-with-client-certificates.md +++ b/docs/user-guide/authenticating-with-client-certificates.md @@ -19,7 +19,7 @@ When sending a request to a service with a client certificate, the Gateway perfo 1. The client calls the service endpoint through the API ML Gateway with the client certificate. 2. The client certificate is verified as a valid TLS client certificate against the trusted certificate authorities (CAs) of the Gateway. -3. The public key of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. As of Zowe version 2.14, the API for API ML can be provided by the internal API ML mapper if the mapper is enabled. Alternatively, you can use Z Secure Services (ZSS) to provide this API for API ML, although we recommend using the internal API ML mapper. +3. The public key of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. The API for API ML can be provided by the internal API ML mapper if the mapper is enabled. Alternatively, you can use Z Secure Services (ZSS) to provide this API for API ML, although we recommend using the internal API ML mapper. 4. The Gateway then performs the login of the mapped user and provides valid authentication to the downstream service. :::note Notes: @@ -31,7 +31,7 @@ When sending a request to the login endpoint with a client certificate, the Gate 1. The client calls the API ML Gateway login endpoint with the client certificate. 2. The client certificate is verified to ensure this is a valid TLS client certificate against the trusted CAs of the Gateway. -3. The public part of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. As of Zowe release 2.14, the internal API ML mapper can provide this API for API ML if enabled in the zowe.yaml file. Alternatively, ZSS can provide this API for API ML, with the noted exception when using ACF2. +3. The public part of the provided client certificate is verified against SAF. SAF subsequently returns a user ID that owns this certificate. The internal API ML mapper can provide this API for API ML if enabled in the zowe.yaml file. Alternatively, ZSS can provide this API for API ML, with the noted exception when using ACF2. 4. The Gateway then performs the login of the mapped user and returns a valid JWT token. :::note diff --git a/docs/user-guide/authentication-providers-for-apiml.md b/docs/user-guide/authentication-providers-for-apiml.md index 8a2eff5a90..48454df956 100644 --- a/docs/user-guide/authentication-providers-for-apiml.md +++ b/docs/user-guide/authentication-providers-for-apiml.md @@ -24,7 +24,7 @@ The `z/OSMF Authentication Provider` allows the API Gateway to authenticate with Use the following properties of the API Gateway to enable the `z/OSMF Authentication Provider`: ``` components.gateway.security.auth.provider: zosmf -components.gateway.security.auth.zosmfServiceId: zosmf # Replace me with the correct z/OSMF service id +components.gateway.security.auth.zosmfServiceId: ibmzosmf # Replace me with the correct z/OSMF service id ``` ## SAF Authentication Provider diff --git a/docs/user-guide/install-zos.md b/docs/user-guide/install-zos.md index 0ced2e3e3f..ba51c86db8 100644 --- a/docs/user-guide/install-zos.md +++ b/docs/user-guide/install-zos.md @@ -46,7 +46,7 @@ Notify your organization's network administrator to assign port numbers, reserve In most cases, the system programmer performs the Zowe installation and configuration, and starts Zowe. Ensure that your system programmers have general knowledge about SMP/E, z/OSMF workflows, and regular maintanance procedures. In many cases, the system programmer also prepares jobs for other administrators. -## End-to-end installation +## End-to-end installation The following diagram illustrates the full ecosystem for installing Zowe server-side components for z/OS. diff --git a/docs/user-guide/systemrequirements-zos.md b/docs/user-guide/systemrequirements-zos.md index 4e31d23d43..d9fee4bbe4 100644 --- a/docs/user-guide/systemrequirements-zos.md +++ b/docs/user-guide/systemrequirements-zos.md @@ -16,10 +16,11 @@ Be sure your z/OS system meets the following prerequisites: ### z/OS -- z/OS version is in active support, such as Version 2.4, 2.5, and 3.1 +- z/OS version is in active support, such as Version 2.5, and 3.1 :::note Notes: * Zowe Version 2.11 or higher is required when using z/OS Version 3.1. + * z/OS V2.4 reached end of support on 30 September, 2024. For more information, see the [z/OS v2.4 lifecycle details](https://www.ibm.com/support/pages/zos24x-withdrawal-notification). * z/OS V2.3 reached end of support on 30 September, 2022. For more information, see the [z/OS v2.3 lifecycle details](https://www.ibm.com/support/pages/zos23x-withdrawal-notification). ::: @@ -94,11 +95,11 @@ Zowe consumption reference data were measured with the default Zowe configuratio ### z/OSMF (Optional) -- (Optional, recommended) IBM z/OS Management Facility (z/OSMF) Version 2.4, Version 2.5, or Version 3.1. +- (Optional, recommended) IBM z/OS Management Facility (z/OSMF) Version 2.5, or Version 3.1. z/OSMF is included with z/OS so does not need to be separately installed. If z/OSMF is present, Zowe detects z/OSMF during configuration and uses z/OSMF for the following purposes: - - Authenticating TSO users and generating a single sign-on JSON Web Token (JWT). Ensure that the [z/OSMF JWT Support is available via APAR and associated PTFs](https://www.ibm.com/support/pages/apar/PH12143). If z/OSMF is not available, Zowe is still able to provide SSO by generating its own JWT and making direct SAF calls. + - Authenticating TSO users and generating a single sign-on JSON Web Token (JWT). Ensure that the [z/OSMF JWT Support is available via APAR and associated PTFs](https://www.ibm.com/support/pages/apar/PH12143). - REST API services for Files (Data Sets and USS), JES, and z/OSMF workflows. These are used by some Zowe applications such as the Zowe Explorers in the Zowe Desktop. If z/OSMF REST APIs are not present, other Zowe desktop application, such as the File Editor that provides access to USS directories and files as well as MVS data sets and members, will work through the Zowe Z Secure Services (ZSS) component to access z/OS resources.