Integrating Endevor Bridge for Git with Zowe API Mediation Layer

Congratulations! You’ve successfully set up Endevor Bridge for Git for your organization, tweaked a few settings, configured several Endevor connections to your mainframe instance, and created some mappings. All operations are running smoothly and users are thrilled with the convenience of using Git to manage their changes in Endevor. Mainframe modernization has truly been a game-changer!

But hold on, there is more to the story. Your organization now aims to improve the security around z/OS services, including Endevor, by implementing a single point of access. The solution: Zowe API Mediation Layer (API ML).

You might be wondering whether this means that all the Endevor connections you’ve meticulously configured in Bridge for Git will become obsolete. Will your users need to go back to using the green screen to manage their sources in Endevor?

Fear not! Bridge for Git has the features to assist you through this transition. In this article, I’ll guide you through the required configuration changes. But before we dive into the details, here’s a quick overview of the Zowe API Mediation Layer.

What is the Zowe API Mediation Layer?

As an important part of the Zowe framework, the API Mediation Layer is designed to provide API consumers with a single point of access to mainframe RESTful API services.

It consists of 3 main components:

• API Gateway — acts as a single point of access to mainframe API services and its main purpose is to securely forward client requests to the corresponding registered services.
• Discovery Service — in charge of dynamically registering active REST API services.
• API Catalog — displays the information about the registered services and their corresponding API documentation through a web user interface.

Security is an important aspect of the API ML setup and it is ensured through a combination of methods.

API ML uses TLS/HTTPS for secure communication, relies on JSON Web Token (JWT) for its API security, and uses mainframe authentication services like SAF with an External Security Manager for its backed services.

Another benefit of API ML is high availability, ensuring continuous and reliable operation of mainframe onboarded services. It employs redundancy allowing multiple instances of API Gateway and service components to operate simultaneously ensuring service continuity even if one instance fails.

If you’re looking to dive deeper into the specifics of API ML, you’ll find a detailed explanation of its security features in this article and its official documentation.

Client-side authentication

To configure Bridge for Git to communicate with Endevor REST API using API Mediation Layer, we need to understand the various methods through which an API client can authenticate itself to access API ML and the services that reside in its catalog. Here are some of the supported authentication methods:

• Basic authentication — requires the API client to provide a mainframe username and password with each request. However, this approach has some drawbacks. Usernames and passwords must be stored on the client side, and they are sent over the network with every access to API ML, which can reduce security.
• Single Sign On (SSO) access token — the client exchanges mainframe user credentials (username and password) for a JWT token, which can be used for future requests. This token has a short lifespan and necessitates providing a client certificate, trusted by the API ML trust store, to get a new one. This approach enhances security as it eliminates the need to store user credentials on the client’s side. Coupled with TLS for secure communication, it significantly bolsters security. Another advantage is that it permits the API client to access multiple services registered in API ML using the same credentials.
• Personal Access Token — Functioning similarly to SSO tokens, PATs offer the same security benefits. However, they come with a longer lifespan and don’t require frequent renewal. Moreover, the layer API allows these tokens to be revoked at any time. One distinctive feature of PATs compared to SSO tokens is their more granular security scope. PATs provide access solely to the service for which they were requested during the authentication process.
• Client certificate — In this method, the API client employs a certificate for authentication. In return, the client receives an SSO JWT token, which can be utilized for subsequent requests. This certificate must be signed by a Certificate Authority trusted by the API Mediation Layer. The advantage here is that it eliminates the necessity of sending mainframe credentials over the network during the authentication process.

To access the documentation for the API endpoints, you can log in to the API ML using your mainframe credentials and then navigate to the API catalog. From there, you can access the documentation for the desired service or for the layer itself.

Bridge for Git configuration

Now that we’ve got some understanding of what API ML is and its role, it’s time to delve into configuring Bridge to seamlessly integrate with Endevor REST API through it.

Assuming you’ve already got API ML up and running within your organization, accessible via the following URL:

https://apiml.some.org.com

Endevor web services are registered into API ML under the following name:

endevor_api_service

Then your Endevor API ML service endpoint should look like this:

