Zowe client certificate authentication

Adding capabilities for machine to machine authentication

{Core} With version 1.19 of the Open Mainframe Project’s Zowe, a new exciting feature is rolling out. You guessed it: client certificate authentication is now possible. We are releasing this feature as a technical preview. It’s ready for early adoption and you can go and give it a spin today. Exciting times!

If you’re not familiar with the concept of digital certificate, public key infrastructure, mutual authentication and so on, I wholeheartedly recommend familiarizing yourself with the topics as it will make understanding some of the concepts in this article easier. This Wikipedia article is a good starting point but there are ample resources on the topics available online.

Why another authentication method?

We have been hearing from Zowe users that they would like to perform authentication to Zowe by other means than using a username and password. One of the chief use cases for Zowe is a devops scenario where external systems interact with mainframe to achieve a particular outcome, whether it be a build pipeline or something entirely different. In such cases, there is typically no human actor to authorize the API calls, and the authorization credentials have to be stored in a safe place. This puts them at risk of being compromised.

The standard alternative to username and password is to use a client certificate instead. There are couple of advantages to this approach over username and password:

• Certificates are much stronger than passwords
• There’s no issues with users forgetting username or password
• Certificate can be stored securely in hardware devices or a SAF security system

These reasons make them ideal for m2m communication.

Design goals for client authentication in Zowe

We have been designing the authentication capabilities with the following goals in mind:

• Enable a secure method of authentication so that a Zowe user does not require knowledge of a password
• Control which authentication fact (certificate) maps to which user
• SAF is used for access control
• Add certificate authentication to services which do not support the feature natively

So let’s dive into how it was achieved.

How does it work?

From the Zowe user’s perspective it can be summarized as the following:

• Perform a login call against Zowe but with a client certificate. The call is to be performed as a standard call with TLS, and, as part of the standard TLS handshake, the client is asked to provide its certificate.
• Receive in return Zowe’s JWT. A standard JWT is returned that represents a mainframe user. That particular user is the outcome of identity mapping performed by Zowe
• Perform API calls with obtained token. Nothing changes here.

From the system’s perspective, the process is way more involved The principle of the authentication mechanism is realized by several systems interacting together:

Zowe’s API Mediation Layer acts as a mediator (pun intended). ZSS server acts as a platform dependent adapter between SAF and API Layer, SAF performs the actual identity mapping from certificate to user and last but not least: zOSMF is the source of JWT tokens. All these systems interact to facilitate the authentication and identity mapping of certificate to mainframe user’s token.

Let’s go step by step in the flow of the authentication request and discuss exactly what happens. I will try to describe the necessary setup that has to be done for each respective step to start working. I aim to provide a comprehensive list of items so that when you’re about to try to set the feature up, you are well equipped for success!

1. Before you start

Zowe instance has to be configured and the whole feature has to be enabled. This is straightforward and you usually don’t have to change much here. There are some extended properties you can set in Gateway’s launch script, but that’s only needed when you have customized Zowe installation and changed the zowe runtime user. We’ll leave it at defaults.

What has to be done for this to work?

• Change parameters in <zowe instance directory>/instance.env

APIML_SECURITY_X509_ENABLED —This is global feature toggle. Set to true

APIML_SECURITY_ZOSMF_APPLID — This feature makes heavy use of passtickets. To be able to generate passtickets for zOSMF, we have to know it’s APPLID. Protip: The default value in the installation of z/OSMF is IZUDFLT (default shipped value). Sometimes referred to as SAF PREFIX in zOSMF’s documentation.

2. Client calls authentication API with client certificate attached

Zowe provides its authentication endpoint through the mediation layer’s API Gateway (that you can view and try out on the API Catalog tile API Mediation Layer API)

Example code to execute curl request specifying client certificate:

curl --request POST --url https://zowe.server.com:7994/gateway/api/v1/auth/login -v --cert ~/myclient.cer --key ~/myclient.key

The client will establish a TLS connection with Gateway and Gateway will request a client certificate from the client and try to verify it. Whenever you’re providing a client certificate, this authentication method takes over and other authentication means (authorization header, bearer header or credentials in request body) are ignored.

API Mediation Layer has to be able to trust this certificate. It will differentiate between Zowe server certificate and any other client certificate. Because of this calls with Zowe’s certificate are valid and will be accepted, but not considered as a method of authentication.

What has to be done for this to work?

