What is the SAF interface? 

System Authorization Facility (SAF) is an interface used by Multiple Virtual Storage (MVS) that allows programs and applications to control access to datasets, commands, or other resources by using system authorization services. Generally, the SAF interface is used concurrently with IBM's Random Access Control Facility (RACF) to control access to specified resources. SAF's primary purpose is to control access to certain resources on the mainframe and ensure that only authorized users have access to those resources.

What are the IBM Java SAF APIs

The IBM Java SAF APIs are a collection of Java classes and methods that utilize the SAF interface to provide an extra set of security APIs to IBM's JDK. These SAF Java APIs wrap z/OS UNIX system services via JNI to call an underlying security server (such as RACF) via the SAF interface to control access to resources on the mainframe using Java code.

In other words, a Java developer simply has to use the Java SAF classes and methods in their programs to utilize the benefits of access control to resources on the mainframe. The Java SAF APIs will then use the JNI layer within UNIX System Services to pass control to the MVS router via the SAF interface. The MVS router is then responsible for passing control to the external security manager (ESM), e.g, RACF, to handle the actual access control functionality. The ESM will then return information back through these applications saying whether the request was approved or not.

What services do the Java SAF APIs provide?

With the Java SAF APIs, we can perform the following operations:

1. Check whether our security server is active
2. Get the current user ID
3. Check the permission a user ID has to certain resources
4. Authenticate a user
5. Check if a user is a member of a group
6. Change a user's password

NOTE: The info in this section was inspired by the Redbook, Java Security on z/OS - The Complete View. Read for more information on the Java SAF APIs as well as Java security on z/OS.

Some examples

Below are some examples of how to use some of the Java SAF APIs. The APIs are under the Java package com.ibm.os390.security.

Example 1 - Check if the security server is active

The following example will allow us to check if our underlying security server, in this case RACF, is currently active.

import com.ibm.os390.security.PlatformSecurityServer;

public class Example1 {
    public static void main(String[] args) {
        if (PlatformSecurityServer.isActive()) {
            System.out.println("The security server is active and ready.");
        } else {
            System.out.println("The security server is NOT active.");
        }
    }
}

Example 2 - Get the current user ID

The following example will return a String of our current user ID.

import com.ibm.os390.security.PlatformThread;

public class Example2 {
    public static void main(String[] args) {
        String userName = PlatformThread.getUserName();
        if (userName != null) {
            System.out.println("My username is: " + userName);
        }
    }
}

Example 3 - Authenticate a user

The following example demonstrates how to authenticate a user. Note that the status of the request is returned into a PlatformReturned object, which provides information indicating whether a successful request occurred. If the PlatformReturned variable is null, that indicates that the request was successful and the user is authenticated. If the request caused an exception or the user is not authenticated, you can extract information from the object to identify the problem.

import com.ibm.os390.security.PlatformReturned;
import com.ibm.os390.security.PlatformThread;
import com.ibm.os390.security.PlatformUser;

public class Example3 {
    public static void main(String[] args) {
        // Retrieve the username and password for the user to authenticate
        String userName = PlatformThread.getUserName();
        String password = "PASSWORD";

        // Authenticate the user
        PlatformReturned pr = PlatformUser.authenticate(userName, password);

        if (pr == null) {
            System.out.println("User authenticated.");
        } else {
            System.err.println("An error occurred while trying to authenticate...");
            System.err.println("\terrno   : " + pr.errno);
            System.err.println("\terrno2  : " + pr.errno2);
            System.err.println("\terrnoMsg: " + pr.errnoMsg);
        }
    }
}

If we run the above code and the user was not properly authenticated, we can expect to see an output like this:

An error occurred while trying to authenticate...
        errno   : 111
        errno2  : 151781376
        errnoMsg: EDC5111I Permission denied.

Conclusion

In this article, we've covered the basics of IBM's Java SAF APIs and have seen some examples of how it can be implemented in our Java applications.

How to obtain the IBM Java SAF APIs

The IBM Java SAF APIs are included in the IBM Semeru Runtime Certified Edition for z/OS download. Please follow the links below to download the IBM Semeru JDK onto your own machines.

 How to obtain IBM Semeru Runtime Certified Edition for z/OS?
IBM Semeru Runtime Certified Edition for z/OS is available for zero license charge through Shopz SMP/E, or you can download the non-SMP/E here. The subscription and service number is 5655-I48.

Supporting Links:
IBM Semeru Runtime Certified Edition for z/OS product page
For additional information on installation, troubleshooting and support please visit IBM Documentation.