ASTRA

How-to: Consume ASTRA Web Service from Java J2EE

Introduction

This document describes how to create a J2EE client application that consumes authorization data from the ASTRA web service. The client authenticates using X509 client certificates.

Required software

• Compliant Java 2 Standard Edition (J2SE) SDK (version 1.4.2 recommended)
  (http://www.java.com)
• Sun JWSDP (Java Web services Developer Pack) 1.4
  (http://java.sun.com/webservices/jwsdp/index.jsp)
• OpenSSL (optional)
  http://www.openssl.org
  Binaries available at http://www.slproweb.com/products/Win32OpenSSL.html

Install X509 certificates

Important: You cannot use keytool (the default tool for creating, import and exporting certificates) to generate X509 v3 certificates, which are required by the ASTRA web service. The keytool utility only creates X509 v1 certificates.

To overcome this, you can use a different tool, such as OpenSSL, IBM's iKeyMan (GUI or command line), or Microsoft's Certificate Manager, to generate the keypair. Once the keypair has been generated, and the certificate has been signed, you can use Sun's new pkcs12import tool that ships with JWSDP 1.4 to import the key pair into an existing key store.

The steps below describe how to do this with OpenSSL.

1. If necessary, download the UWCA root certificate and install in your machine's trusted root store.

   You can determine whether the root certificate exists by using the Sun Java keytool to list the certificates in the cacerts trust store.

   

   Save the downloaded certificate as, say, uwca.crt, and install it into your trust store using keytool.

   The default trust store is {java_home}\jdk\jre\lib\security\cacerts

   keytool -import -file uwca.crt -alias uwca -keystore cacerts

   Note: You can use keytool to import a certificate with no problem; it just does not have the ability to import private keys.

2. Register as administrator of a DNS domain

   You will need to register your workstation or development server please visit https://www.washington.edu/computing/ca/infra/, note step 1.5 and 1.6 which refer to registering your DNS. You may need to request a static IP address for your workstation.

3. Generate a keypair and certificate signing request (CSR)

   openssl req -nodes -newkey 1024 -keyout mycrt.key -out mycrt.req

4. Submit the CSR to the UWCA (http://certs.cac.washington.edu)

Click on the "PEM Method" button and enter the text generated in mycrt.req. The UWCA will process the request within about 10 minutes and will notify you by email that your certificate is ready.

5. Return to the CA and retrieve your certificate in PEM format (copy and paste the text in the box). Save this certificate as, say, mycrt.crt
6. Convert the certificate and key combination to pkcs12 format;

   openssl pkcs12 -in mycrt.crt -inkey mycrt.key -export -out mycrt.p12 -nodes -CAfile uwca.crt

   where the uwca.crt contains at least the certificate of your certificate's signing authority.

7. Import the pkcs12 format certificate and key into your java keystore (JKS) with the pkcs12import tool. If the store does not exist, create one.

   pkcs12import -file mycrt.p12 -keystore mystore.jks -alias mycrt

Generate the static proxy

Use the Sun wscompile utility to generate a static proxy.

wscompile config-wsdl.xml -gen:client -d ${build} -classpath ${build}

The contents of the config-wsdl.xml file referenced above will look something like:

<?xml version="1.0" encoding="UTF-8"?>
<configuration 
 	xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">
  <wsdl location="https://ucs.admin.washington.edu/astraws/astraws.asmx?wsdl"
       packageName="AstraStatic"/>
</configuration>

Import the necessary namespaces

import javax.xml.rpc.Stub;
import java.io.*;
import java.util.*;
import java.beans.XMLEncoder;
import java.beans.XMLDecoder;

Set the security credentials

Specify the java key store and trust store to use.

// Set the security credential properties
System.setProperty("javax.net.ssl.keyStore",
	keyStore);
System.setProperty("javax.net.ssl.keyStoreType", "JKS");
System.setProperty("javax.net.ssl.keyStorePassword",
	keyStorePassword);

System.setProperty("javax.net.ssl.trustStore",
	trustStore);
System.setProperty("javax.net.ssl.trustStoreType", "JKS");
System.setProperty("javax.net.ssl.trustStorePassword",
	trustStorePassword);

Call the web service

// Instantiate the proxy object
Stub stub = createProxy();

// Set the web service end point URL
stub._setProperty(
	javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY,
	endpointAddress);

// Cast it to an AuthzProvider object
AuthzProviderSoap astra = (AuthzProviderSoap) stub;

// Create the auth filter
Auth authFilter = new Auth();

authFilter.privilege = new Privilege();
authFilter.privilege.code = privilegeCode;

authFilter.party = new Party();
authFilter.party.uwNetid = uwnetid;

authFilter.environment = new Environment();
authFilter.environment.code = environmentCode;

// Invoke the call
Authz authz = astra.getAuthz(authFilter);

Cache authorization data for user session

// if authz exist in session cache, deserialize the object from cache

	byte[] buf = cache.toByteArray();
	InputStream is = new ByteArrayInputStream(buf);
	XMLDecoder decoder = new XMLDecoder( is );
	Authz authz = (Authz)decoder.readObject();

// else call the web service, serialize the output and save it to cache

	// Serialize the XML output to a string
	ByteArrayOutputStream os = 
		new ByteArrayOutputStream();
	XMLEncoder encoder = new XMLEncoder(os);
	encoder.writeObject(authz);
	encoder.close();

	// SAVE serialized object to cache
	...

Iterate the authorization collection returned

// Work with the authz
for (int i = 0; i < authz.authCollection.auth.length; i++) 
{
	Auth a = authz.authCollection.auth[i];
	System.out.println(a.privilege.code);
	System.out.println(a.role.code);
	System.out.println(a.action.code);
	for (int n = 0; n < a.spanOfControlCollection.spanOfControl.length; n++)
	{
		SpanOfControl s = a.spanOfControlCollection.spanOfControl[n];
		System.out.println(s.code);
	}
}

References

WS-Security Interoperability Using WSE 2.0 and Sun JWSDP 1.4