diff --git a/docs/diagrams/apiml-oidc-auth-seq.puml b/docs/diagrams/apiml-oidc-auth-seq.puml index 4b553ada1e..c151cea9fe 100644 --- 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/ +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 \ No newline at end of file diff --git a/docs/extend/extend-apiml/api-mediation-oidc-authentication.md b/docs/extend/extend-apiml/api-mediation-oidc-authentication.md index 465157b7b9..0f3bfb88c0 100644 --- a/docs/extend/extend-apiml/api-mediation-oidc-authentication.md +++ b/docs/extend/extend-apiml/api-mediation-oidc-authentication.md @@ -3,15 +3,15 @@ :::info Required roles: system administrator, security administrator ::: -The OpenID/Connect ([OIDC](https://openid.net/specs/openid-connect-core-1_0.html)) protocol adds an authentication layer on top of the [OAuth2](https://www.rfc-editor.org/rfc/rfc6749) Authorization protocol. +The OpenID Connect ([OIDC](https://openid.net/specs/openid-connect-core-1_0.html)) protocol adds an identity layer on top of the [OAuth2](https://www.rfc-editor.org/rfc/rfc6749) Authorization protocol. -OIDC authentication, together with the z/OS [Identity Propagation](https://www.redbooks.ibm.com/redbooks/pdfs/sg247850.pdf) mechanism, is the foundation of the API ML Identity Federation. +OIDC authentication, together with the z/OS [Identity Propagation](https://www.redbooks.ibm.com/redbooks/pdfs/sg247850.pdf) mechanism, is the foundation of the API Mediation Layer (API ML) Identity Federation. In this article, OIDC is often referred to as the provider, while the token-related functionality is actually provided by the OAuth2 component of the OIDC implementation. -You can configure Zowe API ML to authenticate users by accepting Access Tokens issued by an external OIDC/OAuth2 provider. +You can configure Zowe API ML to authenticate users by accepting Access Tokens issued by an external OIDC provider. This configuration is useful in advanced deployments of Zowe where client applications need to access mainframe as well as enterprise/distributed systems while simultaneously offering single sign-on (SSO) across system boundaries. -This article details the API ML OIDC authentication functionality, and how to configure the OIDC Authentication feature. +This article details the API ML OIDC authentication functionality, and describes how to configure the OIDC Authentication feature. :::note 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 described in the [API ML OIDC configuration](#api-ml-oidc-configuration) section. @@ -20,49 +20,74 @@ There is a limitation with respect to performing authentication using Z Secure S - [Usage](#usage) - [Authentication flow](#authentication-flow) - [Prerequisites](#prerequisites) - - [OIDC provider](#oidc-provider-prerequisites) - [ESM configuration](#esm-configuration-prerequisites) - [API ML configuration](#api-ml-oidc-configuration) + - [OIDC client configuration](#oidc-client-configuration) + - [OIDC resource server configuration](#oidc-resource-server-configuration) - [Troubleshooting](#troubleshooting) ## Usage - -The OIDC protocol is used by API ML client applications to verify the identity of a user with a distributed OIDC provider trusted by the mainframe security manager. -After successful user login, the OIDC provider grants the client application a JWT Access Token along with an (JWT) Identity Token. -The client application can pass this Access Token with subsequent requests to mainframe services routed through the API ML Gateway. +API ML functions as an OIDC client application, enabling users to initiate the OIDC authentication flow. +After successful user login, the OIDC provider grants the client application a JWT Access Token along with a JWT Identity Token. +The access token is then returned to the user agent in the "apimlAuthenticationToken" cookie. +The user agent can pass this Access Token with subsequent requests to mainframe services routed through the API ML Gateway. The API ML Gateway then validates the OIDC Access Token. If the token is valid, the user identity from that token is mapped to the mainframe identity of the user. -The API ML Gateway can then create mainframe user credentials (JWT or a PassTicket) according to the service's authentication schema configuration. +The API ML Gateway can then create mainframe user credentials (e.g. JWT, PassTicket) according to the service's authentication schema configuration or forward a valid OIDC access token if the user is not mapped. The request is routed to the target API services with correct mainframe user credentials. ## Authentication Flow -The following diagram illustrates the interactions between the participants of the OIDC/OAuth2 based API ML authentication process. +The following diagram illustrates the interactions between the participants of the OIDC based API ML authentication process. ![APIML OIDC Workflow](../../images/api-mediation/apiml-oidc-auth-seq.png) -- When a user wants to access mainframe resources or services using the client application without valid authentication or an access token, the client redirects the user agent to the login end-point of the distributed OIDC provider. -- The user is asked to provide valid credentials (authentication factors). -- After successful validation of all authentication factors, the OIDC provider grants the client an Access Token. -- The client can then request from API ML Gateway the needed mainframe resources presenting the access token in the request. -- The Gateway validates the access token in two ways: - - By comparing the key ID of the token against the key IDs obtained from the authorization server's JWK keys endpoint (`oidc.validationType: JWK` or omited configuration (`oidc.validationType`)). - - By querying the UserInfo endpoint to verify the token's validity and retrieve user information (`oidc.validationType: endpoint`). -- The URL to the specific authorization server's JWK keys endpoint should be set using the property `jwks_uri`. If the access token is validated, the outcome is cached for a short time (20 sec by default). -- The JWK Keys obtained from the authorization server's endpoint are cached for a while to prevent repeated calls to the endpoint. The interval can be set using the property `jwks.refreshInternalHours` (The default value is one hour). -- In subsequent calls with the same token, the Gateway reuses the cached validation outcome. As such, round trips to the OIDC authorization server for JWK keys, UserInfo endpoint queries, and JWT Token validation are not required between short intervals when the client needs to access multiple resources in a row to complete a unit of work. -- The URL to the specific authorization server's UserInfo endpoint should be set using the property `userInfo_uri`. If the access token is validated, the outcome is cached for a short time (20 sec by default). -- The caching interval is configurable with a default value of 20 seconds, which is typically a sufficient amount of time to allow most client operations requiring multiple API requests to complete, while also providing adequate protection against unauthorized access. -- The API ML Gateway fetches the distributed user identity from the distributed access token and maps this user identity to the user mainframe identity using SAF. -- The API ML Gateway calls the requested mainframe service/s with mainframe user credentials (Zowe, SAF JWT, or PassTicket) which are expected by the target mainframe service. +### Workflow description between OICD participants + +1. The user accesses the agent. +2. The user agent requests the client application without valid authentication or an access token. +3. The client redirects the user agent to the login end-point of the distributed OIDC provider. +4. The user is asked to provide valid credentials (authentication factors). +5. The user provides credentials. +6. The agent sends these credentials to the OIDC provider for validation. +7. After successful validation of all authentication factors, the OIDC provider grants the client an Access Token. +8. The client application replies with an access token in the `set-cookie` header. +9. The user agent can then request from API ML Gateway the needed mainframe resources presenting the access token in the request. +10. The Gateway validates the access token in one of two ways: + 1. By cryptographically validating the token using the public key retrieved from the authorization server's JSON Web Key Set (JWKS) endpoint, matching the token's key ID with the key IDs provided. (`components.gateway.apiml.security.oidc.validationType: JWK`). + + **Notes:** + * The URL to the specific authorization server's JWKS endpoint should be set using the property `components.gateway.apiml.security.oidc.jwks.uri`. + + * The interval can be set using the property `components.gateway.apiml.security.oidc.jwks.refreshInternalHours`. (The default value is one hour.) + + 2. By querying the `UserInfo` endpoint to verify the token's validity and retrieve user information (`components.gateway.apiml.security.oidc.validationType: endpoint`). + + **Note:** The URL to the specific authorization server's `UserInfo` endpoint should be set using the property `components.gateway.apiml.security.oidc.userInfo.uri`. +11. The Gateway caches the valid access token. +12. The Gateway maps the distributed identity from the access token to the z/OS identity. + +**When user mapping exists** + +13. The API ML Gateway generates mainframe user credentials (Zowe JWT, SAF IDT, or PassTicket) which are expected by the target mainframe service. +14. Calls the API with credentials. +15. Services validates generated mainframe credentials. +16. The requested data is returned. +17. The requested data is returned to the user agent. + +**When user mapping does not exist** + +14. The API ML Gateway calls the requested mainframe service/s with the access token in the `OIDC-token` header. +15. The service validates the `OIDC-token`. +16. The requested data is returned. +17. The requested data is returned to the user agent. ## Prerequisites Ensure that the following prerequisites are met: - Users who require access to mainframe resources using OIDC authentication have a mainframe identity managed by SAF/ESM. -- Client application users have their distributed identity managed by the OIDC provider. For details, see the section [OIDC provider](#oidc-provider-prerequisites) in this topic. - SAF/ESM is configured with mapping between the mainframe and distributed user identities. For details, see the section [ESM configuration](#esm-configuration-prerequisites) in this topic. -- If you are using Zowe release 2.14 or a later release, ensure that the API ML Gateway is configured to use the internal mapper functionality. For information about enabling the API ML mapper, see [Configure internal API ML mapper](../../user-guide/api-mediation/configuration-client-certificates.md#configure-internal-api-ml-mapper). Alternatively, enable ZSS in the Zowe installation, however using the internal mapper is the recommended method. ZSS is enabled by default. +- If you are using Zowe release 2.14 or a later release, ensure that the API ML Gateway is configured to use the internal mapper functionality. For information about enabling the API ML mapper, see [Configure internal API ML mapper](../../user-guide/api-mediation/configuration-client-certificates.md#configure-internal-api-ml-mapper). Alternatively, enable ZSS in the Zowe installation, however using the internal mapper is the recommended method. ZSS is enabled by default. ### OIDC provider prerequisites @@ -84,8 +109,8 @@ For example, web applications with a secure server side component can use `code The user identity mapping is defined as a distributed user identity mapping filter, which is maintained by the System Authorization Facility (SAF) / External Security Manager (ESM). A distributed identity consists of two parts: -- A distributed identity name -- A trusted registry which governs that identity +1. A distributed identity name +2. A trusted registry which governs that identity Administrators can use the installed ESM functionality to create, delete, list, and query a distributed identity mapping filter or filters. @@ -151,27 +176,80 @@ For more details about mapping a distributed identity username and a distributed #### Parameters in the ESM commands -- **`userid`** - Specifies the ESM user id -- **`distributed-identity-user-name`** - Specifies the user ID for distributed-identity-registry -- **`distributed-identity-registry-name`** - Specifies the URL value of the distributed-identity-registry where user is defined -- **`label-name`** - Specifies the name for the distributed-identity mapping filter +- **userid** + Specifies the ESM user id. +- **distributed-identity-user-name** + Specifies the user ID for distributed-identity-registry. +- **distributed-identity-registry-name** + Specifies the registry value under which the user is defined in the ESM. +- **label-name** + Specifies the name for the distributed-identity mapping filter. **Example for RACF:** ```markup - RACMAP ID(ab00001) MAP USERDIDFILTER(NAME('aaa.bbb@richradioham.com')) REGISTRY(NAME('ldaps://us.richradioham.com')) WITHLABEL('identity mapping for ab00001') + RACMAP ID(ab00001) MAP USERDIDFILTER(NAME('aaa.bbb@richradioham.com')) REGISTRY(NAME('zowe.org')) WITHLABEL('identity mapping for ab00001') ``` Alternatively, API ML provides a Zowe CLI plug-in to help administrators generate a JCL for creating the mapping filter specific for the ESM installed on the target mainframe system. These JCLs can be submitted on the corresponding ESM to create a distributed identity mapping filter. -For details about how to use the plug-in tool to set up mapping in the ESM of your z/OS system, see the [Identity Federation cli plug-in](../../user-guide/cli-idfplugin.md) documentation. +For details about how to use the plug-in tool to set up mapping in the ESM of your z/OS system, see the [Identity Federation CLI plug-in](../../user-guide/cli-idfplugin.md) documentation. ## API ML OIDC configuration +### OIDC client configuration + +The Gateway service can be configured to provide OIDC client functionality and initiate the OIDC authentication flow to obtain an access token. Provide the following configuration in your zowe.yaml file: + +```yaml +components: + gateway: + spring: + security: + oauth2: + client: + registration: + : + issuer: + clientId: + clientSecret: + provider: + : + authorizationUri: /v1/authorize + tokenUri: /v1/token + userInfoUri: /v1/userinfo + userNameAttribute: sub + jwkSetUri: /v1/keys + + +``` +- **provider-id** + The ID of the Identity provider. Currently supported options are `okta` and `entra`. +- **components.gateway.spring.security.oauth2.client.registration.\.issuer** + The URL of the Token issuer. + Example: `https://dev-okta.com/oauth2`. +- **components.gateway.spring.security.oauth2.client.registration.\.clientId** + The Client application ID. +- **components.gateway.spring.security.oauth2.client.registration.\.clientSecret** + The Client application secret. +- **components.gateway.spring.security.oauth2.client.provider.\.authorizationUri** + The URL for the authorization request. +- **components.gateway.spring.security.oauth2.client.provider.\.tokenUri** + The URL to obtain the token. +- **components.gateway.spring.security.oauth2.client.provider.\.userInfoUri** + The URL to retrieve user information. +- **components.gateway.spring.security.oauth2.client.provider.\.userNameAttribute** + The JWT attribute to locate the user ID. +- **components.gateway.spring.security.oauth2.client.provider.\.jwkSetUri** + The URL to retrieve the JSON Web Key Set. + + +:::tip +Consult your OIDC provider documentation for options and requirements available for your type of client application. +::: + +### OIDC resource server configuration + Use the following procedure to enable the feature to use an OIDC Access Token as the method of authentication for the API Mediation Layer Gateway. :::tip @@ -183,42 +261,39 @@ For more information about the Zowe CLI Identity Federation Plug-in, see the [RE In the zowe.yaml file, configure the following properties: -- **`components.gateway.apiml.security.oidc.enabled`** - Specifies the global feature toggle. Set the value to `true` to enable OIDC authentication functionality. +- **components.gateway.apiml.security.oidc.enabled** + Set the value to `true` to enable OIDC resource server functionality for authentication. -- **`components.gateway.apiml.security.oidc.registry`** - Specifies the SAF registry used to group the identities recognized as having OIDC identity mapping. The registry name is the string used during the creation of the mapping between the dustributed and mainframe user identities. For more information, see the [ESM configuration](#esm-configuration-prerequisites). +- **components.gateway.apiml.security.oidc.registry** + Specifies the SAF registry used to group the identities recognized as having 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 **distributed-identity-registry-name** value used in the [ESM configuration](#esm-configuration-prerequisites). -- **`components.gateway.apiml.security.oidc.validationType`** +- **components.gateway.apiml.security.oidc.validationType** Specifies the validation type for OIDC authentication functionality, which is set to `JWK` by default. To enable access token validation using a remote endpoint, set this property to `endpoint`. When set to `endpoint`, the Gateway uses the URI sepecified in the property `userInfo` to validate access tokens. - -- **`components.gateway.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. - -- **`components.gateway.apiml.security.oidc.userInfo.uri`** - Specifies the URI obtained from the authorization server's metadata where the Gateway queries the userInfo endpoint for access token validation. - To enable this property, ensure that `oidc.enabled` is set to `true` and `oidc.validationType` is set to `endpoint`. - -- **`components.gateway.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. - -- **`components.gateway.apiml.security.oidc.jwks.refreshInternalHours`** - Specifies the frequency in hours to refresh the JWK keys from the OIDC provider. Defaults to one hour. - -- **`components.gateway.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`** - 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/api-mediation/configuration-client-certificates.md#configure-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 - ``` + - For `endpoint` validation type, configure following options + - **components.gateway.apiml.security.oidc.userInfo.uri** + Specifies the URI obtained from the authorization server's metadata where the Gateway queries the userInfo endpoint for access token validation. + + - For `JWK` validation type, configure following options + - **components.gateway.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. + - **components.gateway.apiml.security.oidc.jwks.refreshInternalHours** + (Optional) Specifies the frequency in hours to refresh the JWK keys from the OIDC provider. Defaults to one hour. + +**Example for OKTA:** + +```yaml +components: + gateway: + apiml: + security: + oidc: + enabled: true + registry: zowe.org + validationType: JWK + jwks: + uri: https://okta.com/oauth2/api/v1/keys +``` ## Troubleshooting ### API ML fails to validate the OIDC access token with the Distributed Identity Provider diff --git a/docs/extend/extend-apiml/custom-metadata.md b/docs/extend/extend-apiml/custom-metadata.md index 9a74817a1a..8fb7ab0c02 100644 --- 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/extend-apiml/onboard-spring-boot-enabler.md b/docs/extend/extend-apiml/onboard-spring-boot-enabler.md index 33096061cf..b7103c672e 100644 --- a/docs/extend/extend-apiml/onboard-spring-boot-enabler.md +++ b/docs/extend/extend-apiml/onboard-spring-boot-enabler.md @@ -95,45 +95,15 @@ Use the following procedure to use _Gradle_ as your build automation system. Use the corresponding artifact according to the Zowe APIML version you are using. - - For Zowe APIML versions greater than 1.23.5 use the following artifact: + - Use the latest version of the following artifact: ```groovy implementation "org.zowe.apiml.sdk:onboarding-enabler-spring:$zoweApimlVersion" ``` - - For Zowe APIML version 1.23.5 use the following artifact: - - ```groovy - implementation "org.zowe.apiml.sdk:onboarding-enabler-spring-v2-springboot-2.3.12.RELEASE:$zoweApimlVersion" - ``` - - - For Zowe APIML versions 1.22.3, 1.22.4, and 1.23.0 - 1.23.4 use the following artifact: - - ```groovy - implementation "org.zowe.apiml.sdk:onboarding-enabler-spring-v2-springboot-2.3.11.RELEASE:$zoweApimlVersion" - ``` - - - For Zowe APIML versions 1.21.6 - 1.21.13 and 1.22.0 - 1.22.2 use the following artifact: - - ```groovy - implementation "org.zowe.apiml.sdk:onboarding-enabler-spring-v2-springboot-2.3.9.RELEASE:$zoweApimlVersion" - ``` - - - For Zowe APIML versions earlier than 1.21.6 that use Spring 2.1.1 use the following artifact: - - ```groovy - implementation "org.zowe.apiml.sdk:onboarding-enabler-spring-v2-springboot-2.1.1.RELEASE:$zoweApimlVersion" - ``` - - - For Zowe APIML versions earlier than 1.21.6 that use Spring 1.5.9 use the following artifact: - - ```groovy - implementation "org.zowe.apiml.sdk:onboarding-enabler-spring-v1-springboot-1.5.9.RELEASE:$zoweApimlVersion" - ``` - **Notes:** * You may need to add additional dependencies as required by your service implementation. - * The information provided in this file is valid for `ZoweApimlVersion 1.3.0` and above. + * Replace `zoweApimlVersion` with the latest update of the major version according to your Zowe installation. 5. In your project home directory, run the `gradle clean build` command to build your project. Alternatively, you can run `gradlew` to use the specific gradle version that is working with your project. @@ -161,7 +131,7 @@ Use the following procedure if you use _Maven_ as your build automation system. 2. Add the proper dependencies - - For Zowe APIML versions greater than 1.23.5 use the following artifact: + - Use the latest version of the following artifact: ```XML @@ -170,56 +140,9 @@ Use the following procedure if you use _Maven_ as your build automation system. $zoweApimlVersion ``` + **Notes:** + * Replace `zoweApimlVersion` with the latest update of the major version according to your Zowe installation. - - For Zowe APIML version 1.23.5 use the following artifact: - - ```XML - - org.zowe.apiml.sdk - onboarding-enabler-spring-v2-springboot-2.3.12.RELEASE - $zoweApimlVersion - - ``` - - - For Zowe APIML versions 1.22.3, 1.22.4, and 1.23.0 - 1.23.4 use the following artifact: - - ```XML - - org.zowe.apiml.sdk - onboarding-enabler-spring-v2-springboot-2.3.11.RELEASE - $zoweApimlVersion - - ``` - - - For Zowe APIML versions 1.21.6 - 1.21.13 and 1.22.0 - 1.22.2 use the following artifact: - - ```XML - - org.zowe.apiml.sdk - onboarding-enabler-spring-v2-springboot-2.3.9.RELEASE - $zoweApimlVersion - - ``` - - - For Zowe APIML versions earlier than 1.21.6 that use Spring 2.1.1 use the following artifact: - - ```XML - - org.zowe.apiml.sdk - onboarding-enabler-spring-v2-springboot-2.1.1.RELEASE - $zoweApimlVersion - - ``` - - - For Zowe APIML versions earlier than 1.21.6 that use Spring 1.5.9 use the following artifact: - - ```XML - - org.zowe.apiml.sdk - onboarding-enabler-spring-v1-springboot-1.5.9.RELEASE - $zoweApimlVersion - - ``` 3. In the directory of your project, run the `mvn clean package` command to build the project. @@ -374,12 +297,12 @@ apiml: - apiId: zowe.apiml.sampleservice version: 1.0.0 gatewayUrl: api/v1 - swaggerUrl: ${apiml.service.scheme}://${apiml.service.hostname}:${apiml.service.port}${apiml.service.contextPath}/api-doc + swaggerUrl: ${apiml.service.scheme}://${apiml.service.hostname}:${apiml.service.port}${apiml.service.contextPath}/v3/api-docs/apiv1 documentationUrl: https://www.zowe.org - apiId: zowe.apiml.sampleservice version: 2.0.0 gatewayUrl: api/v2 - swaggerUrl: ${apiml.service.scheme}://${apiml.service.hostname}:${apiml.service.port}${apiml.service.contextPath}/api-doc?group=apiv2 + swaggerUrl: ${apiml.service.scheme}://${apiml.service.hostname}:${apiml.service.port}${apiml.service.contextPath}/v3/api-docs/apiv2 documentationUrl: https://www.zowe.org catalog: @@ -393,8 +316,8 @@ apiml: ## This part configures the http client that connects to Discovery Service. You might reuse your server.ssl.xxx properties that configure your application's servlet. enabled: true verifySslCertificatesOfServices: true - protocol: TLSv1.2 - enabled-protocols: TLSv1.2 + protocol: TLSv1.3 + enabled-protocols: TLSv1.3 keyStoreType: ${fill.your.keystoretype} trustStoreType: ${fill.your.truststoretype} @@ -495,92 +418,89 @@ Use the following procedure to add Swagger API documentation to your project. * For _Gradle_, add the following dependency in `build.gradle`: ```groovy - compile "io.springfox:springfox-swagger2:2.9.2" + implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.2' ``` - * For _Maven_, add the following dependency in `pom.xml`: + * For _Maven_, add the following dependency in `pom.xml`: - ```xml - - io.springfox - springfox-swagger2 - 2.9.2 - - ``` + ```xml + + org.springdoc + springdoc-openapi-starter-webmvc-ui + 2.8.2 + + ``` 2. Add a Spring configuration class to your project. **Example:** ```java - package org.zowe.apiml.sampleservice.configuration; + package org.zowe.apiml.sampleservice.configuration; + + import io.swagger.v3.oas.models.Components; + import io.swagger.v3.oas.models.OpenAPI; + import io.swagger.v3.oas.models.info.Info; + import io.swagger.v3.oas.models.security.SecurityScheme; + import org.springdoc.core.models.GroupedOpenApi; + import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; - import org.springframework.web.servlet.config.annotation.EnableWebMvc; - import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter; - import springfox.documentation.builders.PathSelectors; - import springfox.documentation.builders.RequestHandlerSelectors; - import springfox.documentation.service.ApiInfo; - import springfox.documentation.service.Contact; - import springfox.documentation.spi.DocumentationType; - import springfox.documentation.spring.web.plugins.Docket; - import springfox.documentation.swagger2.annotations.EnableSwagger2; - - import java.util.ArrayList; - + @Configuration - @EnableSwagger2 - @EnableWebMvc - public class SwaggerConfiguration extends WebMvcConfigurerAdapter { + public class SwaggerConfiguration { + + @Value("${apiml.service.title}") + private String apiTitle; + + @Value("${apiml.service.apiInfo[0].version}") + private String apiVersionRest1; + + @Value("${apiml.service.apiInfo[1].version}") + private String graphqlVersion; + + @Value("${apiml.service.apiInfo[2].version}") + private String apiVersionRest2; + + @Value("${apiml.service.description}") + private String apiDescription; + @Bean - public Docket api() { - return new Docket(DocumentationType.SWAGGER_2) - .select() - .apis(RequestHandlerSelectors.any()) - .paths(PathSelectors.ant("/api/v1/**")) - .build() - .apiInfo(new ApiInfo( - "Spring REST API", - "Example of REST API", - "1.0.0", - null, - null, - null, - null, - new ArrayList<>() - )); + public OpenAPI openAPI() { + return new OpenAPI() + .info(new Info() + .title("Spring REST API") + .description("Example of REST API")) + .components(new Components().addSecuritySchemes("ESM token", + new SecurityScheme().type(SecurityScheme.Type.APIKEY).in(SecurityScheme.In.HEADER).name("esmToken")) + ); } - + + @Bean + public GroupedOpenApi apiV1() { + return GroupedOpenApi.builder() + .group("apiv1") + .pathsToMatch("/api/v1/**") + .addOpenApiCustomizer(openApi -> openApi.setInfo(openApi.getInfo().version("1.0.0"))) + .build(); + } + @Bean - public Docket apiv2() { - return new Docket(DocumentationType.SWAGGER_2) - .groupName("apiv2") - .select() - .apis(RequestHandlerSelectors.any()) - .paths(PathSelectors.ant("/api/v2/**")) - .build() - .apiInfo(new ApiInfo( - "Spring REST API", - "Example of REST API", - "1.0.0", - null, - null, - null, - null, - new ArrayList<>() - )); + public GroupedOpenApi apiV2() { + return GroupedOpenApi.builder() + .group("apiv2") + .pathsToMatch("/api/v2/**") + .addOpenApiCustomizer(openApi -> openApi.setInfo(openApi.getInfo().version("2.0.0"))) + .build(); } + } + ``` 3. Customize this configuration according to your specifications. For more information about customization properties, -see [Springfox documentation](https://springfox.github.io/springfox/docs/snapshot/#configuring-springfox). - -:::note -The current SpringFox Version 2.9.2 does not support OpenAPI 3.0. -For more information about the open feature request see this [issue](https://github.com/springfox/springfox/issues/2022). -::: +see [Springdoc configuration](https://springdoc.org/#properties). ## Validating the discoverability of your API service by the Discovery Service diff --git a/docs/extend/zowe-conformance-program.md b/docs/extend/zowe-conformance-program.md index 4dadd9da08..e75198dcb0 100644 --- 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 index 2c9115d1cd..68ccef5902 100644 --- 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 index b809022d83..f82c7dce72 100644 Binary files a/docs/images/api-mediation/apiml-oidc-auth-seq.png and b/docs/images/api-mediation/apiml-oidc-auth-seq.png differ diff --git a/docs/user-guide/cli-db2-install-m1.md b/docs/user-guide/_cli-db2-install-m1.md similarity index 100% rename from docs/user-guide/cli-db2-install-m1.md rename to docs/user-guide/_cli-db2-install-m1.md diff --git a/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md b/docs/user-guide/api-mediation/api-mediation-multi-tenancy.md index 842f8aad90..794c764ac6 100644 --- 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,15 +129,20 @@ 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: +
+ Click here for an example of keytool commands for PKCS12 certificates. + + 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` + +
- - **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": @@ -145,13 +150,13 @@ The following commands are examples of establishing a trust relationship between Click here for command details for RACF. - **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 Click here for command details for ACF2. - **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 Click here for command details for Top Secret. - **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** + +
+ Click here for example keytool commands for PKCS12 certificates. - 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** +
+ + - **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`. - -
-Click here for a Gateway static definition example. - -**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 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 a58d091713..715ed4a317 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 @@ -8,4 +8,8 @@ As a system programmer, you can customize your configuration for how API ML mana * To change the number of concurrent connections per route passing through the API Gateway, see [Customizing connection limits](./configuration-connection-limits.md). * To change the global Gateway timeout value for the API ML instance, see [Customizing Gateway timeouts](./configuration-gateway-timeouts.md). + + * To change the number of concurrent requests an application should support and its impact on the size of the Java memory heap, see [Customizing Java Heap sizes](./configuration-customizing-java-heap-sizes.md). + + * To customize the rate limit for each service, see [Customizing Gateway rate limiter](./customizing-gateway-rate-limiter.md). diff --git a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md index a78a1152e0..8a76a31ed0 100644 --- a/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md +++ b/docs/user-guide/api-mediation/configuration-multi-tenancy-routing.md @@ -6,27 +6,18 @@ The domain-specific Discovery Service is typically in the same LPAR in a multi-s 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: - discoveryServiceUrls: https://sys1:10011/eureka/,https://sys1:10021/eureka/ - routes: - - gatewayUrl: / - serviceUrl: / - + - discoveryServiceUrls: https://sys2:10011/eureka/,https://sys2:10021/eureka/ - routes: - - gatewayUrl: / - serviceUrl: / - + - discoveryServiceUrls: https://sys3:10011/eureka/,https://sys3:10021/eureka/ - routes: - - gatewayUrl: / - serviceUrl: / ``` :::note @@ -36,7 +27,13 @@ Follow these steps to register with additional Discovery Services: Always provide the direct address to the system. Do not use the DVIPA address. Using this address could lead to unexpected behaviour. ::: +3. Add property `components.gateway.apimlId` and set the value to a unique string to identify gateway for routing. -3. Restart Zowe. + **Example:** + ```yaml + components.gateway.apimlId: apiml1 + ``` + +4. Restart Zowe. You completed the procedure to register with additional Discovery Services. \ No newline at end of file diff --git a/docs/user-guide/api-mediation/configuration-saf-resource-checking.md b/docs/user-guide/api-mediation/configuration-saf-resource-checking.md index e94b50a7bc..d699ed56ac 100644 --- a/docs/user-guide/api-mediation/configuration-saf-resource-checking.md +++ b/docs/user-guide/api-mediation/configuration-saf-resource-checking.md @@ -2,90 +2,89 @@ :::info Roles: system programmer, system administrator, security administrator ::: + You can use various SAF resource providers depending on your use case to handle the SAF authorization check. Follow the procedure in this article that applies to your specific configuration use case. ## SAF Resource Checking Providers -API ML can check for the authorization of the user on certain endpoints. Access to a SAF resource is checked with ESM. +API ML can check for the authorization of the user on certain endpoints. Access to a SAF resource is checked with your External Security Manager (ESM). -Verification of the SAF resource is provided by the following three providers: +Verification of the SAF resource is possible by any of the following three providers: -- **`endpoint`** -This is the highest priority provider, such as a REST endpoint call (ZSS or similar one). This option is disabled by default. In Zowe, ZSS has the API to check for SAF resource authorization. - -- **`native`** -The Native JZOS classes from Java are used to determine SAF resource access. This is the default provider. - -- **`dummy`** -This is the lowest priority provider. This is the dummy implementation and is defined in a file. +- **native** + The Native JZOS classes from Java are used to determine SAF resource access. This is the default provider. + + **Note:** This provider cannot be used off-platform. + +- **endpoint** +The endpoint provider relies on APIs such as through a REST endpoint call (for example ZSS). This option is disabled by default. In Zowe, ZSS provides the API to check for SAF resource authorization. + +- **dummy** +The dummy provider is the lowest priority provider. This is the dummy implementation and is defined in a file. :::note -Verification of the SAF resource uses the first available provider based on the specified priority. The default configuration resolves to the native provider. +Verification of the SAF resource uses the first available provider based on the specified priority. The default configuration resolves to the **native** provider. ::: -You can select a specific provider by specifying the `components.gateway.apiml.security.authorization.provider` key in the `zowe.yaml` file. Use the parameter value to -strictly define a provider. If verification is disabled, select the `endpoint` option. +### Setting the native provider to perform SAF resource check (Default setting) -1. Open the file `zowe.yaml`. -2. Find or add the property `components.gateway.apiml.security.authorization.provider` and set desired value. -3. Restart Zowe. +The Native provider is the easiest approach to use the SAF resource checking feature on the mainframe. -**Examples:** -``` -components.gateway.apiml.security.authorization.endpoint.url: endpoint -``` +1. Open the file `zowe.yaml`. +2. Find or add the following property with the value set as `native`: + ``` + components.gateway.apiml.security.authorization.provider: native + ``` -To configure the `endpoint` provider, add the following additional property: -`components.gateway.apiml.security.authorization.endpoint.enabled: true` +3. Restart Zowe. -`components.gateway.apiml.security.authorization.provider: native` +:::tip +Enable this provider when classes `com.ibm.os390.security.PlatformAccessControl` and `com.ibm.os390.security.PlatformReturned` +are available on the classpath. This approach uses the method described in [Class PlatformAccessControl](https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/com.ibm.java.zsecurity.api.80.doc/com.ibm.os390.security/com/ibm/os390/security/PlatformAccessControl.html?view=kc#checkPermission-java.lang.String-java.lang.String-java.lang.String-int-) in the IBM documentation. +::: -`components.gateway.apiml.security.authorization.provider: dummy` +:::note +Ensure that the version of Java on your system has the same version of classes and method signatures. +::: +### Setting the endpoint provider to perform SAF resouce check -To use the endpoint provider, customize the URL corresponding to the SAF resource authorization. By default, the ZSS API is configured and used. +To use the endpoint provider it is necessary to enable the endpoint property and customize the URL corresponding to the SAF resource authorization. By default, the ZSS API is configured and used. 1. Open the file `zowe.yaml`. -2. Find or add the property `components.gateway.apiml.security.authorization.endpoint.url` and set desired value. - The default value for ZSS API is `https://${ZWE_haInstance_hostname}:${GATEWAY_PORT}/zss/api/v1/saf-auth` +2. Find or add the following properties and their corresponding values: + - `components.gateway.apiml.security.authorization.provider: endpoint` + - `components.gateway.apiml.security.authorization.endpoint.enabled: true` + - (Optional)`components.gateway.apiml.security.authorization.endpoint.url: ` + + When using ZSS, the default value of the property + `components.gateway.apiml.security.authorization.endpoint.url` is `https://:/zss/api/v1/saf-auth` + + - **haInstance_hostname** + Specifies the Zowe instance hostname from the configuration. + - **gateway_port** + Specifies the Gateway port from the configuration. + 3. Restart Zowe. -## REST endpoint call +### Setting the dummy provider to perform SAF resource check -The REST provider calls the external API to retrieve information about access rights. To enable the feature outside of the mainframe, such as when running in Docker, you can use a REST endpoint call using the `GET` method: +Use the Dummy provider for testing purpose outside of the mainframe. -- Method: `GET` -- URL: `{base path}/{userId}/{class}/{entity}/{level}` -- Response: -```json5 - { - "authorized": "{true|false}", - "error": "{true|false}", - "message": "{message}" - } -``` -:::note -For more information about this REST endpoint call, see [ZSS implementation](https://github.com/zowe/zss/blob/master/c/authService.c). -::: +1. Open the file `zowe.yaml`. +2. Find or add the following property with the value `dummy`: + ``` + components.gateway.apiml.security.authorization.provider: dummy + ``` -### Native +3. Restart Zowe. -The Native provider is the easiest approach to use the SAF resource checking feature on the mainframe. +In the folder where the application is running, create the file `saf.yml`. Alternatively, you can create the file `mock-saf.yml` in the test module (root folder). -Enable this provider when classes `com.ibm.os390.security.PlatformAccessControl` and `com.ibm.os390.security.PlatformReturned` -are available on the classpath. This approach uses the following method described in the IBM documentation: [method](https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/com.ibm.java.zsecurity.api.80.doc/com.ibm.os390.security/com/ibm/os390/security/PlatformAccessControl.html?view=kc#checkPermission-java.lang.String-java.lang.String-java.lang.String-int-). - -:::note -Ensure that the version of Java on your system has the same version of classes and method signatures. +:::caution Important: +It is necessary to read the file outside of the JAR. A file (inner or outside) has to exist. ::: -### Dummy implementation - -Use the Dummy provider for testing purpose outside of the mainframe. - -Create the file `saf.yml` and locate it in the folder, where is application running or create file `mock-saf.yml` in the -test module (root folder). The highest priority is to read the file outside of the JAR. A file (inner or outside) has to exist. - The following YAML presents the structure of the file: ```yaml @@ -94,14 +93,19 @@ The following YAML presents the structure of the file: {RESOURCE}: - {UserID} ``` +- **CLASS** + Specifies the name of the SAF class. +- **RESOURCE** + Specifies the name of the SAF resource. :::note Notes -- Classes and resources are mapped into a map, user IDs into a list. -- The load method does not support formatting with dots, such as shown in the following example: +- Classes and resources are mapped into a map with user IDs contained in a list. +- The load method does not support formatting with periods (`.`), such as shown in the following example: + **Example:** `{CLASS}.{RESOURCE}` - Ensure that each element is separated. +- Ensure that each element is separated. - The field `safAccess` is not required to define an empty file without a definition. - Classes and resources cannot be defined without the user ID list. -- When a user has multiple definitions of the same class and resource, only the most privileged access level loads. +- When a user has multiple definitions of the same class and resource only the most privileged access level loads. diff --git a/docs/user-guide/api-mediation/customizing-gateway-rate-limiter.md b/docs/user-guide/api-mediation/customizing-gateway-rate-limiter.md new file mode 100644 index 0000000000..2b919fabaa --- /dev/null +++ b/docs/user-guide/api-mediation/customizing-gateway-rate-limiter.md @@ -0,0 +1,35 @@ +# Customizing Gateway rate limiter + +:::info Role: system programmer +::: + +The API Gateway offers a way to customize the rate limit for each service via a configurable rate limiter, which prevents individual users from overloading the system with excessive requests. Configuring the rate limiter helps ensure that a user's activity does not negatively impact the experience of other users by mitigating the risk of Distributed Denial-of-Service (DDoS) attacks and other automated exploit attempts. + +Use the following procedure to customize the Gateway rate limiter: + +1. In the zowe.yaml, set the following rate limiting properties in api/gateway: + + * **rateLimiterCapacity** + Defines the total number of requests that can be allowed at one time per user. The default value is set to 20. + + * **rateLimiterTokens** + Defines the number of requests that are added to the service’s allowance at regular intervals. This property controls how quickly requests are replenished after being consumed. The default value is set to 20. + + * **rateLimiterRefillDuration** + Sets the time interval (in minutes) at which new requests (or tokens) are added. The default value is set to 1. + +2. Define the services to limit: + + Use `servicesToLimitRequestRate` to specify a list of services to limit. In the following example, this property applies to the API Catalog. + +**Example configuration:** +``` + apiml: + gateway: + rateLimiterCapacity: 35 + rateLimiterTokens: 35 + rateLimiterRefillDuration: 2 + servicesToLimitRequestRate: apicatalog +``` +You configured the properties of the rate limiter for the API Catalog, thereby improving user accessibility and overall system stability. + diff --git a/docs/user-guide/assign-security-permissions-to-users.md b/docs/user-guide/assign-security-permissions-to-users.md index 700ede0f6c..a9d1fa3fb2 100644 --- a/docs/user-guide/assign-security-permissions-to-users.md +++ b/docs/user-guide/assign-security-permissions-to-users.md @@ -46,17 +46,17 @@ command, you do not need to perform the steps described in this section. The TSO groups are executed during the JCL sections of `ZWESECUR`. For more information about the `zwe init security` command, see [zwe init security](../appendix/zwe_server_command_reference/zwe/init/zwe-init-security.md). -| Feature of a Zowe server-side component | Resource class | Resource name | Type of access required | Reason | Actions | -|------------------------------------------------------------|----------------|-----------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Core | FACILITY | `BPX.JOBNAME` | READ | Allow z/OS address spaces for unix processes to be renamed for [ease of identification](./configure-zos-system.md#configure-address-space-job-naming). | This parameter permits the Zowe main server to set the job name. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L353)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L586)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L801) | -| API Mediation Layer certificate mapping | FACILITY | `IRR.RUSERMAP` | READ | **Optional** Allow Zowe to [map an X.509 client certificate to a z/OS identity](./configure-zos-system.md#configure-main-zowe-server-to-use-client-certificate-identity-mapping). | This parameter permits the Zowe main server to use the client certificate mapping service. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L369)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L606)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L811) | -| API Mediation Layer identity mapping | FACILITY | `IRR.IDIDMAP.QUERY` | READ | **Optional** Allow Zowe to [map a distributed identity to a z/OS identity](./configure-zos-system.md#configure-main-zowe-server-to-use-distributed-identity-mapping). | This parameter permits the Zowe main server to use distributed identity mapping service. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L374)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L611)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L815) | -| API Mediation Layer SMF records | FACILITY | `IRR.RAUDITX` | READ | **Optional** Allow API Mediation Layer to issue [SMF 83 records](./api-mediation/api-mediation-smf) about activity of Personal Access Tokens. For more information about configuring MFA, see [Multi-Factor Authentication (MFA)](./address-authentication-requirements/#multi-factor-authentication-mfa) | This parameter permits the Zowe main server to cut SMF records. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L381)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L616)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L820) | -| ZSS (required for API ML certificate and identity mapping) | FACILITY | `BPX.SERVER` + `BPX.DAEMON` | UPDATE | Allow Zowe to run code on behalf of the API requester's TSO user ID. For more information, see [Security Environment Switching](./configure-zos-system.md#configure-security-environment-switching). | This parameter permits the Zowe main server to create a user's security environment. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L333)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L568)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L784) | -| ZSS (required for API ML certificate and identity mapping) | APPL | `OMVSAPPL` | READ | Allow Zowe to run code on behalf of the API requester's TSO user ID. This permission is also required from a requester's TSO user. You can skip this requirement when the resource `OMVSAPPL` in the `APPL` class is not defined. For more information, see [Security Environment Switching](./configure-zos-system.md#configure-security-environment-switching). | This parameter permits the Zowe main server to run the code on behalf of the user. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L347)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L579)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L796) | -| ZSS | FACILITY | `IRR.RADMIN.LISTUSER` | READ | Allow Zowe to obtain information about OMVS segment of the user profile using `LISTUSER` TSO command. | This parameter permits the Zowe main server to obtain information about OMVS segment of the user profile. Run the command that applies to your ESM.
• RACF
• ACF2
• Top Secret | -| ZSS | CSFSERV | `Multiple` | READ | Generate symmetric keys using ICSF that is used by [Zowe Desktop cookies](./configure-zos-system.md#configure-an-icsf-cryptographic-services-environment). | The list of IDs to enable include `CSF1TRD` , `CSF1TRC` , `CSF1SKE` , `CSF1SKD`. The full list of IDs is described in the z/OS Cryptographic Services user guide for your z/OS release level: [2.2](https://www.ibm.com/docs/en/zos/2.2.0?topic=ssl-racf-csfserv-resource-requirements), [2.3](https://www.ibm.com/docs/en/zos/2.3.0?topic=ssl-racf-csfserv-resource-requirements), [2.4](https://www.ibm.com/docs/en/zos/2.4.0?topic=ssl-racf-csfserv-resource-requirements) and [2.5](https://www.ibm.com/docs/en/zos/2.5.0?topic=ssl-racf-csfserv-resource-requirements). | | | | | | -| Cross memory server (ZIS) | FACILITY | `ZWES.IS` | READ | Allow Zowe ZWESLSTC processes to access the Zowe ZIS cross memory server. | This parameter permits the Zowe main server to use ZIS cross memory server. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L329)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L560)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L780) | +| Feature of a Zowe server-side component | Resource class | Resource name | Type of access required | Reason | Actions | +|------------------------------------------------------------|----------------|-----------------------------|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Core | FACILITY | `BPX.JOBNAME` | READ | Allow z/OS address spaces for unix processes to be renamed for [ease of identification](./configure-zos-system.md#configure-address-space-job-naming). | This parameter permits the Zowe main server to set the job name. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L353)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L586)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L801) | +| API Mediation Layer certificate mapping | FACILITY | `IRR.RUSERMAP` | READ | **Optional** Allow Zowe to [map an X.509 client certificate to a z/OS identity](./configure-zos-system.md#configure-main-zowe-server-to-use-client-certificate-identity-mapping). | This parameter permits the Zowe main server to use the client certificate mapping service. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L369)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L606)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L811) | +| API Mediation Layer identity mapping | FACILITY | `IRR.IDIDMAP.QUERY` | READ | **Optional** Allow Zowe to [map a distributed identity to a z/OS identity](./configure-zos-system.md#configure-main-zowe-server-to-use-distributed-identity-mapping). | This parameter permits the Zowe main server to use distributed identity mapping service. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L374)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L611)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L815) | +| API Mediation Layer SMF records | FACILITY | `IRR.RAUDITX` | READ | **Optional** Allow API Mediation Layer to issue [SMF 83 records](./api-mediation/api-mediation-smf) about activity of Personal Access Tokens. For more information about configuring the main Zowe server to issue SMF records, see [Configure the main Zowe server to issue SMF records](./address-authentication-requirements/#configure-the-main-zowe-server-to-issue-smf-records) | This parameter permits the Zowe main server to cut SMF records. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L381)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L616)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L820) | +| ZSS (required for API ML certificate and identity mapping) | FACILITY | `BPX.SERVER` + `BPX.DAEMON` | UPDATE | Allow Zowe to run code on behalf of the API requester's TSO user ID. For more information, see [Security Environment Switching](./configure-zos-system.md#configure-security-environment-switching). | This parameter permits the Zowe main server to create a user's security environment. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L333)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L568)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L784) | +| ZSS (required for API ML certificate and identity mapping) | APPL | `OMVSAPPL` | READ | Allow Zowe to run code on behalf of the API requester's TSO user ID. This permission is also required from a requester's TSO user. You can skip this requirement when the resource `OMVSAPPL` in the `APPL` class is not defined. For more information, see [Security Environment Switching](./configure-zos-system.md#configure-security-environment-switching). | This parameter permits the Zowe main server to run the code on behalf of the user. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L347)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L579)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L796) | +| ZSS | FACILITY | `IRR.RADMIN.LISTUSER` | READ | Allow Zowe to obtain information about OMVS segment of the user profile using `LISTUSER` TSO command. | This parameter permits the Zowe main server to obtain information about OMVS segment of the user profile. Run the command that applies to your ESM.
• RACF
• ACF2
• Top Secret | +| ZSS | CSFSERV | `Multiple` | READ | Generate symmetric keys using ICSF that is used by [Zowe Desktop cookies](./configure-zos-system.md#configure-an-icsf-cryptographic-services-environment). | The list of IDs to enable include `CSF1TRD` , `CSF1TRC` , `CSF1SKE` , `CSF1SKD`. The full list of IDs is described in the z/OS Cryptographic Services user guide for your z/OS release level: [2.2](https://www.ibm.com/docs/en/zos/2.2.0?topic=ssl-racf-csfserv-resource-requirements), [2.3](https://www.ibm.com/docs/en/zos/2.3.0?topic=ssl-racf-csfserv-resource-requirements), [2.4](https://www.ibm.com/docs/en/zos/2.4.0?topic=ssl-racf-csfserv-resource-requirements) and [2.5](https://www.ibm.com/docs/en/zos/2.5.0?topic=ssl-racf-csfserv-resource-requirements). | | | | | | +| Cross memory server (ZIS) | FACILITY | `ZWES.IS` | READ | Allow Zowe ZWESLSTC processes to access the Zowe ZIS cross memory server. | This parameter permits the Zowe main server to use ZIS cross memory server. Run the command that applies to your ESM.
• [RACF](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L329)
• [ACF2](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L560)
• [Top Secret](https://github.com/zowe/zowe-install-packaging/blob/79527166f34e28c205c5f60bf4b4bb7b630bc6a1/workflows/templates/ZWESECUR.vtl#L780) | ## Granting users permission to access z/OSMF diff --git a/docs/user-guide/authenticating-with-client-certificates.md b/docs/user-guide/authenticating-with-client-certificates.md index 7c47d9e19d..82ee0ff344 100644 --- a/docs/user-guide/authenticating-with-client-certificates.md +++ b/docs/user-guide/authenticating-with-client-certificates.md @@ -163,3 +163,19 @@ Where: x.509 Client Certificate authentication is correctly configured if the result of the request is HTTP 200 with an `apimlAuthenticationToken` cookie generated. Your Zowe instance is configured to accept x.509 client certificates authentication. + +**Java sample application** + +**Note:** This code sample requires JDK 17 or newer. + +You can find a [Java sample application](https://github.com/zowe/api-layer/blob/v3.x.x/client-cert-auth-sample/src/main/java/org/zowe/apiml/Main.java) in the Zowe API Layer repository. This sample can help you get started with client certificate authentication. + +Replace the following placeholder values in the sample application with your actual configuration: + +```text + API_URL - URL that points to your API ML instance + CLIENT_CERT_PATH - PKCS12 keystore that contains your client certificate + CLIENT_CERT_PASSWORD - keystore password + CLIENT_CERT_ALIAS - client certificate alias + PRIVATE_KEY_ALIAS - client certificate private key alias - usualy is the same value +``` \ No newline at end of file diff --git a/docs/user-guide/cli-db2plugin.md b/docs/user-guide/cli-db2plugin.md index a9b82efd40..1ecd955d37 100644 --- a/docs/user-guide/cli-db2plugin.md +++ b/docs/user-guide/cli-db2plugin.md @@ -4,10 +4,6 @@ The IBM® Db2® Database Plug-in for Zowe™ CLI lets you interact with Db2 Zowe CLI Plug-in for IBM Db2 Database lets you execute SQL statements against a Db2 region, export a Db2 table, and call a stored procedure. The plug-in also exposes its API so that the plug-in can be used directly in other products. -:::note -Although Node.js is required to run Zowe CLI, Node.js V22.0 is not yet supported for this plug-in. -::: - ## Use cases As an application developer, you can use Zowe CLI Plug-in for IBM Db2 Database to perform the following tasks: diff --git a/docs/user-guide/cli-swreqplugins.md b/docs/user-guide/cli-swreqplugins.md index d6dd703be6..2f49838d56 100644 --- a/docs/user-guide/cli-swreqplugins.md +++ b/docs/user-guide/cli-swreqplugins.md @@ -8,7 +8,7 @@ Before installing a Zowe™ CLI plug-in, meet the software requirements to r | Plug-in | Requirements | | --- | --- | | [IBM CICS Plug-in for Zowe CLI](cli-cicsplugin.md) |
  • Ensure that [IBM CICS Transaction Server v5.2 or later](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.home.doc/welcomePage/welcomePage.html) is installed and running in your mainframe environment.
  • [IBM CICS Management Client Interface (CMCI)](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.clientapi.doc/topics/clientapi_overview.html) is configured and running in your CICS region.
| -| [IBM Db2 Database Plug-in for Zowe CLI](cli-db2plugin.md) |
  • [Download and prepare the ODBC driver](../user-guide/cli-db2plugin.md#downloading-the-odbc-driver) (required for only package installations) and address the licensing requirements. _Perform this task before you install the plug-in_.
  • **(MacOS)** Download and Install [Xcode](https://developer.apple.com/xcode/resources/).
  • **Note**: Node.js V22.0 is not yet supported.
| [z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| +| [IBM Db2 Database Plug-in for Zowe CLI](cli-db2plugin.md) |
  • [Download and prepare the ODBC driver](../user-guide/cli-db2plugin.md#downloading-the-odbc-driver) (required for only package installations) and address the licensing requirements. _Perform this task before you install the plug-in_.
  • **(MacOS)** Download and Install [Xcode](https://developer.apple.com/xcode/resources/).
  • **Note**: Linux users might need to resolve an [incompatible glibc version](../troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md#incompatible-glibc-version).
| [z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| | [IBM z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| | [IBM MQ Plug-in for Zowe CLI](cli-mqplugin.md) |
  • Ensure that [IBM® MQ™ v9.1.0](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.1.0/com.ibm.mq.pro.doc/q121910_.htm) or later is installed and running in your mainframe environment. Please read this blog for more information: [Exposing the MQ REST API via the Zowe API Mediation Layer](https://developer.ibm.com/messaging/2019/05/17/exposing-the-mq-rest-api-via-the-zowe-api-mediation-layer/)
| | [Visual Studio Code Extension for Zowe](../user-guide/ze-install.md) |
  • Node.js V8.0 or later
  • Access to z/OSMF; at least one profile is configured
  • Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST interface. For more information, see [z/OS Requirements](../user-guide/systemrequirements-zosmf.md).
| diff --git a/docs/user-guide/configuring-at-tls-for-zowe-server.md b/docs/user-guide/configuring-at-tls-for-zowe-server.md index 8f4e94b399..ee274cfbc3 100644 --- a/docs/user-guide/configuring-at-tls-for-zowe-server.md +++ b/docs/user-guide/configuring-at-tls-for-zowe-server.md @@ -130,6 +130,7 @@ For more granularity in the AT-TLS rules, separate the rules that need to suppor Outbound rules in this section allow Zowe services to communicate with each other and to other southbound services using HTTP. :::caution Important: + Careful consideration needs to be made regarding which rules are to be configured to send a Client Certificate. Since configuration cannot be performed on a per-request basis, it is essential not to configure the rule to send the Zowe Server certificate to the API Gateway or to a southbound service that supports X.509 Client Certificate authentication. Doing so will result in unintentionally authenticating the server ACID. ::: @@ -273,7 +274,7 @@ This scenario includes services that set `zoweJwt` as the authentication scheme, In this case, it is necessary to have an Outbound rule from the service to the API Gateway. -These service also already have an outbound rule set for the onboarding process against the Discovery Service. +These services also already have an outbound rule set for the onboarding process against the Discovery Service. Ensure these rules are followed: diff --git a/docs/user-guide/user-roadmap-zowe-cli.md b/docs/user-guide/user-roadmap-zowe-cli.md index 6bd06cabce..f1a7863aab 100644 --- a/docs/user-guide/user-roadmap-zowe-cli.md +++ b/docs/user-guide/user-roadmap-zowe-cli.md @@ -52,8 +52,20 @@ The Zowe ecosystem is more than a collection of applications and extensions. An - If you have an issue that is specific to Zowe CLI, you can [**submit an issue**](https://github.com/zowe/zowe-cli/issues/new/choose) in the `zowe-cli` 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/) + + Join the #zowe-cli Slack channel to ask questions about Zowe CLI, 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 CLI squad meetings**](https://zoom-lfx.platform.linuxfoundation.org/meetings/zowe) + + Join Zowe CLI squad meetings to get involved. + +- [**Zowe CLI Blogs on Medium**](https://medium.com/zowe/search?q=Zowe%20CLI) + + Read a series of blogs about Zowe CLI 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/user-guide/ze-usage-tips.md b/docs/user-guide/ze-usage-tips.md index 85abe7c2e2..a8e9e3ce60 100644 --- a/docs/user-guide/ze-usage-tips.md +++ b/docs/user-guide/ze-usage-tips.md @@ -4,11 +4,11 @@ Make the best use of Zowe Explorer with the following tips. ## Data sets, USS, and jobs persistence settings -Store any data sets, USS files, or jobs permanently in the **Favorites** tab. Right-click on a data set, USS file, or job and click **Add Favorite**. +You can store any data sets, USS files, or jobs permanently in the **Favorites** tab. Right-click on a data set, USS file, or job and click **Add Favorite**. ## Identify syntax errors with a syntax highlighter -Zowe Explorer supports syntax highlighting for data sets and USS files. To enable syntax highlighting, download a Visual Studio Code extension that provides syntax highlighting. +Zowe Explorer supports a syntax highlighter for data sets. To enhance the experience of using the extension, you can download an extension that highlights syntax. ## Configure the detected language of a file or data set @@ -30,18 +30,20 @@ Manage existing profiles listed in the **Side Bar**. Right-click the profile and ## Delete a profile -Delete a profile displayed in the **Side Bar**. Right-click the profile and select **Manage Profile** in the context menu to see a list of options in the **Quick Pick**. Select **Delete Profile** to open the associated configuration file and manually delete the profile. +:::tip +Alternatively, delete a profile by using the VS Code **Command Palette**. Press `F1` on your keyboard, then select the **Zowe Explorer: Delete a Profile Permanently** option. In Zowe Explorer V1, you select the profile to delete. In Zowe Explorer V2 and above, the configuration file opens for you to delete the profile manually. +::: ## Hide a profile -Hide a profile from the **Side Bar**. Right-click the profile, select the **Manage Profile** option in the context menu, and then click **Hide Profile** in the **Quick Pick**. If necessary, add the profile back by clicking the **+** icon on the **DATA SETS**, **UNIX SYSTEM SERVICES (USS)**, or **JOBS** bar. +Hide a profile from the **Side Bar** by right-clicking the profile and selecting the **Hide Profile** option. If necessary, add the profile back by clicking the **+** icon on the **DATA SETS**, **UNIX SYSTEM SERVICES (USS)**, or **JOBS** bar. -## Multi-select functionality +## Open recent members -Apply an action to multiple objects at the same time for increased efficiency. This is available in actions such as **Copy** (data sets, USS), **Delete**, and **Add to Favorites**. +Zowe Explorer lets you open a list of members you have previously worked on. You can access the list by pressing `Ctrl`+`Alt`+`R` or `Command`+`Option`+`R`. -Use the `Shift` key to select a continuous range of items, or select multiple items by pressing the `Ctrl` key as you select each item. Once the items are selected, right-click to choose the action from the menu. +## Access resources with virtual workspaces -## Open recent members +Use your virtual workspaces to access multiple resources from the **Explorer** view, such as local files or resources from other file systems. -Zowe Explorer lets you open a list of members you have previously worked on. Access the list by pressing `Ctrl`+`Alt`+`R` or `Command`+`Option`+`R`. +In the **Data Sets** or **Unix System Services (USS)** tree, click on a profile **Search** icon. In the **Search** prompt, enter a data set search pattern or a USS file path. Right click on a resource to select the **Add to Workspace** context menu option. The status bar message displays and the selected folder is listed in the **Explorer** view with any other files/resources. diff --git a/docs/whats-new/release-notes/v2_0_0.md b/docs/whats-new/release-notes/v2_0_0.md index 9c62de27ee..24d9d76511 100644 --- a/docs/whats-new/release-notes/v2_0_0.md +++ b/docs/whats-new/release-notes/v2_0_0.md @@ -207,7 +207,7 @@ Zowe CLI contains the following enhancements and changes: Zowe maintained CLI plug-ins are Zowe V2 LTS conformant. As such, they integrate with Team configuration, daemon mode, and the team configuration migration utility. For information about enhancements and bug fixes, see the changelogs for the following plug-ins: -- [IBM CICS Plug-in for Zowe CLI](https://github.com/zowe/cics-for-zowe-client/blob/main/packages/cli/CHANGELOG.md) +- [IBM CICS Plug-in for Zowe CLI](https://github.com/zowe/cics-for-zowe-client/releases) - [IBM Db2 Database Plug-in for Zowe CLI](https://github.com/zowe/zowe-cli-db2-plugin/blob/master/CHANGELOG.md) - [IBM z/OS FTP Plug-in for Zowe CLI](https://github.com/zowe/zowe-cli-ftp-plugin/blob/master/CHANGELOG.md) - [IBM IMS Plug-in for Zowe CLI](https://github.com/zowe/zowe-cli-ims-plugin/blob/master/CHANGELOG.md) @@ -237,7 +237,7 @@ The Nodejs SDK packages were updated to make use of key Zowe V2 features, includ Zowe Explorer makes use of Team Configuration and is secure by default. For information about enhancements and bug fixes, see the following changelogs: - [Zowe Explorer](https://github.com/zowe/zowe-explorer-vscode/blob/next/packages/zowe-explorer/CHANGELOG.md) -- [Zowe Explorer CICS Extension](https://github.com/zowe/cics-for-zowe-client/blob/main/packages/vsce/CHANGELOG.md) +- [Zowe Explorer CICS Extension](https://github.com/zowe/cics-for-zowe-client/releases) - [Zowe Explorer FTP Extension](https://github.com/zowe/zowe-explorer-vscode/blob/next/packages/zowe-explorer-ftp-extension/CHANGELOG.md) ## Bug fixes diff --git a/docs/whats-new/release-notes/v2_16_0.md b/docs/whats-new/release-notes/v2_16_0.md index 3b953e0c80..778fd10214 100644 --- a/docs/whats-new/release-notes/v2_16_0.md +++ b/docs/whats-new/release-notes/v2_16_0.md @@ -33,7 +33,7 @@ System demos are typically held the week after a minor release becomes available ### Zowe API Mediation Layer * The log message `ZWEAM001I` is now issued when API Mediation Layer starts. ([#3523](https://github.com/zowe/api-layer/issues/3523)) -* SSL is now disabled when profile `attls` is active to simplify AT-TLS configuration. ([#3521](https://github.com/zowe/api-layer/issues/3521)) +* SSL is now disabled when profile `attls` is active to simplify AT-TLS configuration. ([#3521](https://github.com/zowe/api-layer/pull/3521)) * Valid OIDC tokens are now forwarded to the downstream service when the distributed ID is not mapped. ([#3497](https://github.com/zowe/api-layer/issues/3497)) * Included OIDC JWKSet in the gateway JWKs. JWKs retrieved from the Identity Provider allow clients and services to validate the OIDC access token locally. ([#3499](https://github.com/zowe/api-layer/issues/3499)) * Moved OIDC access token from cookie to special header. If the user ID from the token cannot be mapped to a mainframe account, the access token is now sent via the request header OIDC-token. ([#3513](https://github.com/zowe/api-layer/issues/3513)) diff --git a/package-lock.json b/package-lock.json index 452c26f725..3dd04a99de 100644 --- a/package-lock.json +++ b/package-lock.json @@ -13149,6 +13149,7 @@ "url": "https://github.com/sponsors/ai" } ], + "license": "MIT", "bin": { "nanoid": "bin/nanoid.cjs" }, diff --git a/sidebars.js b/sidebars.js index d67e9aac01..b85c65cb20 100644 --- a/sidebars.js +++ b/sidebars.js @@ -294,6 +294,7 @@ module.exports = { "items": [ "user-guide/api-mediation/configuration-connection-limits", "user-guide/api-mediation/configuration-gateway-timeouts", + "user-guide/api-mediation/customizing-gateway-rate-limiter", "user-guide/api-mediation/configuration-customizing-java-heap-sizes" ] } @@ -647,14 +648,7 @@ module.exports = { items: [ "user-guide/cli-installplugins", "user-guide/cli-cicsplugin", - { - type: "category", - label: "IBM® Db2® Database Plug-in for Zowe CLI", - link: { type: "doc", id: "user-guide/cli-db2plugin" }, - items: [ - "user-guide/cli-db2-install-m1", - ], - }, + "user-guide/cli-db2plugin", "user-guide/cli-ftpplugin", "user-guide/cli-mqplugin", "user-guide/cli-idfplugin", diff --git a/versioned_docs/version-v2.15.x/user-guide/cli-swreqplugins.md b/versioned_docs/version-v2.15.x/user-guide/cli-swreqplugins.md index 374b20b6e4..ea44f4ec74 100644 --- a/versioned_docs/version-v2.15.x/user-guide/cli-swreqplugins.md +++ b/versioned_docs/version-v2.15.x/user-guide/cli-swreqplugins.md @@ -7,7 +7,7 @@ Before you use Zowe™ CLI plug-ins, complete the following steps: | Plug-in | Required Configurations | | --- | --- | | [IBM CICS Plug-in for Zowe CLI](cli-cicsplugin.md) |
  • Ensure that [IBM CICS Transaction Server v5.2 or later](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.home.doc/welcomePage/welcomePage.html) is installed and running in your mainframe environment
  • [IBM CICS Management Client Interface (CMCI)](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.clientapi.doc/topics/clientapi_overview.html) is configured and running in your CICS region.
| -| [IBM Db2 Database Plug-in for Zowe CLI](cli-db2plugin.md) |
  • [Download and prepare the ODBC driver](../user-guide/cli-db2plugin.md#downloading-the-odbc-driver) (required for only package installations) and address the licensing requirements. _Perform this task before you install the plug-in_.
  • **(MacOS)** Download and Install [Xcode](https://developer.apple.com/xcode/resources/).
| [z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| +| [IBM Db2 Database Plug-in for Zowe CLI](cli-db2plugin.md) |
  • [Download and prepare the ODBC driver](../user-guide/cli-db2plugin.md#downloading-the-odbc-driver) (required for only package installations) and address the licensing requirements. _Perform this task before you install the plug-in_.
  • **(MacOS)** Download and Install [Xcode](https://developer.apple.com/xcode/resources/).
  • **Note:** Linux users might need to resolve an [incompatible glibc version](../troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md#incompatible-glibc-version).
| [z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| | [IBM z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| | [IBM MQ Plug-in for Zowe CLI](cli-mqplugin.md) |
  • Ensure that [IBM® MQ™ v9.1.0](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.1.0/com.ibm.mq.pro.doc/q121910_.htm) or later is installed and running in your mainframe environment. Please read this blog for more information: [Exposing the MQ REST API via the Zowe API Mediation Layer](https://developer.ibm.com/messaging/2019/05/17/exposing-the-mq-rest-api-via-the-zowe-api-mediation-layer/)
| | [Visual Studio Code Extension for Zowe](../user-guide/ze-install.md) |
  • Node.js V8.0 or later
  • Access to z/OSMF; at least one profile is configured
  • Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST interface. For more information, see [z/OS Requirements](../user-guide/systemrequirements-zosmf.md).
| diff --git a/versioned_docs/version-v2.16.x/user-guide/cli-swreqplugins.md b/versioned_docs/version-v2.16.x/user-guide/cli-swreqplugins.md index 374b20b6e4..ea44f4ec74 100644 --- a/versioned_docs/version-v2.16.x/user-guide/cli-swreqplugins.md +++ b/versioned_docs/version-v2.16.x/user-guide/cli-swreqplugins.md @@ -7,7 +7,7 @@ Before you use Zowe™ CLI plug-ins, complete the following steps: | Plug-in | Required Configurations | | --- | --- | | [IBM CICS Plug-in for Zowe CLI](cli-cicsplugin.md) |
  • Ensure that [IBM CICS Transaction Server v5.2 or later](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.home.doc/welcomePage/welcomePage.html) is installed and running in your mainframe environment
  • [IBM CICS Management Client Interface (CMCI)](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.clientapi.doc/topics/clientapi_overview.html) is configured and running in your CICS region.
| -| [IBM Db2 Database Plug-in for Zowe CLI](cli-db2plugin.md) |
  • [Download and prepare the ODBC driver](../user-guide/cli-db2plugin.md#downloading-the-odbc-driver) (required for only package installations) and address the licensing requirements. _Perform this task before you install the plug-in_.
  • **(MacOS)** Download and Install [Xcode](https://developer.apple.com/xcode/resources/).
| [z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| +| [IBM Db2 Database Plug-in for Zowe CLI](cli-db2plugin.md) |
  • [Download and prepare the ODBC driver](../user-guide/cli-db2plugin.md#downloading-the-odbc-driver) (required for only package installations) and address the licensing requirements. _Perform this task before you install the plug-in_.
  • **(MacOS)** Download and Install [Xcode](https://developer.apple.com/xcode/resources/).
  • **Note:** Linux users might need to resolve an [incompatible glibc version](../troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md#incompatible-glibc-version).
| [z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| | [IBM z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| | [IBM MQ Plug-in for Zowe CLI](cli-mqplugin.md) |
  • Ensure that [IBM® MQ™ v9.1.0](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.1.0/com.ibm.mq.pro.doc/q121910_.htm) or later is installed and running in your mainframe environment. Please read this blog for more information: [Exposing the MQ REST API via the Zowe API Mediation Layer](https://developer.ibm.com/messaging/2019/05/17/exposing-the-mq-rest-api-via-the-zowe-api-mediation-layer/)
| | [Visual Studio Code Extension for Zowe](../user-guide/ze-install.md) |
  • Node.js V8.0 or later
  • Access to z/OSMF; at least one profile is configured
  • Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST interface. For more information, see [z/OS Requirements](../user-guide/systemrequirements-zosmf.md).
| diff --git a/versioned_docs/version-v2.17.x/user-guide/cli-swreqplugins.md b/versioned_docs/version-v2.17.x/user-guide/cli-swreqplugins.md index 374b20b6e4..ea44f4ec74 100644 --- a/versioned_docs/version-v2.17.x/user-guide/cli-swreqplugins.md +++ b/versioned_docs/version-v2.17.x/user-guide/cli-swreqplugins.md @@ -7,7 +7,7 @@ Before you use Zowe™ CLI plug-ins, complete the following steps: | Plug-in | Required Configurations | | --- | --- | | [IBM CICS Plug-in for Zowe CLI](cli-cicsplugin.md) |
  • Ensure that [IBM CICS Transaction Server v5.2 or later](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.home.doc/welcomePage/welcomePage.html) is installed and running in your mainframe environment
  • [IBM CICS Management Client Interface (CMCI)](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.clientapi.doc/topics/clientapi_overview.html) is configured and running in your CICS region.
| -| [IBM Db2 Database Plug-in for Zowe CLI](cli-db2plugin.md) |
  • [Download and prepare the ODBC driver](../user-guide/cli-db2plugin.md#downloading-the-odbc-driver) (required for only package installations) and address the licensing requirements. _Perform this task before you install the plug-in_.
  • **(MacOS)** Download and Install [Xcode](https://developer.apple.com/xcode/resources/).
| [z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| +| [IBM Db2 Database Plug-in for Zowe CLI](cli-db2plugin.md) |
  • [Download and prepare the ODBC driver](../user-guide/cli-db2plugin.md#downloading-the-odbc-driver) (required for only package installations) and address the licensing requirements. _Perform this task before you install the plug-in_.
  • **(MacOS)** Download and Install [Xcode](https://developer.apple.com/xcode/resources/).
  • **Note:** Linux users might need to resolve an [incompatible glibc version](../troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md#incompatible-glibc-version).
| [z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| | [IBM z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| | [IBM MQ Plug-in for Zowe CLI](cli-mqplugin.md) |
  • Ensure that [IBM® MQ™ v9.1.0](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.1.0/com.ibm.mq.pro.doc/q121910_.htm) or later is installed and running in your mainframe environment. Please read this blog for more information: [Exposing the MQ REST API via the Zowe API Mediation Layer](https://developer.ibm.com/messaging/2019/05/17/exposing-the-mq-rest-api-via-the-zowe-api-mediation-layer/)
| | [Visual Studio Code Extension for Zowe](../user-guide/ze-install.md) |
  • Node.js V8.0 or later
  • Access to z/OSMF; at least one profile is configured
  • Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST interface. For more information, see [z/OS Requirements](../user-guide/systemrequirements-zosmf.md).
| diff --git a/versioned_docs/version-v2.18.x/user-guide/cli-swreqplugins.md b/versioned_docs/version-v2.18.x/user-guide/cli-swreqplugins.md index 374b20b6e4..8f47de00e9 100644 --- a/versioned_docs/version-v2.18.x/user-guide/cli-swreqplugins.md +++ b/versioned_docs/version-v2.18.x/user-guide/cli-swreqplugins.md @@ -7,11 +7,10 @@ Before you use Zowe™ CLI plug-ins, complete the following steps: | Plug-in | Required Configurations | | --- | --- | | [IBM CICS Plug-in for Zowe CLI](cli-cicsplugin.md) |
  • Ensure that [IBM CICS Transaction Server v5.2 or later](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.home.doc/welcomePage/welcomePage.html) is installed and running in your mainframe environment
  • [IBM CICS Management Client Interface (CMCI)](https://www.ibm.com/support/knowledgecenter/en/SSGMCP_5.2.0/com.ibm.cics.ts.clientapi.doc/topics/clientapi_overview.html) is configured and running in your CICS region.
| -| [IBM Db2 Database Plug-in for Zowe CLI](cli-db2plugin.md) |
  • [Download and prepare the ODBC driver](../user-guide/cli-db2plugin.md#downloading-the-odbc-driver) (required for only package installations) and address the licensing requirements. _Perform this task before you install the plug-in_.
  • **(MacOS)** Download and Install [Xcode](https://developer.apple.com/xcode/resources/).
| [z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| +| [IBM Db2 Database Plug-in for Zowe CLI](cli-db2plugin.md) |
  • [Download and prepare the ODBC driver](../user-guide/cli-db2plugin.md#downloading-the-odbc-driver) (required for only package installations) and address the licensing requirements. _Perform this task before you install the plug-in_.
  • **(MacOS)** Download and Install [Xcode](https://developer.apple.com/xcode/resources/).
  • **Note:** Linux users might need to resolve an [incompatible glibc version](../troubleshoot/cli/troubleshoot-ibm-db2-database-plug-in.md#incompatible-glibc-version).
| [z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| | [IBM z/OS FTP Plug-in for Zowe CLI](cli-ftpplugin.md) |
  • Ensure that z/OS FTP service is enabled and configured with `JESINTERFACELEVEL` = 2.
  • FTP over SSL is recommended.
| | [IBM MQ Plug-in for Zowe CLI](cli-mqplugin.md) |
  • Ensure that [IBM® MQ™ v9.1.0](https://www.ibm.com/support/knowledgecenter/en/SSFKSJ_9.1.0/com.ibm.mq.pro.doc/q121910_.htm) or later is installed and running in your mainframe environment. Please read this blog for more information: [Exposing the MQ REST API via the Zowe API Mediation Layer](https://developer.ibm.com/messaging/2019/05/17/exposing-the-mq-rest-api-via-the-zowe-api-mediation-layer/)
| | [Visual Studio Code Extension for Zowe](../user-guide/ze-install.md) |
  • Node.js V8.0 or later
  • Access to z/OSMF; at least one profile is configured
  • Configure TSO/E address space services, z/OS data set, file REST interface, and z/OS jobs REST interface. For more information, see [z/OS Requirements](../user-guide/systemrequirements-zosmf.md).
| | [IBM IMS Plug-in for Zowe CLI](cli-imsplugin.md)
**DEPRECATED** |
  • **As of Zowe v2.15, the IBM IMS Plug-in has been deprecated. No additional security updates, bug fixes, or enhancements are expected.**
  • Ensure that [IBM® IMS™ v14.1.0](https://www.ibm.com/support/knowledgecenter/en/SSEPH2_14.1.0/com.ibm.ims14.doc/ims_product_landing_v14.html) or later is installed and running in your mainframe environment.
  • Configure [IBM® IMS™ Connect](https://www.ibm.com/support/knowledgecenter/en/SSEPH2_13.1.0/com.ibm.ims13.doc.ccg/ims_ct_intro.html).
  • Configure [IBM IMS Operations APIs](https://github.com/zowe/ims-operations-api) to enable communication between the CLI and the IMS instance.
| - **Important!** You can perform the required configurations for the plug-ins that you want to use ***before*** or ***after*** you install the plug-ins. However, if you do not perform the required configurations, the plug-ins will not function as designed.