Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

language refactor and question re: configuring AT-TLS for Zowe server #4070

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
Open

language refactor and question re: configuring AT-TLS for Zowe server #4070

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
093354f
language refactor and question
janan07 Jan 14, 2025
e6c644e
formatting improvements
janan07 Jan 14, 2025
146c0c1
fix typos. Add question
janan07 Jan 14, 2025
1afd6af
minor fixes
janan07 Jan 14, 2025
edf6f19
fix link
janan07 Jan 15, 2025
cbb5f80
fix typo
janan07 Jan 16, 2025
506fcd2
fix statement per Pavel's comment
janan07 Jan 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 36 additions & 19 deletions docs/user-guide/configuring-at-tls-for-zowe-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
# Configuring AT-TLS for Zowe Server

You can configure parameters in the Zowe server to enable Zowe to work with AT-TLS. Review this article for information about AT-TLS inbound and outbound rules, and the required configuration to use AT-TLS in high availability. You can also find troubleshooting tips as well as security recommendations.
You can configure parameters in the Zowe server to enable Zowe to work with AT-TLS. Review this article for information about how to set AT-TLS inbound and outbound rules, and the required configuration to use AT-TLS in high availability. You can also find troubleshooting tips and security recommendations.

:::info Role: security administrator
:::

## AT-TLS configuration for Zowe

Follow these steps to configure Zowe to support AT-TLS:
In the network section in the Zowe.yaml file, set your inbound and outbound traffic rules to configure Zowe to support AT-TLS. Details about how to set these rules are described in the section [AT-TLS rules](#at-tls-configuration-for-zowe) later in this article.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These section does not configure rules. The rules are configured outside the Zowe. Those configuration values just tell to Zowe if there are some rules and should be used.


**Example yaml:**

```yaml
zowe:
Expand All @@ -22,7 +24,13 @@ zowe:
attls: true
```

While the Zowe Server components do not handle TLS on its own with AT-TLS enabled, the API Mediation Layer (API ML) requires information about the server certificate that is defined in the AT-TLS rule. Ensure that the server certificates provided by the AT-TLS layer are trusted in the configured Zowe keyring. We strongly recommend that AT-TLS be configured with the same Zowe keyring.
When AT-TLS is enabled, the Zowe Server components themselves do not handle TLS. Instead, the API Mediation Layer (API ML) utilizes information about the server certificate that is defined in the AT-TLS rule.

Ensure that the server certificates provided by the AT-TLS layer are trusted in the configured Zowe keyring.

:::tip
We strongly recommend that AT-TLS be configured with the same Zowe keyring.
:::

:::note Notes

Expand All @@ -40,13 +48,13 @@ Outbound AT-TLS rules (i.e. to make a transparent https call through http) that

The Discovery Service endpoints are not reachable by standard API Gateway routing by default.

Zowe v3 includes a new component named ZAAS (Zowe Authentication and Authorization Service). In AT-TLS-aware mode, calls to this service are all internal between API ML components. These must include the X.509 Client Certificate.
Zowe v3 includes Zowe Authentication and Authorization Service (ZAAS). In AT-TLS-aware mode, calls to the ZAAS service are all internal between API ML components and must include the X.509 Client Certificate.
:::

### Limitations

If using AT-TLS with a z/OS Keyring backed by an ICSF hardware module, the only supported configuration is Zowe with z/OSMF authentication provider in JWT mode.
A LTPA token and SAF provider cannot be used in this configuration because API ML cannot access the hardware key to sign its own tokens.
If using AT-TLS with a z/OS Keyring backed by an ICSF hardware module, ensure that your Zowe configuration utilizes the z/OSMF authentication provider in JWT mode.
A LTPA token and SAF provider cannot be used in this configuration as API ML cannot access the hardware key to sign its own tokens.
Personal Access Tokens (PAT) are not supported in this configuration because API ML cannot access the hardware key to sign the tokens.

## AT-TLS rules
Expand Down Expand Up @@ -104,8 +112,9 @@ TTLSKeyringParms ZoweKeyring
Keyring ZWEKRNG
}
```
<!--Can we provide a list of all parameters that need to be set in the previous example with the definitions of those parameters? -->
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess we shouldn't make a replacement of IBM documentation: https://www.ibm.com/docs/en/zos/3.1.0?topic=applications-tls-policy-statements


The `PortRange` of this inbound rule is taken from the list of API Mediation Layer components in the `zowe.yaml` file. The `PortRange` should cover the following components:
Assign the `PortRange` of this inbound rule based on the list of API Mediation Layer components in the `zowe.yaml` file. Ensure that the `PortRange` covers the following components:

| Component | Default Port |
|----|-----------------------|
Expand All @@ -119,11 +128,17 @@ The `PortRange` of this inbound rule is taken from the list of API Mediation Lay

**Follow this step:**

Replace `ZoweKeyring` with the keyring configured for your installation. Follow [the SAF keyring instructions](../getting-started/zowe-certificates-overview.md#saf-keyring) in the article _Zowe Certificates overview_ to configure keyrings for your Zowe instance.
Replace `ZoweKeyring` with the keyring configured for your installation.

To configure keyrings for your Zowe instance, see [Use a z/OS keyring-based keystore with Zowe generated certificates](../user-guide/certificate-configuration-scenarios.md#scenario-3-use-a-zos-keyring-based-keystore-with-zowe-generated-certificates).

Note the setting `HandshakeRole`. This setting applies to core services which authenticate through certificates with each other. This setting allows the API Gateway to receive and accept X.509 client certificates from API Clients.
:::note Notes:

For more granularity in the AT-TLS rules, separate the rules that need to support Client Certificate authentication (Discovery Service, Gateway Service) from the rules that do not need to support Client Certificate authentication(for example a rule covering API Gateway to an onboarded service).
* The setting `HandshakeRole` applies to core services which authenticate through certificates with each other. This setting allows the API Gateway to receive and accept X.509 client certificates from API Clients.

* For more granularity in the AT-TLS rules, separate the rules that need to support Client Certificate authentication (Discovery Service, Gateway Service) from the rules that do not need to support Client Certificate authentication, for example a rule that applies to communication between the API Gateway and an onboarded service.

:::

### Outbound rules

Expand All @@ -146,11 +161,11 @@ TTLSConnectionAction ClientConnectionAction
}
```

