Merge branch 'docs-staging' into anax-v3.0-sync-branches-docs

Signed-off-by: Pablo Carle <[email protected]>
zowe · Jan 8, 2025 · 12e2238 · 12e2238
2 parents 32205c6 + 1752df4
commit 12e2238
Show file tree

Hide file tree

Showing 19 changed files with 374 additions and 243 deletions.
diff --git a/docs/diagrams/apiml-oidc-auth-seq.puml b/docs/diagrams/apiml-oidc-auth-seq.puml
@@ -4,32 +4,40 @@
 autonumber
 actor User
 actor "User Agent" as Agent
-actor "Client App" as Client
 actor OIDC as OIDC
 actor "API ML GW" as GW
 
 User -> Agent: Do stuff
-Agent -> Client: Open Client App
-Client -> OIDC: Initiate OIDC flow [client_id, client_secret]
-loop [MFA]
+Agent -> GW: /gateway/oauth2/authorization/<provider-id>
+GW -> OIDC: Initiate OIDC flow [client_id, client_secret]
+group MFA
 OIDC -> Agent: Request user credentials
 User <-> Agent: Provide credentials
 Agent -> OIDC: Validate credentials
 end
-OIDC --> Client: Return Auth Code / JWTs[access,refresh,identity]
-Client -> GW: Request resources [JWT AT]
-group validate
-GW -> GW: Validate AT
-GW -> OIDC: Validate AT
-end
-alt Validation success
-GW -> GW: Cache AT validity
+OIDC --> GW: Return Auth Code / JWTs[access,refresh,identity]
+GW -> Agent: Set-cookie access token
+Agent -> GW: Request resources [access token]
+GW -> GW: Validate access token
+GW -> GW: Cache access token validity
+group map user
 GW -> SAF: Map distributed ID to mainframe ID
+end
+alt mapping success
 GW -> GW: Create Zowe JWT
-GW -> Service: call API service
-Service --> GW: return Response
+GW -> Service: Call API service with Zowe JWT
+Service -> Service: Validate JWT
+Service --> GW: Return Response
+autonumber 14 1
+else mapping failure
+
+GW -> Service: call API service with access token
+note left: Step 13 Create Zowe JWT was skipped
+Service -> Service: Validate access token
+Service --> GW: Return Response
 end
-GW --> Client: Response
-Client --> Agent: Response
+autonumber 17 1
+GW --> Agent: Response
+
 
 @enduml
diff --git a/docs/extend/extend-apiml/api-mediation-oidc-authentication.md b/docs/extend/extend-apiml/api-mediation-oidc-authentication.md
diff --git a/docs/extend/extend-apiml/custom-metadata.md b/docs/extend/extend-apiml/custom-metadata.md
@@ -105,6 +105,18 @@ Optionally, service can specify which origins will be accepted by Gateway during
 * **customMetadata.apiml.lb.cacheRecordExpirationTimeInHours**  
 When the property `customMetadata.apiml.lb.type` is set to `authentication`, the user can also define the expiration time for the selected instance information that is cached. This property aims to prevent any discrepancy which might occur if the required target server is no longer available. The default value is 8 hours.   
 
+* **customMetadata.apiml.gateway.applyRateLimiterFilter**  
+This parameter specifies the services that the rater limiter is applied to. When enabling this filter, you can also define the following properties:
+  * `customMetadata.apiml.gateway.rateLimiterCapacity`  
+  Defines the total number of requests that can be allowed at one time per user
+  * `customMetadata.apiml.gateway.rateLimiterTokens`  
+  Defines the number of requests that are added to the service’s allowance at regular intervals
+  * `customMetadata.apiml.gateway.rateLimiterRefillDuration`  
+  Sets the time interval (in minutes) at which new requests (or tokens) are added.
+
+  When no values are provided, global values defined in the Gateway are applied. For more information about the default configuration, see [Customizing gateway rate limiter filer](../../user-guide/api-mediation/customizing-gateway-rate-limiter.md).
+
+
 * **customMetadata.apiml.response.compress**  
 When this parameter is set to `true`, API ML compresses content for all responses from this services using GZIP. API ML also adds the `Content-Encoding` header with value `gzip` to responses.
 

