How To‎ > ‎

AUSkey under Linux - obsolete

As of March 2014, this document is obsolete. AUSkey now works natively under Linux. The information on this page was correct at time of publication.

About this document

This document is a completely re-written description of the process to install AUSkey under Linux. It's history relates to a document called "CSI under Linux", which is being superseded as I write this - CSI ATO Digital Certificates stopped being registered or renewed from May 2010, when AUSkey started. The last of the ATO certificates should expire by the end of 2012. At that time, AUSkey will be the way to authenticate with many Australian Government services.

This document has been long in the planning. Originally the CSI document was written by me, Onno Benschop with much assistance from the community. It was last revised in 2007 and while it contains some ancient references, the process is still essentially correct. As new systems were being developed by the developers at the ATO, I kept holding off writing a new version until there was some stability in the system.

If you find errors or omissions in this document, send an email to the AUSkey mailing list/forum which is hosted using Google Groups/Sites. Information can be found at: http://auskey.itmaze.com.au/

Credits

This document was originally written by Onno Benschop (onno@itmaze.com.au) and was revised and commented on by many members of the community including ATO staff members from the AUSkey development team - you know who you are!

Introduction

Authenticating to the ATO has been a challenge for Linux users for some time. The process involves running a Java applet that uses a locally stored certificate and password to authenticate itself to a remote server. Once authentication has completed, the web-site you're intending to connect to will grant access.

In principle the process to install this authentication software is simple, in practice there are several things that can go wrong. This document aims to outline the issues and provide you with assistance in overcoming the potential challenges along the way.

The process is:
  1. Install Java
  2. Install AUSkey
  3. Import Certificate
  4. Login to Business Portal

Requirements

To make this work you need a web-browser capable of running Java and you need a copy of Java. The current version of Java is 1.6.0_x (as at 24 Feb 2011)

The minimum machine specifications are anything that Sun says will run Java.

It is assumed that you know how to get to a Linux command line and that you know how to become root on the machine where you want to install the software. If this is not the case, either contact the system administrator for your machine, or contact a local Linux User Group, I'd recommend my friends at the Perth Linux User Group. Having said that, this is not hard and if you know how to type you should not be able to get into too much trouble while installing this.

The ATO maintains an FAQ for AUSkey which now has information that assists you in the installation and/or running of AUSkey software. The AUSkey developers also maintain a site that contains the AUSkey software, FAQ and further information.

Installing Java

Before you go down the path of manually installing Java, you should first determine if you have it already installed, since most Linux distributions include some form of Java. Your first step should be to open this link: http://www.java.com/en/download/installed.jsp to see if java is detected and installed - note that if you have Java installed, it's likely to tell you that you need a newer version.

If you have Java installed according to the above, then you can skip to the next section.

If you could not determine that you have Java installed using the previous method, you can try running the following command on your terminal:

$ java -version

The output might be "command not found", or it might look something like this:

java version "1.6.0_14"
Java(TM) SE Runtime Environment (build 1.6.0_14-b08)
Java HotSpot(TM) Client VM (build 14.0-b16, mixed mode, sharing)

You have GIJ installed if your output looks like this:

java version "1.4.2"
gij (GNU libgcj) version 4.1.2 (Ubuntu 4.1.2-0ubuntu5)
Copyright (C) 2006 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Depending on which distribution you have installed, the instructions will be different for installing Sun Java 1.6.0_x. If you don't know where the documentation on how to do this is for your distribution, you can visit DistroWatch.com and look at the page specific to your distribution - it will contain links to the documentation available for you.

You can also follow the instructions on Oracle's Java site http://www.java.com/en/download/installed.jsp

Installing AUSkey

Until you have confirmed that you have Java installed and that it is working within your browser, there is no point in starting this section.

You'll need to download the AUSkey software and run the installer within. Read the readme for updates. The final step will include some sudo commands, so you'll need sudo access and your password. The steps are:
  1. cd /tmp
  2. wget https://www.auskey.abr.gov.au/plugin/AUSkey_software_for_Linux.zip
  3. unzip AUSkey_software_for_Linux.zip
  4. cd ABR_PKG
  5. less AUSkey\ Linux\ Readme.txt
  6. cd Resources
  7. bash linux_install.sh
Note that the third-party security extensions will be installed in the system Java library extension directory, /usr/java/packages/lib/ext - it will also update the export policy security libraries in /usr/lib/jvm/java-?-sun/jre/lib/security if those JRE's are found.

Importing Certificates

{this is incomplete}
AUSkey's cannot be imported like with the CSI Management Utility. They have to be individually installed (although it is possible to copy a keystore from one computer to another if needed, or manually backup the keystore).

The file that contains your certificate is the keystore.xml file. Under Linux it lives in ~/AUSkey. The locations for the key under other operating systems are:

Operating System
Location
Windows Vista and Windows 7 C:\Users\{USERNAME}\AppData\Roaming\AUSkey
Windows XP/2003 Server C:\Documents and Settings\{USERNAME}\Application Data\AUSkey
Apple OS X
~/Library/Application Support/AUSkey
Linux
~/AUSkey
USB USB Drive\AUSkey or AUSkey Browser\AUSkey


Login to Business Portal

Start you browser as the same user (i.e. the one used to import the certs).
  1. Go to http://bp.ato.gov.au/.
  2. Click "Continue". This will open the Government Authentication Service Login screen in a new window.
  3. Select your AUSkey from the list and enter the password. Then click the "Continue" button.
You should now be connected to and authenticated with the Business Portal. Remember to click "Logout" when you leave.

Resources

Comments