• You have to have a client certificate and a Certificate Authority(CA) that has signed the certificate.
• The client certificate has to have Extended Key Usage extension allowing it to be used for TLS Client authentication.
• When you’re specifying SAN in the client certificate, make sure it’s valid for the call being made.
• The CA has to be imported to Zowe’s truststore/keyring.

3. Gateway calls ZSS

After establishing trust with the client, Gateway will take the public key of the client’s certificate. It will call ZSS server and provide this information. API Layer also authenticates to ZSS using valid Jwt token. While this sounds simple, there are quite a few things needed for this to happen. Generating token for ZSS means calling zOSMF and authenticating to obtain a token, that is then sent to ZSS. Since we don’t store any passwords to do so, we have to rely on passtickets. API Layer can be configured to generate passtickets and we depend on this functionality for creating the tokens. For ZSS authentication, Zowe’s runtime user is used. ZSS has to be enabled to participate in Zowe SSO and be able to verify that the token is valid.

What has to be done for this to work?

• Zowe’s runtime user has to be able to generate passtickets for zOSMF’s APPLID
• Zowe’s runtime user has to be allowed to login to zOSMF. For example be member of default IZUUSER security group
• Zowe’s runtime user has to be set with password. The user is created with the NOPASSWORD parameter by the Zowe installer. This password must be changed and a new password has to be set.
• ZSS has to be configured to participate in Zowe SSO

4. ZSS asks SAF

After the previous step, it’s ZSS’s time to shine. The meaning of this action is to perform a mapping from the client certificate to a concrete mainframe user. ZSS performs a native call to SAF’s API to map the public certificate it received from API Layer to a mainframe identity. R_usermap callable service is the underlying mechanism, and ZSS has to have sufficient authority to use it. SAF then searches for a user that owns the specified certificate. That means that the certificate that the original client called with, has to be assigned to a specific mainframe user in SAF. If SAF finds the user that owns the certificate, it returns it. This is how the mapping works. The user name is returned back to API Layer.

What has to be done for this to work?

• Zowe is configured to use identity mapping. Since version 1.18 this is done automatically during installation. You can do this manually as well
• The client certificate has to be owned by user in SAF. You have to import or generate the client certificate to the appropriate user that is represented by the client certificate. There are several ways to achieve this. For example in RACF you could use RACDCERT command to import a certificate from dataset like so:

RACDCERT ADD(‘RACFADM.NETB0Y.CERT’) ID(NETB0Y) TRUST WITHLABEL(‘Netb0y client certificate’)

Please refer to your security system’s documentation for details.

5. API Layer generates token for mapped user

This is the last step performed by API Layer calling zOSMF with passticket and logging in as the mapped user returned from ZSS. After the token is obtained, it is returned to the client. This closes the authentication cycle and the client can call APIs with this token.

What has to be done for this to work?

• Zowe’s runtime user has to be able to generate passtickets for zOSMF’s APPLID. This is a repeat from one of the previous steps.

Debugging client certificate setup

As you can see, the setup is quite involved and there are many steps that have to line up and be performed correctly for this feature to work as expected. Chances are that you will get it wrong the first time around. We have been conscious of this fact and added debug logs for this feature. That is also a reason why I tried to explain the process in great detail step by step, so that when looking through the logs, these steps are obvious and you can identify where the problems are.

When you want to debug, just enable API Layer’s debug mode, restart Zowe and try to perform the authentication. Main classes of interest are: TokenCreationService, X509AuthenticationProvider, X509ExternalMapper. If you’re still unable to get it right, reach out to one of Zowe’s public Slack channels (zowe-dev, zowe-user) or directly to API Squad Channel.

We want to hear from you

We do appreciate any feedback that relates to this feature, setting it up or using it. Best way to provide it is by going to Zowe’s public Slack channels zowe-dev, zowe-user or directly to API Squad channel. Alternatively you are welcome to create an issue against API Layer’s repository on GitHub.

Finding out more

If you enjoyed this blog checkout more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #Zowe-dev, #Zowe-user or #Zowe-onboarding. If this is your first time using the OMP slack channel register here.

Zowe is an open source project and all of the code is available at https://github.com/zowe. The Zowe documentation sections for client certificate authentication can be found here: https://docs.zowe.org/stable/user-guide/api-mediation/api-gateway-configuration.html#gateway-client-certificate-authentication https://docs.zowe.org/stable/extend/extend-apiml/api-mediation-security.html#client-certificate