diff --git a/docs/extend/zowe-conformance-program.md b/docs/extend/zowe-conformance-program.md
@@ -19,7 +19,7 @@ The [Zowe Conformance Program Explained](https://medium.com/zowe/zowe-conformanc
 
 To participate in the Zowe Conformance Program, follow the process on the [Zowe Conformance Program website](https://openmainframeproject.org/our-projects/zowe-conformance-program/). You can also find a list of products that have earned Zowe Conformant status.  
 
-To learn the criteria of achieving Zowe conformance for an offering, see [Zowe Conformance Criteria](https://github.com/openmainframeproject/foundation/tree/master/zowe_conformance).
+To learn the criteria of achieving Zowe conformance for an offering, see [Zowe Conformance Criteria](https://github.com/openmainframeproject/foundation/blob/main/zowe_conformance/test_evaluation_guide_table.md).
 
 ## How to suggest updates to the Zowe conformance program
 

diff --git a/docs/getting-started/user-roadmap-zowe-explorer.md b/docs/getting-started/user-roadmap-zowe-explorer.md
@@ -50,10 +50,20 @@ The Zowe ecosystem is more than a collection of applications and extensions. An
 
 - If you have an issue that is specific to Zowe Explorer, you can [**submit an issue**](https://github.com/zowe/zowe-explorer-vscode/issues/new/choose) in the `zowe-explorer-vscode` repository on GitHub.
 
-## Zowe Conformance Program
+## Community resources
 
-Administered by the Open Mainframe Project, the [Zowe Conformance Program](../extend/zowe-conformance-program.md) aims to give users the confidence that when they use a product, app, or distribution that leverages Zowe, they can **expect a high level of common functionality**, **interoperability**, and **user experience**.
+* [**Slack channel**](https://openmainframeproject.slack.com/)
 
-As vendors, you are invited to submit conformance testing results for review and approval by the Open Mainframe Project. If your company provides software based on Zowe Explorer, you are encouraged to get certified today.
+   Join the `# zowe-explorer` Slack channel to ask questions, propose new ideas, and interact with the Zowe community.
 
-Read the blog post [**Zowe Conformance Program Explained**](https://medium.com/zowe/zowe-conformance-program-7f1574ade8ea) for more details about the Conformance Program, including useful references.
+* [**Zowe Explorer squad meetings**](https://zoom-lfx.platform.linuxfoundation.org/meetings/zowe)
+
+   You can join one of the Zowe Explorer squad meetings to get involved.
+
+* [**Zowe Blogs on Medium**](https://medium.com/zowe)
+
+   Read a series of blog articles about Zowe on Medium to explore use cases, best practices, and more.
+
+* **Community Forums**
+
+   Look for discussion on Zowe topics on the [Open Mainframe Project Community Forums](https://community.openmainframeproject.org/c/zowe).
diff --git a/docs/images/api-mediation/apiml-oidc-auth-seq.png b/docs/images/api-mediation/apiml-oidc-auth-seq.png
diff --git a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md
@@ -2,7 +2,7 @@
 
 Zowe supports management of multiple tenants, whereby different tenants can serve different purposes or different customers. The use case for multi-tenant support is when a service provider manages sysplexes/monoplexes for multiple customers. This configuration makes it possible to have a single access point for all customers, and properly route and authenticate across different domains.
 
-## Overview of API MLs 
+## Overview of API MLs
 
 The following diagram illustrates communication between the API Mediation Layers and Zowe in multiple domains. Note that some API MLs may be running in a sysplex (HA), while others may be in a monoplex (non-HA).
 
@@ -27,9 +27,9 @@ A Gateway from any domain can onboard Gateways of any other domains. Onboarding
 
 1. In zowe.yml, set the following property for the Gateway of API MLs in Domain(2-N) to dynamically onboard to the Discovery service of API ML in Domain-1:
 
-`components.gateway.apiml.service.additionalRegistration`
+    `components.gateway.apiml.service.additionalRegistration`
 
-Use the following example as a template for how to set the value of this property in zowe.yml.
+Use the following example as a template for how to set the value of this property in zowe.yaml.
 
 **Example:**
 ```
@@ -88,7 +88,7 @@ This Zowe configuration transforms the zowe.yaml configuration file into the env
 
 ### Validating successful configuration
 
-The corresponding Gateway service in domain(2-N) should appear in the Eureka console of the Discovery service in the domain-1 API ML. 
+The corresponding Gateway service in domain(2-N) should appear in the Eureka console of the Discovery service in the domain-1 API ML.
 
 To see details of all instances of the ‘GATEWAY’ application, perform a **GET** call on the following endpoint of the Discovery service in domain-1 API ML:
 
@@ -129,29 +129,34 @@ The following commands are examples of establishing a trust relationship between
 
 1. Import the root and, if applicable, the intermediate public key certificate of registered "Domain API ML 2" and "Domain API ML 3" API MLs running on systems Y and Z into the truststore of the "Domain API ML 1" running on system X.
 
-  - **PKCS12**
+    - **PKCS12**
 
-    For PKCS12 certificates, use the following example of keytool commands:
+      <details>
+      <summary>Click here for an example of keytool commands for PKCS12 certificates.</summary>
+
+      For PKCS12 certificates, use the following example of keytool commands:
 
-    `keytool -import -file sysy/keystore/local_ca/local_ca.cer -alias gateway_sysy -keystore sysx/keystore/localhost/localhost.truststore.p12`
+      `keytool -import -file sysy/keystore/local_ca/local_ca.cer -alias gateway_sysy -keystore sysx/keystore/localhost/localhost.truststore.p12`
 
-    `keytool -import -file sysz/keystore/local_ca/local_ca.cer -alias gateway_sysz -keystore sysx/keystore/localhost/localhost.truststore.p12`
+      `keytool -import -file sysz/keystore/local_ca/local_ca.cer -alias gateway_sysz -keystore sysx/keystore/localhost/localhost.truststore.p12`
+
+      </details>
 
-  - **Keyring**
+    - **Keyring**
 
     For keyrings, use the following examples of commands specific to your ESM to add certificates from the dataset and connect these certificates to the keyring used by the "Domain APIML 1":
 
     <details>
     <summary>Click here for command details for RACF.</summary>
     - **For RACF:**
 
-      ```
-      RACDCERT ADD('SHARE.SYSY.ROOTCA.CER') ID(ZWESVUSR) WITHLABEL('DigiCert Root CA') TRUST
-      RACDCERT ADD('SHARE.SYSZ.INTERCA.CER') ID(ZWESVUSR) WITHLABEL('DigiCert CA') TRUST
-      RACDCERT ID(ZWESVUSR) CONNECT(ID(ZWESVUSR) LABEL('DigiCert Root CA') RING(ZoweKeyring) USAGE(CERTAUTH))
-      RACDCERT ID(ZWESVUSR) CONNECT(ID(ZWESVUSR) LABEL('DigiCert CA') RING(ZoweKeyring) USAGE(CERTAUTH))
-      SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH
-      ```
+        ```
+        RACDCERT ADD('SHARE.SYSY.ROOTCA.CER') ID(ZWESVUSR) WITHLABEL('DigiCert Root CA') TRUST
+        RACDCERT ADD('SHARE.SYSZ.INTERCA.CER') ID(ZWESVUSR) WITHLABEL('DigiCert CA') TRUST
+        RACDCERT ID(ZWESVUSR) CONNECT(ID(ZWESVUSR) LABEL('DigiCert Root CA') RING(ZoweKeyring) USAGE(CERTAUTH))
+        RACDCERT ID(ZWESVUSR) CONNECT(ID(ZWESVUSR) LABEL('DigiCert CA') RING(ZoweKeyring) USAGE(CERTAUTH))
+        SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH
+        ```
 
       Verify:
       ```
@@ -163,18 +168,18 @@ The following commands are examples of establishing a trust relationship between
     <summary>Click here for command details for ACF2.</summary>
     - **For ACF2:**
       
-      ```
-      ACF
-      SET PROFILE(USER) DIV(CERTDATA)
-      INSERT CERTAUTH.SYSYROOT DSNAME('SHARE.SYSY.ROOTCA.CER') LABEL(DigiCert Root CA) TRUST
-      INSERT CERTAUTH.SYSZINTR DSNAME('SHARE.SYSZ.INTERCA.CER') LABEL(DigiCert CA) TRUST
-      F ACF2,REBUILD(USR),CLASS(P),DIVISION(CERTDATA)
+        ```
+        ACF
+        SET PROFILE(USER) DIV(CERTDATA)
+        INSERT CERTAUTH.SYSYROOT DSNAME('SHARE.SYSY.ROOTCA.CER') LABEL(DigiCert Root CA) TRUST
+        INSERT CERTAUTH.SYSZINTR DSNAME('SHARE.SYSZ.INTERCA.CER') LABEL(DigiCert CA) TRUST
+        F ACF2,REBUILD(USR),CLASS(P),DIVISION(CERTDATA)
       
-      SET PROFILE(USER) DIVISION(KEYRING)
-      CONNECT CERTDATA(CERTAUTH.SYSYROOT) LABEL(DigiCert Root CA) KEYRING(ZWESVUSR.ZOWERING) USAGE(CERTAUTH)
-      CONNECT CERTDATA(CERTAUTH.SYSZINTR) LABEL(DigiCert CA) KEYRING(ZWESVUSR.ZOWERING) USAGE(CERTAUTH)
-      F ACF2,REBUILD(USR),CLASS(P),DIVISION(KEYRING)
-      ```
+        SET PROFILE(USER) DIVISION(KEYRING)
+        CONNECT CERTDATA(CERTAUTH.SYSYROOT) LABEL(DigiCert Root CA) KEYRING(ZWESVUSR.ZOWERING) USAGE(CERTAUTH)
+        CONNECT CERTDATA(CERTAUTH.SYSZINTR) LABEL(DigiCert CA) KEYRING(ZWESVUSR.ZOWERING) USAGE(CERTAUTH)
+        F ACF2,REBUILD(USR),CLASS(P),DIVISION(KEYRING)
+        ```
       
       Verify:
       ```
@@ -187,12 +192,12 @@ The following commands are examples of establishing a trust relationship between
     <summary>Click here for command details for Top Secret.</summary>
     - **For Top Secret:**
       
-      ```
-      TSS ADD(CERTAUTH) DCDS(SHARE.SYSY.ROOTCA.CER)  DIGICERT(SYSYROOT) LABLCERT('DigiCert Root CA') TRUST
-      TSS ADD(CERTAUTH) DCDS(SHARE.SYSZ.INTERCA.CER)  DIGICERT(SYSZINTR) LABLCERT('DigiCert CA') TRUST
-      TSS ADD(ZWESVUSR) KEYRING(ZOWERING) RINGDATA(CERTAUTH,SYSYROOT) USAGE(CERTAUTH)
-      TSS ADD(ZWESVUSR) KEYRING(ZOWERING) RINGDATA(CERTAUTH,SYSZINTR) USAGE(CERTAUTH)
-      ```
+        ```
+        TSS ADD(CERTAUTH) DCDS(SHARE.SYSY.ROOTCA.CER)  DIGICERT(SYSYROOT) LABLCERT('DigiCert Root CA') TRUST
+        TSS ADD(CERTAUTH) DCDS(SHARE.SYSZ.INTERCA.CER)  DIGICERT(SYSZINTR) LABLCERT('DigiCert CA') TRUST
+        TSS ADD(ZWESVUSR) KEYRING(ZOWERING) RINGDATA(CERTAUTH,SYSYROOT) USAGE(CERTAUTH)
+        TSS ADD(ZWESVUSR) KEYRING(ZOWERING) RINGDATA(CERTAUTH,SYSZINTR) USAGE(CERTAUTH)
+        ```
 
       Verify:
       ```
@@ -202,15 +207,20 @@ The following commands are examples of establishing a trust relationship between
       
 2. Import root and, if applicable, intermediate public key certificates of the API ML running on system X into the truststore of the API MLs running on systems Y and Z.
 
-  - **PKCS12**
+    - **PKCS12**
+
+      <details>
+      <summary>Click here for example keytool commands for PKCS12 certificates.</summary>
 
-    For PKCS12 certificates, use the following example of the keytool commands:
+      For PKCS12 certificates, use the following example of the keytool commands:
 
-    `keytool -import -file x/keystore/local_ca/local_ca.cer -alias gateway_x -keystore y/keystore/localhost/localhost.truststore.p12`
+      `keytool -import -file x/keystore/local_ca/local_ca.cer -alias gateway_x -keystore y/keystore/localhost/localhost.truststore.p12`
 
-    `keytool -import -file x/keystore/local_ca/local_ca.cer -alias gateway_x -keystore z/keystore/localhost/localhost.truststore.p12`
+      `keytool -import -file x/keystore/local_ca/local_ca.cer -alias gateway_x -keystore z/keystore/localhost/localhost.truststore.p12`
   
-  - **Keyring**
+      </details>
+
+    - **Keyring**
 
     For keyring certificates, use the following examples of commands specific to your ESM to add certificates from the dataset, and connect these certificates to the keyrings used by registered API MLs:
   
@@ -270,12 +280,15 @@ The following commands are examples of establishing a trust relationship between
 
 You completed certificates setup for multitenancy configuration, whereby registered API MLs can trust the API ML where they are registered and vice versa.
 
-## Using the `/registry` endpoint in the Gateway
+## Using the `/registry` endpoint in the Central Cloud Gateway
 
+The `/registry` endpoint provides information about services onboarded to all registered Gateways. This section describes the configuration, authentication, authorization, example of requests, and responses when using the `/registry` endpoint. 
 The `/registry` endpoint provides information about services onboarded to all registered Gateways. This section describes the configuration, authentication, authorization, example of requests, and responses when using the `/registry` endpoint. 
 
 ### Configuration for `/registry`
 
+The `/registry` endpoint is disabled by default. Use the configuration property `apiml.gateway.registry.enabled=true` or
+environment variable `APIML_GATEWAY_REGISTRY_ENABLED=TRUE` to enable this feature.
 The `/registry` endpoint is disabled by default. Use the configuration property `apiml.gateway.registry.enabled=true` or
 environment variable `APIML_GATEWAY_REGISTRY_ENABLED=TRUE` to enable this feature.
 
@@ -429,7 +442,7 @@ This response should contain information about a specific service in an APIML wi
                 "status": "UP",
                 "customMetadata": {
                     "zos.sysname": "sys2",
-		             "zos.sysplex": "sysplex"
+		            "zos.sysplex": "sysplex"
                 },
                 "apiId": [
                     "zowe.apiml.catalog"
@@ -446,85 +459,6 @@ This response should contain information about a specific service in an APIML wi
 
 Use the `/registry` endpoint to validate successful configuration. The response should contain all the API MLs represented by `apimlId`, and information about onboarded services.
 
-## Gateway static definition example (deprecated)
-
-The Gateway static definition file should be stored together with other statically onboarded services. The default location is `/zowe/runtime/instance/workspace/api-mediation/api-defs/`. 
-There is no naming restriction of the filename, but the file extension must be `yml`.
-
-<details>
-<summary>Click here for a Gateway static definition example.</summary>
-
-**Example:**
-```
-#
-# Static definition of "discoverable-client" as "staticclient"
-#
-# This file provides static API service definition in YAML format.
-# It is loaded by the Discovery Service during its startup.
-#
-services:
-   - serviceId: GATEWAY  # unique lowercase ID of the service
-     catalogUiTileId: static  # ID of the API Catalog UI tile (visual grouping of the services)
-     title: Statically Defined API Service  # Title of the service in the API catalog
-     description: Sample to demonstrate how to add an API service with Swagger to API Catalog using a static YAML definition  # Description of the service in the API catalog
-     instanceBaseUrls:  # list of base URLs for each instance
-         - https://sys1:{gatewayPort}/  # scheme://hostname:port/contextPath
-     homePageRelativeUrl: / # Normally used for informational purposes for other services to use it as a landing page
-     statusPageRelativeUrl: /application/info  # Appended to the instanceBaseUrl
-     healthCheckRelativeUrl: /application/health  # Appended to the instanceBaseUrl
-     routes:
-         - gatewayUrl: api/v1  # [api/ui/ws]/v{majorVersion}
-           serviceRelativeUrl: /api/v1 # relativePath that is added to baseUrl of an instance
-         - gatewayUrl: ui/v1
-           serviceRelativeUrl: /
-         - gatewayUrl: ws/v1
-           serviceRelativeUrl: /ws
-     # List of APIs provided by the service (currently only one is supported):
-     apiInfo:
-         - apiId: zowe.apiml.gateway
-           gatewayUrl: api/v1
-           swaggerUrl: https://sys1:{discoverableClientPort}/discoverableclient/v2/api-docs
-     customMetadata:
-         apiml:
-             service.apimlId: apiml1
-             okToRetryOnAllOperations: true
-
-
-   - serviceId: GATEWAY  # unique lowercase ID of the service
-     catalogUiTileId: static  # ID of the API Catalog UI tile (visual grouping of the services)
-     title: Statically Defined API Service  # Title of the service in the API catalog
-     description: Sample to demonstrate how to add an API service with Swagger to API Catalog using a static YAML definition  # Description of the service in the API catalog
-     instanceBaseUrls:  # list of base URLs for each instance
-         - https://sys2:{gatewayPort}/  # scheme://hostname:port/contextPath
-     homePageRelativeUrl: / # Normally used for informational purposes for other services to use it as a landing page
-     statusPageRelativeUrl: /application/info  # Appended to the instanceBaseUrl
-     healthCheckRelativeUrl: /application/health  # Appended to the instanceBaseUrl
-     routes:
-         - gatewayUrl: api/v1  # [api/ui/ws]/v{majorVersion}
-           serviceRelativeUrl: /api/v1 # relativePath that is added to baseUrl of an instance
-         - gatewayUrl: ui/v1
-           serviceRelativeUrl: /
-         - gatewayUrl: ws/v1
-           serviceRelativeUrl: /ws
-     # List of APIs provided by the service (currently only one is supported):
-     apiInfo:
-         - apiId: zowe.apiml.gateway
-           gatewayUrl: api/v1
-           swaggerUrl: https://sys2:{discoverableClientPort}/discoverableclient/v2/api-docs
-     customMetadata:
-         apiml:
-             service.apimlId: apiml2
-             okToRetryOnAllOperations: true
-
-
-# List of tiles that can be used by services defined in the YAML file:
-catalogUiTiles:
-   static:
-       title: Static API Services
-       description: Services which demonstrate how to make an API service discoverable in the APIML ecosystem using YAML definitions
-
-```
-</details>
 
 ## Troubleshooting multitenancy configuration