System developers – USI Registry System support and information

To establish web service connections, the USI Registry System uses a combination of an organisation’s ABN and USI OrgCode for authentication and authorisation.

Software Developer Kits

Developers need:

• an Authentication kit - email the Digital Partnership Office (DPO) at dpo@ato.gov.au
• a USI Developer kit - complete the USI Developer Kit request form.

USI Developer Kit

The USI Developer Kit includes:

• USI web service technical services contract
• current version of the security token service – service definitions
• USI check character algorithm
• connection instructions
• Machine-to-Machine (M2M) authentication and organisation codes for the test environment.

Apply for the USI Developer Kit (DK)

Connecting to the USI Registry System

When accessing the Registry System, an organisation is authenticated. The OrgCode is submitted to the USI Registry System and checked that it:

• is registered in the USI Registry System
• has an ABN that matches the certificate generated from authentication credentials
• has been authorised by the Student Identifiers Registrar to use the USI web services
• is the correct organisation type (Registered Training Organisation, VET related body, Higher Education Provider or Tertiary Admission Centre) to use the called functions.

For more information, contact us at IT@usi.gov.au.

Obtaining Machine-to-Machine (M2M) authentication

Web services use Machine-to-Machine (M2M) authentication. To be issued with M2M, an organisation and its staff must first set up a myID and Relationship Authorisation Manager (RAM).

Authentication options

Desktop software

Organisations download software to their own environment and use their secure M2M credential for transactions to the USI Registry System.

Cloud software

The My Cloud software services allows software developers to design and install a solution for clients using cloud-based SBR enabled software. This enables secure communication with the Office of the Student Identifiers Registrar.

An organisation using cloud-hosted services does not have to get their own machine credential. The digital service provider is required to create a machine credential and install it on their server. The digital service provider is then able to authenticate a connection to the USI Registry System by third party users.

After creating a Digital ID, such as myID and linking their business in Relationship Authorisation Manager (RAM), the business associate (principal authority) of an organisation needs to access RAM and nominate the digital service provider submitting transactions on their behalf.

To use USI web services in the production environment, an education or training provider must be authenticated and authorised to access the USI Registry System and meet the following requirements:

• registered training organisations must be listed on training.gov.au (TGA)
• higher education providers must be listed on the TEQSA National Register.

The USI Registry System uses the education or training provider ABN and code details as listed on TGA or the National Register for authentication purposes. The ABN listed must be the same one linked in RAM and registered with the Australian Business Register. If an education or training provider has changed their ABN recently, they need to update their details on TGA or the TEQSA National Register.

Where organisations have a single ABN and multiple organisation codes (including dual sector providers) machine credentials can be used.

All education or training providers must:

• have a Student Management System that has incorporated the USI Technical Services Contract
• have machine credentials installed in their SMS infrastructure. To be issued with M2M, an organisation and its staff must first set up a Digital ID, such as myID and Relationship Authorisation Manager (RAM)
• complete the System Access Request Form to request access to use USI web services and accept the terms and conditions of use.

An access form needs to be submitted for each provider, as defined by organisation codes, requesting access to web services.

Organisations must read, understand and accept the terms and conditions of using the USI Registry System.

Other VET related organisations and Tertiary Admission Centres wishing to use USI web services must:

• have set up myIDs and RAM
• have M2M credentials
• complete the System Access Request form so they can be issued an USI organisation code which must be supplied as a part of all USI web service calls
• agree to the terms and conditions of use.

Student Management System (SMS) developers must use our third party environment to test their system for:

• web service authentication
• connectivity
• functionality.

To arrange access to our third-party testing environment, complete the USI Developers Kit application form.

Once approved, you will be issued with the USI Developers Kit which includes:

• USI web service technical services contract
• current version of the security token service – service definitions
• USI check character algorithm
• connection instructions
• Machine-to-Machine (M2M) authentication and organisation codes for the test environment.

Using libraries in development is required

• WCF for .NET (latest versions, minimum requirement .NET 4.5)
• Java WSIT library (authorised by Microsoft and Sun and published on the Oracle website)

Web services integration

We have developed a web services component that enables calls between Student Management Systems (SMS) and the USI Registry System.

The services allow an authorised consumer to:

• create a USI record for an individual and receive an immediate response
• submit a batch of USI creation requests for processing
• retrieve the results of a previously submitted batch request
• verify a USI for an individual and receive an immediate response
• verify a batch of USIs and receive an immediate response.

USI Technical Services Contract and web service versioning policy

To set up web service functionality, along with other details, you will need the USI Registry System Technical Services Contract in conjunction with the policy and procedures for web service versioning for the USI Registry System. The current version of the Technical Services Contract (TSC) is V 5.0 effective July 2022.

All new systems must use Technical Services Contract Version 5.0 from July 2022.

USI Organisation Portal users

For more information, visit myID and RAM.

DotNET Framework

Organisations experiencing problems with specific machines may resolve the machine issue by having dotNET Framework reinstalled (and/or upgraded from 4.0 to 4.5 on machines that won't connect).

Student Management System (SMS) error messages

Organisation was not verified as an authorised body/organisation in the system

The error indicates the organisation has not requested access to the USI Registry System using web services or if access has been requested, the application has not yet been processed.

A request for access via web services and accepting terms and conditions is a mandatory requirement.

An error occurred when verifying security for the message

In the USI request, all the EncryptedData elements (including the EncryptedAssertion element) need to appear before all instances of the Signature element.

Some developers have resolved the issue by changing the order of the classpath parameters for the java execution.

ID3242: The security token could not be authenticated or authorised

ATO MAS gateway does not authenticate using a username/password model. It uses a certificate. If a developer uses the svcutil tool against the endpoint they will generate a config file which shows the bindings expected. They should see that a certificate is required, not a password.

Unknown KeyStore exception – 4699

For applications developed in .Net using IIS manager. In IIS Applications Pool -> Advanced Settings:- changing the setting ‘Load User Profile’ to true solved problems for some users.

If not using .Net/IIS manager, this solution (amending local settings) may be something that can be investigated.

The relying party specified in the ‘Applies to’ element is not recognised. Event Code [E2044]

This error is encountered when code has been migrated from the test environment into the production environment. To resolve this, remove:

• any references to the 3PT realm in the 'Applies To' element of the request to the production Security Token Service (STS) at VANguard
• any testing references (for example ‘3PT’ or ‘third party’) from all endpoint production URLs.

Could not establish trust relationship for the SSL/TLS secure channel with authority 'authentication.softwareauthorisations.ato.gov.au’

TLS protocol 1.2 is the minimum version supported in the USI Registry System. Check whether a 2003 server that is not compatible with USI Web Services is being used.

I am testing the system but it says the credential has expired

Send a request for an updated credential file to IT@usi.gov.au.

What do I need to be able to test my system connectivity with the USI Registry System?

Register for web services testing with the USI Developer Kit (DK) request form. 

What happens after I submit my USI Developer Kit (DK) form?

You will receive the USI Developer Kit which contains everything that is needed to connect to USI web services, including:

• test environment credentials and org codes
• checksum algorithm
• technical service contract.

USI web service sample code installation guides for:

The USI Registry System provides a web service to allow authorised education or training providers to initiate direct, system-to-system interactions with the USI Registry System.

The web service versioning policy is intended for:

• the USI Registry System Development team
• the USI Registry System Operations team
• system developers (usually Student Management Systems) that consume the USI Registry System Web Service.

Read the web service versioning policy.

Click here to access the System developers FAQ page.