refresh multi tenancy and OIDC doc

docs/diagrams/apiml-oidc-auth-no-mf-id-seq.puml

@@ -0,0 +1,36 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+
+autonumber
+actor User
+actor "User Agent" as Agent
+actor OIDC as OIDC
+actor "API ML GW" as GW
+
+User -> Agent: Do stuff
+Agent -> GW: /gateway/oauth2/authorization/<provider-id>
+GW -> OIDC: Initiate OIDC flow [client_id, client_secret]
+loop [MFA]
+OIDC -> Agent: Request user credentials
+User <-> Agent: Provide credentials
+Agent -> OIDC: Validate credentials
+end
+OIDC --> GW: Return Auth Code / JWTs[access,refresh,identity]
+GW -> Agent: set-cookie access token
+Agent -> GW: Request resources [access token]
+group validate
+GW -> GW: Validate access token
+GW -> OIDC: Validate access token
+end
+alt Validation success
+GW -> GW: Cache access token validity
+GW -> SAF: Map distributed ID to mainframe ID
+SAF -> GW: No mapping exists for distributed ID
+GW -> Service: call API service with OIDC-token
+Service -> Service: Validate access token
+Service --> GW: return Response
+end
+GW --> Agent: Response
+
+
+@enduml

docs/diagrams/apiml-oidc-auth-seq.puml

@@ -4,32 +4,33 @@
 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]
+Agent -> GW: /gateway/oauth2/authorization/<provider-id>
+GW -> OIDC: Initiate OIDC flow [client_id, client_secret]
 loop [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]
+OIDC --> GW: Return Auth Code / JWTs[access,refresh,identity]
+GW -> Agent: set-cookie access token
+Agent -> GW: Request resources [access token]
 group validate
-GW -> GW: Validate AT
-GW -> OIDC: Validate AT
+GW -> GW: Validate access token
+GW -> OIDC: Validate access token
 end
 alt Validation success
-GW -> GW: Cache AT validity
+GW -> GW: Cache access token validity
 GW -> SAF: Map distributed ID to mainframe ID
 GW -> GW: Create Zowe JWT
-GW -> Service: call API service
+GW -> Service: call API service with Zowe JWT
+Service -> Service: Validate JWT
 Service --> GW: return Response
 end
-GW --> Client: Response
-Client --> Agent: Response
+GW --> Agent: Response
+
 
 @enduml

docs/user-guide/api-mediation/api-mediation-multi-tenancy.md

@@ -67,10 +67,7 @@ Use the following example as a template for how to set the value for this proper
 ```
 components.gateway.apiml.service.additionalRegistration:
     # central API ML (in HA, for non-HA mode use only 1 hostname)
-       - discoveryServiceUrls:      https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/
- 	    routes:
-              - gatewayUrl: /
-                serviceUrl: /
+       - discoveryServiceUrls: https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/
 ```
 
 ```
@@ -117,12 +114,9 @@ Use the following example as a template for how to set the value of this propert
 
 **Example:**
 ```
-components.cloud-gateway.apiml.service.additionalRegistration:
-    # central API ML (in HA, for non-HA mode use only 1 hostname)
-       - discoveryServiceUrls:      https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/
- 	    routes:
-              - gatewayUrl: /
-                serviceUrl: /
+components.gateway.apiml.service.additionalRegistration:
+       # central API ML (in HA, for non-HA mode use only 1 hostname)
+       - discoveryServiceUrls: https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/
 ```
 
 #### Dynamic configuration: Environment variables
@@ -133,8 +127,6 @@ The previous example can be substituted with the following variables:
 
 ```
 ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_0_DISCOVERYSERVICEURLS=https://sys1:{discoveryServicePort}/eureka/,https://sys2:{discoveryServicePort}/eureka/
-ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_0_ROUTES_0_GATEWAYURL=/
-ZWE_CONFIGS_APIML_SERVICE_ADDITIONALREGISTRATION_0_ROUTES_0_SERVICEURL=/
 ```
 
 This Zowe configuration transforms the zowe.yaml configuration file into the environment variables described previously. 
@@ -463,81 +455,7 @@ Should contain information about a specific service in a specific domain
 
 Use the `/registry` endpoint to validate successful configuration. The response should contain all Domain 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`.
-
-**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
-
-```
 ## Troubleshooting multitenancy configuration
 
 ### ZWESG100W

docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md

@@ -5,26 +5,23 @@ in isolated sysplex environments. Data from the Central Discovery Service can th
 
 Follow these steps to register with additional Discovery Services:
 
-1. Open the `zowe.yaml` configuration file.
-2. Add the property `components.gateway.apiml.service.additionalRegistration` and set the value to a list of Discovery service clusters to additional Disovery Services.
+1. Open the `zowe.yaml` configuration file.
+2. Add the property `components.gateway.apiml.service.additionalRegistration` and set the value to a list of Discovery service clusters to additional Disovery Services.
 
    **Example:**
    ```
    components.gateway.apiml.service.additionalRegistration: 
        <!-- central APIML -->
        - discoveryServiceUrls: https://sys1:10011/eureka/,https://sys1:10021/eureka/ 
-                    routes:
-                            gatewayUrl: /
-                            serviceUrl: /
      <!-- APIML on System 2 -->
        - discoveryServiceUrls: https://sys2:10011/eureka/,https://sys2:10021/eureka/
-                    routes:
-                            gatewayUrl: /
-                            serviceUrl: /
       <!-- APIML on System 3 -->
        - discoveryServiceUrls: https://sys3:10011/eureka/,https://sys3:10021/eureka/ 
-                    routes:
-                            gatewayUrl: /
-                            serviceUrl: /
     ```
-3. Restart Zowe.
+3. Add property `components.gateway.apimlId` and set the value to a unique string to identify gateway for routing.
+
+   **Example:**
+   ```
+   components.gateway.apimlId: apiml1
+    ```
+4. Restart Zowe.