Skip to content

Commit

Permalink
Merge pull request #3692 from zowe/balhar-jakub/client-certificates/i…
Browse files Browse the repository at this point in the history 
…nternal-mapper

Move configuration of certificate to Install section
  • Loading branch information
@janan07
janan07 authored Jun 6, 2024
2 parents 350924b + 9669783 commit 25493e9
Show file tree
Hide file tree
Showing 2 changed files with 89 additions and 69 deletions.
89 changes: 76 additions & 13 deletions docs/user-guide/api-mediation/configuration-client-certificates.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,74 @@
# Enabling single sign on for clients via client certificate configuration


:::info Roles: system programmer, system administrator, security administrator
:::

You can authenticate against API ML onboarded APIs. This functionality is disabled by default. Follow the steps in this article to enable authentication against API ML onboarded APIs.

There are two methods to enable client certificate functionality:
* The original and default method via ZSS
* The newer and recommended method via the internal mapper component of API Mediation Layer
The internal API ML mapper is simpler to configure and provides more functionality than ZSS.

Review this article to learn about the required configuration to authenticate with either method.

For information about the usage of the client certificate when this feature is enabled, see [Authenticating with client certificates](../authenticating-with-client-certificates.md).

## General prerequisites

* Zowe has correct TLS setup
* The external CA used for issuing client certificates to specific users is imported to the truststore or keyring of the API Mediation Layer.

