ZAAS Client
ZAAS Client
The ZAAS client is a plain Java library that provides authentication through a simple unified interface without the need for detailed knowledge of the REST API calls presented in this section. The Client function has only a few dependencies including Apache HTTP Client, Lombok, and their associated dependencies. The client contains methods to perform the following actions:
- To obtain a JWT token
- To validate and get details from a JWT token
- To invalidate the JWT token
- To obtain a PassTicket
This article contains the following topics:
Pre-requisites
- Java SDK version 1.8.
- An active instance of the API ML Gateway Service.
- A property file which defines the keystore or truststore certificates.
API Documentation
The plain java library provides the ZaasClient
interface with 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;
ZaasToken query(HttpServletRequest request) 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
)
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.
Both methods automatically use the truststore file to add a security layer, which requires configuration in the ConfigProperties
class.
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.
Call the query
method from your API in the following format:
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.
The query
method is overloaded, so you can provide the HttpServletRequest
object that contains the token in the apimlAuthenticationToken
cookie or in an Authorization header. You then receive the ZaasToken
Object in JSON format.
ZaasToken query(HttpServletRequest request) throws ZaasClientException;
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;
If the token is successfully invalidated, you receive a 204
HTTP status code in return.
Obtain a PassTicket (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 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.
For additional information about PassTickets in API ML see Enabling single sign on for extending services via PassTicket configuration.
Getting Started (Step by Step Instructions)
To use this library, use the procedure described in this section.
Follow these steps:
-
Add
zaas-client
as a dependency in your project.
You will need to specify the version of thezaas-client
you want.zaas-client
versioning following the semantic versioning format ofmajor.minor.patch
. For example,1.22.0
.Gradle:
-
Create a
gradle.properties
file in the root of your project if one does not already exist. -
In the
gradle.properties
file, set the URL of the specific Artifactory containing the SpringEnabler artifact.
# Repository URL for getting the enabler-java artifact
artifactoryMavenRepo=https://zowe.jfrog.io/zowe/libs-release/- Add the following Gradle code block to the
repositories
section of yourbuild.gradle
file:
repositories {
...
maven {
url artifactoryMavenRepo
}
}- Add the following Gradle dependency:
dependencies {
compile 'org.zowe.apiml.sdk:zaas-client:{{version}}'
}Maven:
- Add the following XML tags within the newly created
pom.xml
file:
<repositories>
<repository>
<id>libs-release</id>
<name>libs-release</name>
<url>https://zowe.jfrog.io/zowe/libs-release/</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>Tip: If you want to use snapshot version, replace libs-release with libs-snapshot in the repository url and change snapshots->enabled to true.
- Then add the following Maven dependency:
<dependency>
<groupId>org.zowe.apiml.sdk</groupId>
<artifactId>zaas-client</artifactId>
<version>{{version}}</version>
</dependency> -
-
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 a PassTicket. -
To use
zaas-client
, provide a property file for configuration.Tip: Check
org.zowe.apiml.zaasclient.config.ConfigProperites
to see which properties are required in the property file.Configuration Properties:
public class ConfigProperties {
private String apimlHost;
private String apimlPort;
private String apimlBaseUrl;
private String keyStoreType;
private String keyStorePath;
private String keyStorePassword;
private String trustStoreType;
private String trustStorePath;
private String trustStorePassword;
private boolean httpOnly;
}Note: If
httpOnly
property is set to true, the ZAAS Client will access the API ML via HTTP protocol without TLS. This meant for z/OS configuration with AT-TLS that will ensure that TLS and the required client certificates are used. -
Create an instance of
ZaasClient
in your class and provide theconfigProperties
object.Example:
ZaasClient zaasClient = new ZaasClientImpl(getConfigProperties());
You can now use any method from ZaasClient
in your class.
Example:
For login, use the following code snippet:
String zaasClientToken = zaasClient.login("user", "password");
The following codeblock is an example of a SampleZaasClientImplementation
.
Example:
import org.zowe.apiml.zaasclient.config.ConfigProperties;
import org.zowe.apiml.zaasclient.exception.ZaasClientException;
import org.zowe.apiml.zaasclient.exception.ZaasConfigurationException;
import org.zowe.apiml.zaasclient.service.ZaasClient;
public class SampleZaasClientImplementation {
/**
* This method is used to fetch token from zaasClient
* @param username
* @param password
* @return valid JWT token returned from the authentication service
*/
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
}
}