#### For z/OSMF
#### Outbound rule for z/OSMF

This example rule covers the connection between the API Gateway and the z/OSMF instance. This connection is made to authenticate users in z/OS.
The following example rule applies to the connection between the API Gateway and the z/OSMF instance. This connection is made to authenticate users in z/OS.

If `zowe.network.client.tls.attls` is `true`, this rule is assumed set. The requests to z/OSMF are issued using `http`.
This rule is set when `zowe.network.client.tls.attls` is set to `true`. The requests to z/OSMF are issued using `http`.

```bash
TTLSRule ApimlZosmfClientRule
Expand Down Expand Up @@ -184,7 +199,7 @@ TTLSEnvironmentAction ApimlClientEnvironmentAction
`Jobname` is defined explicitly for the ZAAS component and is formed with the `zowe.job.prefix` setting from `zowe.yaml` plus `AZ` as the ZAAS identifier.
:::

#### For communication between API Gateway and other core services
#### Outbound rule for communication between API Gateway and other core services

Use the example in this section as a template for internal connections between API Mediation Layer core services.

Expand Down Expand Up @@ -223,12 +238,14 @@ TTLSConnectionAdvancedParms ApimlClientX509ConnAdvParms
}
```

#### For communication between API Gateway and southbound services
#### Outbound rule for communication between API Gateway and southbound services

In this example, the rule covers all outbound connections originating from the API Gateway to an example southbound service listening on port 8080.
This rule applies for Zowe services as well, such as the ZSS and app-server if they are enabled.

This example covers routing scenarios.
The following example covers routing scenarios.

**Example:**

```bash
TTLSRule ApimlServiceClientRule
Expand Down Expand Up @@ -265,7 +282,7 @@ Outbound connections from the Gateway to southbound services (onboarded services

:::

#### Services that validate tokens against the API Mediation Layer
#### Outbound rule for services that validate tokens against the API ML

In this scenario, the services issue a request against the API Gateway to validate the received authentication token.

Expand All @@ -277,8 +294,8 @@ These service also already have an outbound rule set for the onboarding process

Ensure these rules are followed:

- Outbound rule to Discovery Service: Sends X.509 Client Certificate to authorize the onboarding.
- Outbound rule to API Gateway: __Do not__ set a Client Certificate.
- Outbound rule to Discovery Service: Sends X.509 Client Certificate to authorize the onboarding
- Outbound rule to API Gateway: __Do not__ set a Client Certificate

### Ciphers

Expand Down
2 changes: 1 addition & 1 deletion docs/user-guide/mvd-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ The Inbound rules can be filtered by the listening ports of the servers, but Out

The ports and jobnames can be found in the [Addressing network requirements](./address-network-requirements.md) documentation.

The Outbound rules can have HandshakeRole of Client, but when APIML is enabled, it is required that `app-server` and `zss` include their server certificates as client certificates using the `CertificateLabel` property of a `TTLSConnectionAdvancedParms` rule. For more information, see [Configuring AT-TLS for Zowe server](./configuring-at-tls-for-zowe-server.md#for-communication-between-api-gateway-and-other-core-services).
The Outbound rules can have HandshakeRole of Client, but when APIML is enabled, it is required that `app-server` and `zss` include their server certificates as client certificates using the `CertificateLabel` property of a `TTLSConnectionAdvancedParms` rule. For more information, see [Configuring AT-TLS for Zowe server](./configuring-at-tls-for-zowe-server.md#outbound-rule-for-communication-between-api-gateway-and-other-core-services).

The Inbound rules can have a HandshakeRole of Server or ServerWithClientAuth.

Expand Down
Loading