The ZAAS Client: a library for the API Mediation Layer

{Core} If you’ve been following the latest news from the Open Mainframe Project Zowe, perhaps you’ve discovered that you can now take advantage of new authentication functionalities (multi-factor authentication, token authentication, PassTicket) as well as single-sign-on provided by the API Mediation Layer.

The next thing you may be wondering, though, as a system administrator or API developer, is “How do I do this?” What steps are needed to adopt these authentication capabilities to implement and integrate security solutions for your own application?

For example, as a typical use case, you might want to access the Zowe ecosystem to use a specific Zowe REST API service. To do that, you have to log in once through the API Gateway by providing the Basic Authentication credentials in order to obtain the JWT token that can be used to access the Zowe REST service resources. Furthermore, you might also want to check the validity of the JWT token by getting its details, such as the expiration time and the user who the token is issued to. Or, in alternative, you would like to generate a PassTicket and use it to access the Zowe-conformant API service.

Does this require a detailed knowledge of the API ML REST API calls which support these functionalities? Wouldn’t it be great if there was a Java library that could provide authentication through a simple unified interface?

Well, you’re in luck.

I’d like to introduce you to Zowe Authentication and Authorization Service (ZAAS) Client — a library that contains methods for retrieval of JWT tokens, PassTickets, and even verifying JTW token information. ZAAS Client simplifies your security implementation and introduces only a few dependencies including Apache HTTP Client, Lombok and their associated dependencies.

This native java library is developed on top of the Zowe API Mediation Layer login, query, logout and PassTicket API, and is developed with Apache http Client version 4.5.11.

API documentation

The plain java library provides the ZaasClient interface with the following public methods:

public interface ZaasClient {
    String login(String userId, String password) throws ZaasClientException;
    String login(String authorizationHeader) throws ZaasClientException;
    ZaasToken query(String token) throws ZaasClientException;
    String passTicket(String jwtToken, String applicationId) throws ZaasClientException, ZaasConfigurationException;
    void logout(String token) throws ZaasClientException, ZaasConfigurationException;
}

This Java code enables your application to add the following functions:

• Obtain a JWT token (login)
• Validate and get details from the token (query)
• Invalidate a JWT token (logout)
• Obtain a PassTicket (passTicket)

Let’s start off by looking at how to obtain a JWT token (login)

To integrate login, call one of the following methods for login in the ZaasClient interface:

• If the user provides credentials in the request body, call the following method from your API:

String login(String userId, String password) throws ZaasClientException;

• If the user provides credentials as Basic Auth, use the following method:

String login(String authorizationHeader) throws ZaasClientException;

These methods return the JWT token as a String. This token can then be used to authenticate the user in subsequent APIs.

Note that both methods automatically use the truststore file to add a security layer, which requires configuration in the ConfigProperties class.

Now that we’ve obtained a JWT token, let’s take a look at how to validate and get details from the token (query).

Use the query method to get the details embedded in the token. These details include creation time of the token, expiration time of the token, and the user who the token is issued to.

To use this method, call the method from your API.

ZaasToken query(String token) throws ZaasClientException;

In return, you receive the ZaasToken Object in JSON format.

This method automatically uses the truststore file to add a security layer, which you configured in the ConfigProperties class.

Ok, now that we’ve validated the token and gotten the details it contains, let’s look at how to invalidate a JWT token (logout).

The logout method is used to invalidate the JWT token. The token must be provided in the Cookie header and must follow the format accepted by the API ML.

Call the logout method from your API in the following format:

void logout(String token) throws ZaasClientException, ZaasConfigurationException;

In return, you receive a 204 HTTP status code if the token was successfully invalidated.

Finally, let’s look at how to validate and get details from the token (passTicket).

The passTicket method has an added layer of protection. To use this method, call the method of the interface and provide a valid APPLID of the application and JWT token as an input.

The APPLID is the name of the application (up to 8 characters) that is used by security products to differentiate certain security operations (like PassTickets) between applications.

This method has an added layer of security, whereby you do not have to provide an input to the method since you already initialized the ConfigProperties class. As such, this method automatically fetches the truststore and keystore files as an input.

In return, this method provides a valid pass ticket as a String to the authorized user.

So, how do I use the ZAAS Client?

To use this library, follow the steps described below:

1. Add zaas-client as a dependency in your project.
   dependencies {
compile 'org.zowe.apiml.sdk:zaas-client:{{version}}'
}
2. In your application, create your java class which will be used to create an instance of ZaasClient, which enables you to use its method to login, query, and to issue passTicket.
3. To use zaas-client, provide a property file for configuration. Check org.zowe.apiml.zaasclient.config.ConfigProperites to see which properties are required in the property file.

public class ConfigProperties {
    private String apimlHost;
    private String apimlPort;
    private String apimlBaseUrl;
    private String keyStoreType;
    private String keyStorePath;
    private char[] keyStorePassword;
    private String trustStoreType;
    private String trustStorePath;
    private char[] trustStorePassword;
    private boolean httpOnly;
}

4. Create an instance of ZaasClient in your class and provide the configProperties object. You can now use any method from ZaasClient in your class. The following codeblock is an example of a SampleZaasClientImplementation.

public class SampleZaasClientImplementation {
/**
     * This method is used to fetch token from zaasClient
     * @param username
     * @param password
     * @return
     */
    public String login(String username, String password) {
        try {
            ZaasClient zaasClient = new ZaasClientImpl(getConfigProperties());
            String zaasClientToken = zaasClient.login(username, password);
            //Use this token  in subsequent calls
            return zaasClientToken;
        } catch (ZaasClientException | ZaasConfigurationException exception) {
            exception.printStackTrace();
        }
    }
private ConfigProperties getConfigProperties() {
        // Load the values for configuration properties
     }
}

Conclusion

Following up on the main principle on which Zowe is built, namely to provide a high level of common functionality, interoperability and enhanced user experience, the ZAAS Client library aims to facilitate the work of the system administrator or API developer. Using the ZAAS Client library, Zowe API Mediation Layer’s authentication capabilities become even easier to use.

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.