https://apiml.some.org.com/endevor_api_service/api/v2

It’s important to note that there are two versions of the API Mediation Layer endpoints:

• V1: The initial version, which supports SSO tokens exclusively.
• V2: Introduces support for Personal Access Token authentication.

To ensure you’re using the correct endpoint and login method, it is advisable to confirm these details with your API ML Administrator. For the sake of this example, let’s assume we’re using the latest version.

With these details in mind, we can now proceed with our setup. The first step is to navigate to the ‘Endevor Connections’ page, found under the ‘Settings’ menu in the Bridge for Git administration page, and click on the ‘Create Endevor Connection’ button:

For the next step, before you proceed to fill out the form, make sure to check the ‘Show advanced options’ checkbox.

After checking this option, an additional dropdown labeled ‘Login method’ becomes visible. With this in place, we can begin completing the form.

First, provide a name for your connection. In the ‘Endevor web services URL’ field, enter the API ML URL mentioned earlier, and select your desired Endevor configuration.

Moving on, in the ‘Login method’ dropdown, you’ll find several authentication options. Depending on your API ML version and your organization preference, you can either select ‘Login with API Mediation Layer’ for SSO token authentication or ‘Login with API Mediation Layer Personal Access Token’ to utilize the PAT token method.

Once you’ve made your choice from the options mentioned above, click on the ‘Save connection details’ button. You’ll then be directed to the Endevor Connections page, where your newly configured connection is now visible.

Login with API Mediation Layer

If you selected the ‘Login with API Mediation Layer’ option, you may notice that the API ML login button is disabled. This happens because, as mentioned earlier, the SSO token has a limited lifespan. To enable Bridge for Git to refresh it, you’ll need to provide a client certificate. This certificate needs to be paired with a mainframe user id (recommended approach is to use a technical user id for this purpose) and signed by a certificate authority trusted by both the mainframe security authority and the API Mediation Layer.

Having the certificate and its correspondent key file, it’s time to add them to the newly created configuration. To do this, on the specific connection under Endevor connections page, simply click on the options icon (Three dots) and proceed to upload your certificate file and key file.

As part of this process, you will also need to provide the API ML login endpoint which has the following path:

https://apiml.some.org.com/endevor_api_service/api/v2/auth/login

After completing this step, you’ll notice that the API ML login button becomes active. You can now enter your credentials to log in to API ML and receive the JWT token which, in turn, will be securely stored in the Bridge for Git database. Additionally, you’ll see that the Certificate Status is marked as ‘valid

As an administrator, there’s one final crucial step to ensure that API ML JWT tokens for users won’t expire. You need to enable the ‘refresh tokens’ option in the Bridge configuration, which will automatically refresh the valid tokens at halftime of their expiration interval.

To achieve this, you can add the following parameters to your Bridge application.yml file:

app:
   refresh-tokens:
      enabled: true
      at-shutdown: true

The first parameter enables token refresh during runtime, ensuring tokens stay valid.

The second parameter focuses on token refresh during a graceful shutdown operation. If the application shuts down gracefully, it refreshes all existing tokens as part of the process. However, please note that this doesn’t apply in the case of a hard kill.

If Bridge for Git experiences prolonged downtime, some tokens may expire, requiring users to log in again. As you can see, selecting the first authentication option involves several additional configurations to ensure a fully functional Endevor connection.

Login with API Mediation Layer Personal Access Token

To simplify matters, if your environment allows, you can opt for the second option, ‘Login with API Mediation Layer Personal Access Token.’ This method doesn’t require regular token refreshing due to its longer lifespan, spanning several months. As a result, successful login only requires mainframe credentials.

To ensure Bridge for Git can still synchronize changes from Endevor to Git even if the personal access token eventually expires, you can follow the same steps to add a client certificate, just like in the case of the SSO authentication method.

Conclusion

And there you have it. As you’ve seen, Bridge for Git provides full support for seamless integration with Endevor through Zowe API Mediation Layer, ensuring a secure path for modernizing your mainframe infrastructure.

I trust you’ve found this article valuable, and if you’re seeking additional information about Bridge for Git, you can explore more articles right here and also refer to our official documentation page.