:::caution Important:
* The Zowe runtime user must be enabled to perform identity mapping in SAF. For more information about identity mapping in SAF, see [Configure main Zowe server to use client certificate identity mapping](./configure-zos-system.md#configure-main-zowe-server-to-use-client-certificate-identity-mapping).
:::

## Configure Internal API ML Mapper

Use the following procedure to enable the zowe.yaml file to use a client certificate as the method of authentication for the API Mediation Layer Gateway. Note that the use of the internal API ML mapper is the recommended method.

1. Open the `zowe.yaml` configuration file.
2. Configure the following properties:

* **components.gateway.apiml.security.x509.enabled**
This property is the global feature toggle. Set the value to `true` to enable client certificate functionality.
* **components.gateway.apiml.security.useInternalMapper**
This property is the global feature toggle. Set the value to `true` to enable Internal Mapper

3. Restart Zowe.

## Configure ZSS

For information about configuring ZSS, see [Configure components zss](../appendix/zowe-yaml-configuration.md#configure-component-zss) in the References section of Zowe Docs.

### Prerequisites for ZSS

When using ZSS for authentication, ensure that you satisfy the following prerequisites before you set up client certificate authentication:

1. Set the password for the Zowe runtime user. The user is created with the `NOPASSWORD` parameter by the Zowe installer. It is necessary to change this password.

For RACF, issue the following TSO command:

`ALTUSER <ZOWE_RUNTIME_USER (ZWESVUSR by default)> PASSWORD(<NEWPASSWORD>)`

For other security systems, refer to the documentation for an equivalent command.

2. Verify that the Zowe runtime user is allowed to log in to z/OSMF. (Check that the user is a member of the default `IZUUSER` group.)

:::note
Ensure that you have the Issuer certificate imported in the truststore or in the SAF keyring. Alternatively, you can generate these certificates in SAF.
:::

:::caution Important:
* PassTicket generation must be enabled for the Zowe runtime user. The user must be able to generate a PassTicket for the user and for the APPLID of z/OSMF. For more information, see [Configuring Zowe to use PassTickets](./api-mediation/configuration-extender-passtickets.md#configuring-zowe-to-use-passtickets).
:::

:::tip
There is a limitation with respect to performing authentication using Z Secure Services (ZSS) with ACF2 systems. If you are using ACF2, and are using Zowe v2.14 or a later version, use the recommended internal API ML mapper.
:::

### Enabling zowe.yaml to use a client certificate

Use the following procedure to enable the zowe.yaml file to use a client certificate as the method of authentication for the API Mediation Layer Gateway.

1. Open the `zowe.yaml` configuration file.
Expand All @@ -15,18 +80,16 @@ Use the following procedure to enable the zowe.yaml file to use a client certifi
* **components.gateway.apiml.security.zosmf.applid**
When z/OSMF is used as an authentication provider, provide a valid `APPLID` to allow for client certificate authentication. The API ML generates a passticket for the specified `APPLID` and subsequently uses this passticket to authenticate to z/OSMF. The default value in the installation of z/OSMF is `IZUDFLT`.

:::note
The following steps are only required if the ZSS hostname or default Zowe user name are altered:
:::
:::note
The following steps are only required if the ZSS hostname or default Zowe user name are altered:
:::

3. Change the following property if user mapping is provided by an external API:

* **components.gateway.apiml.security.x509.externalMapperUrl**

:::note
:::note
Skip this step if user mapping is not provided by an external API.
:::

* **components.gateway.apiml.security.x509.externalMapperUrl**
The API Mediation Gateway uses an external API to map a certificate to the owner in SAF. This property informs the Gateway about the location of this API. ZSS is the default API provider in Zowe. 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:
Expand All @@ -37,12 +100,11 @@ Use the following procedure to enable the zowe.yaml file to use a client certifi

4. Add the following property if the Zowe runtime userId is altered from the default `ZWESVUSR`:

:::note
Skip this step if the Zowe runtime userId is not altered from the default `ZWESVUSR`.
:::
:::note
Skip this step if the Zowe runtime userId is not altered from the default `ZWESVUSR`.
:::

* **components.gateway.apiml.security.x509.externalMapperUser**

* **components.gateway.apiml.security.x509.externalMapperUser**
To authenticate to the mapping API, a JWT is sent with the request. The token represents the user that is configured with this property. The 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.

If you customized the `ZWESECUR` JCL or workflow (the customization of zowe runtime user: `// SET ZOWEUSER=ZWESVUSR * userid for Zowe started task`) and changed the default USERID, create the `components.gateway.apiml.security.x509.externalMapperUser` property and set the value by adding a new line as in the following example:
Expand All @@ -55,3 +117,4 @@ Skip this step if the Zowe runtime userId is not altered from the default `ZWESV

5. Restart Zowe.

You enabled zowe.yaml to use a client certificate.
69 changes: 13 additions & 56 deletions docs/user-guide/authenticating-with-client-certificates.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,12 @@
:::info Required roles: system administrator, security administrator
:::

Authentication for integration with API ML can also be performed by the client when the service endpoint is called through the API ML Gateway with client certificates.

:::tip
There is a limitation with respect to performing authentication using Z Secure Services (ZSS) with ACF2 systems. If you are using ACF2, and are using Zowe v2.14 or a later version, use the recommended internal API ML mapper.
:::
Authentication for integration with API Mediation Layer (API ML) can also be performed by the client when the service endpoint is called through
the API ML Gateway with client certificates. Client certification must be enabled and configured. For details about this configuration, see [Enabling single sign on for clients via client certificate configuration](./api-mediation/configuration-client-certificates.md).

:::note Notes:
* When calling the login endpoint with basic authentication credentials as well as with client certificate, the basic authentication credentials take precedence and client certificate is ignored.
* When calling the login endpoint with basic authentication credentials, as well as with client certificate, the basic
authentication credentials take precedence and the client certificate is ignored.

* If you are calling a specific endpoint on one of the onboarded services, API Mediation Layer ignores Basic authentication. In this case, the Basic authentication is not part of the authenticated request.
:::
Expand Down Expand Up @@ -40,36 +38,17 @@ When sending a request to the login endpoint with a client certificate, the Gate
ZSS is currently the default API that provides this mapping between the public part of the client certificate and SAF user ID. Using the internal API ML mapper is, however, the recommended method.
:::

The following diagram shows how routing works with ZSS.

![Zowe client certificate authentication diagram](../images/api-mediation/zowe-client-cert-auth.png)

:::tip
For more information, see the Medium blog post [Zowe client certificate authentication](https://medium.com/zowe/zowe-client-certificate-authentication-5f1c7d4d579).
:::

## Prerequisites when using ZSS

When using ZSS for authentication, ensure that you satisfy the following prerequisites before you set up client certificate authentication. These prerequsites do not apply when using the internal API ML mapper.

1. Set the password for the Zowe runtime user. The user is created with the `NOPASSWORD` parameter by the Zowe installer. It is necessary to change this password.

For RACF, issue the following TSO command:

`ALTUSER <ZOWE_RUNTIME_USER (ZWESVUSR by default)> PASSWORD(<NEWPASSWORD>)`

For other security systems, refer to the documentation for an equivalent command.

2. Verify that the Zowe runtime user is allowed to log in to z/OSMF. (Check that the user is a member of the default `IZUUSER` group.)

:::note
Ensure that you have the Issuer certificate imported in the truststore or in the SAF keyring. Alternatively, you can generate these certificates in SAF.
Ensure that the client certificate has the following `Extended Key Usage` metadata:
`OID: 1.3.6.1.5.5.7.3.2`
This metadata can be used for TLS client authentication.
:::

## Configure your z/OS system to support client certificate authentication
## Configure your z/OS system to support client certificate authentication for a specific user

1. Register the client certificate with the user ID in your ESM. The following commands apply to both the internal API ML mapper and ZSS.
Register the client certificate with the user ID in your ESM. The following commands apply to both the internal API ML mapper and ZSS.

**Example command in RACF:**

Expand All @@ -85,35 +64,13 @@ This metadata can be used for TLS client authentication.

Additional details are likely described in your security system documentation.

2. Import the external CA to the truststore or keyring of the API Mediation Layer.
3. Configure the Gateway for client certificate authentication. Follow the procedure described in [Enabling single sign on for clients via client certificate configuration](./api-mediation/configuration-client-certificates.md).

:::caution Important:
* PassTicket generation must be enabled for the Zowe runtime user. The user must be able to generate a PassTicket for the user and for the APPLID of z/OSMF. For more information, see [Configuring Zowe to use PassTickets](./api-mediation/configuration-extender-passtickets.md#configuring-zowe-to-use-passtickets).

* The Zowe runtime user must be enabled to perform identity mapping in SAF. For more information about identity mapping in SAF, see [Configure main Zowe server to use client certificate identity mapping](./configure-zos-system.md#configure-main-zowe-server-to-use-client-certificate-identity-mapping).
:::

:::note Notes:
* The internal API ML mapper can provide the API for API ML if enabled in the zowe.yaml file. Use of the internal API ML mapper is the recommended method. Note that the mapper feature is available for Zowe release 2.14 and later releases. Alternatively, ZSS can be configured to participate in Zowe SSO.

* Currently, ZSS is the default API that provides this mapping between the public part of the client certificate and the SAF user ID, however the use of the internal API ML mapper is the recommended method.

* For more information about configuring ZSS, see [Configure components zss](../appendix/zowe-yaml-configuration.md#configure-component-zss) in the References section of Zowe Docs.
:::note Notes
* Ensure that you have the Issuer certificate imported in the truststore or in the SAF keyring. Alternatively, you can generate these certificates in SAF.
* Ensure that the client certificate has the following `Extended Key Usage` metadata:
`OID: 1.3.6.1.5.5.7.3.2`
This metadata can be used for TLS client authentication.
:::

### Enabling the internal API ML mapper

To enable the internal API ML mapper, set the following property in zowe.yaml:
```
gateway:
apiml:
security:
useInternalMapper: true
```
Note that the internal API ML mapper option is only available for Zowe release 2.14 and later releases.


## Validate the client certificate functionality

To validate that the client certificate functionality works properly, call the login endpoint with the certificate that was set up using the steps in [Configure your z/OS system to support client certificate authentication](#configure-your-zos-system-to-support-client-certificate-authentication) described previously in this article.
Expand Down

0 comments on commit 25493e9

Please sign in to comment.