From 04e4edc50f6cadae8eac6a4a2545d9987fb9ff86 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Wed, 20 Dec 2023 14:26:08 +0100 Subject: [PATCH] refactor steps Signed-off-by: Andrew Jandacek --- .../authentication-for-apiml-services.md | 47 ++++++++++++------- 1 file changed, 31 insertions(+), 16 deletions(-) diff --git a/docs/extend/extend-apiml/authentication-for-apiml-services.md b/docs/extend/extend-apiml/authentication-for-apiml-services.md index bd72872a82..74cd12a38b 100644 --- a/docs/extend/extend-apiml/authentication-for-apiml-services.md +++ b/docs/extend/extend-apiml/authentication-for-apiml-services.md @@ -105,22 +105,29 @@ with each authentication provider. The client can authenticate via Username and password. There are multiple methods which can be used to deliver credentials. For more details, see the ZAAS Client documentation. -### Authentication with Client certificate +### Authenticate with Client certificate -It is possible to perform authentication with client certificates. There is a limitation with respect to the ACF2 systems. If you would like to offer feedback using client certificate authentication, please create an issue against the api-layer repository. +You can perform authentication with client certificates. -If the keyring or a truststore contains at least one valid certificate authority (CA) other than the CA of API ML, it is possible to use the client certificates issued by this CA to authenticate to API ML. This feature is not enabled by default and needs to be configured. +If the keyring or a truststore contains at least one valid certificate authority (CA) other than the CA of API ML, it is possible to use the client certificates issued by this CA to authenticate to API ML. This feature is not enabled by default and must be configured. -When providing credentials in any form together with a client certificate on the same login request, the credentials take precedence and the client certificate is ignored. +:::note +There is a limitation with respect to ACF2 systems. If you would like to offer feedback using client +certificate authentication, please create an issue against the api-layer repository. +::: + +When providing credentials with a client certificate on the same login request, the credentials take precedence and the client certificate is ignored. -Authentication against any endpoint is performed in the following way: +### How the Gateway resolves authentication + +The Gateway resolves authetication by authenticating against an endpoint through the following process: * The client calls the service endpoint through API ML Gateway with the client certificate. * The client certificate and private key are checked as a valid TLS client certificate against the trusted CAs of the Gateway. -* The public part of the provided client certificate is checked against SAF. SAF subsequently returns a user ID that owns this certificate. ZSS provides this API for API ML. +* The public part of the provided client certificate is checked against SAF. SAF subsequently returns a user ID that owns this certificate. ZSS provides this API for API ML. * The Gateway performs the login of the mapped user and provides valid authentication to the southbound service. -Authentication via the login endpoint is performed in the following way: +The Gateway resolves authentication via the login endpoint through the following process: * The client calls the API ML Gateway login endpoint with the client certificate. * The client certificate and private key are checked as a valid TLS client certificate against the trusted CAs of the Gateway. @@ -129,40 +136,48 @@ Authentication via the login endpoint is performed in the following way: ![Zowe client certificate authentication diagram](../../images/api-mediation/zowe-client-cert-auth.png) -### Procedure to authenticate with client certificates - -Follow these steps to authenticate with client certificates: +### Prerequisites 1. Specify the Zowe runtime user and set your protection by password. 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 PASSWORD()` 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 member of the default `IZUUSER` group.) + + :::note -Ensure that you have an external Certificate Authority and signed client certificates. Alternatively, you can generate these certificates in SAF. The client certificate has to have correct `Extended Key Usage` metadata so these metadate can be used for TLS client authentication. (`OID: 1.3.6.1.5.5.7.3.2`) +Ensure that you have an external Certificate Authority and signed client certificates. Alternatively, you can generate these certificates in SAF. The client certificate must have correct `Extended Key Usage` metadata so the metadate can be used for TLS client authentication. (`OID: 1.3.6.1.5.5.7.3.2`) ::: -3. Import the client certificates to SAF, or add them to a user profile. +### Configure your z/OS system to support client certificate authentication + +1. Import the client certificates to SAF, or add them to a user profile. **Examples:** `RACDCERT ADD` or `RACDCERT GENCERT`. For more information, see your security system documentation. -4. Import the external CA to the truststore or keyring of the API Mediation Layer. -5. [Configure the Gateway for client certificate authentication](../../user-guide/api-mediation/api-gateway-configuration/#gateway-client-certificate-authentication). +2. Import the external CA to the truststore or keyring of the API Mediation Layer. +3. [Configure the Gateway for client certificate authentication](../../user-guide/api-mediation/api-gateway-configuration/#gateway-client-certificate-authentication). :::note**Notes:** * PassTicket generation must be enabled for the Zowe runtime user. The user has to be able to generate a PassTicket for itself and for the APPLID of z/OSMF. For more information, see [Configure Passticket](#authentication-with-passtickets). -* The Zowe runtime user has to be enabled to perform identity mapping in SAF. For more information, see [Additional security rights that need to be granted](../../user-guide/configure-zos-system/#configure-main-Zowe-server-use-identity-mapping). +* The Zowe runtime user must be enabled to perform identity mapping in SAF. For more information, see [Additional security rights that need to be granted](../../user-guide/configure-zos-system/#configure-main-Zowe-server-use-identity-mapping). * ZSS has to be configured to participate in Zowe SSO. For more information, see [Configure components zss](../../appendix/zowe-yaml-configuration/#configure-component-zss). ::: #### Validate the client certificate functionality -To validate that the client certificate functionality works properly, call the login endpoint with the certificate that was setup using the steps in the previous section, _Procedure to authenticate with client certificates_. The following example uses curl, which is generally available on Linux based systems. +To validate that the client certificate functionality works properly, call the login endpoint with the certificate that was setup using the steps in _Configure your z/OS system to support client certificate authentication_. + +Validate using CURL, a command line utility that runs on Linux based systems: **Example:** ``` curl --cert /path/to/cert.pem --key /path/to/key.pem https://api-mediation-layer:7554/gateway/api/v1/login ``` + + ### Authentication with JWT Token