Client Authentication

Getting started

This page defines the process to successfully authenticate your client application using a machine-to-machine (M2M) credential,  obtain an access token from the ATO authorisation server (ATO SSO/IdP), and make calls to the API gateway.

There are some differences in the process for a directly connected software or an online service provider (OSPs). Any differences will be clearly stated. Otherwise, the process is the same.

Definitions

Online Service Providers (OSPs)

Products or services controlled by the DSP that is either self-hosted or more commonly cloud hosted by the DSP. Online service providers and Cloud service providers are considered synonymous terms. The DSP manages their own M2M Credential.

Directly Connected Software

Software that directly consumes DSG APIs. The M2M Credential is hosted and managed by the business client. Examples include:

• Desktop software installed on PCs
• Desktop software installed on virtual machines (whether they are hosted in the cloud or on-premises)
• Software installed in cloud hosted and security isolated multi-tenant solutions
• DSP cloud providers when consuming the DSG Health check API

Authentication using OAuth 2.0

For M2M authentication, we use the OAuth 2.0 protocol:

• client credentials grant type (see RFC-6749) for directly connected software
• JSON Web Token (JWT) bearer grant type (see RFC 7523) for online service providers

The ATO SSO/IdP requires consuming applications to authenticate themselves via the exchange of a signed private key JWT. This is outlined in section 9 of the Open Id Connect 1.0 standard. In addition, online service providers will need a grant JWT when acting on behalf of a business or intermediary.

Consuming applications are required to submit their serialised M2M credential along with a specific client id in their private key JWT. An access token is then issued by ATO SSO/IdP based on the trust of the Certificate Authority (CA), not the trust of the software.

The following information describes these rules in addition to section 9 of the standard.

High-level end-to-end processes

The process of authenticating a client application using an M2M credential, then making calls to the API gateway involve the following steps:

• For directly connected software
  • Ensure pre-requisites are met
  • 1a: create private key JWT
  • 2: request access token from ATO SSO/IdP
  • 3: make calls to the API gateway.

Note: a grant JWT does not need to be created for directly connected software.

• For online service providers
  • Ensure pre-requisites are met
  • 1a: create private key JWT
  • 1b: create grant JWT
  • 2: request access token from ATO SSO/IdP
  • 3: make calls to the API gateway.

Pre-requisites

The following are pre-requisites for the authentication process:

• Client Id
• M2M credential
• Scopes
• Authorisation in Access Manager (AM)
• Consumer (API) key

Client Id

For sandbox testing use the test credentials provided.

For production calls, a unique client id is required for each software instance. A unique client id is generated when you register your software instance with ATO SSO/IdP via dynamic client registration (DCR).

• Use the OAuth dynamic client registration API to register your software instance via DCR.

M2M credential

For sandbox testing use the test credentials provided.

For production calls:

• directly connected software - use the M2M credential of your desktop software user. Inform your desktop software users that they will need to create their own M2M credential.
• online service providers - use your own M2M credential (you can create your M2M credential if you don’t already have one). Your subscribing users do not need to install their own M2M credential.

You will need to extract the public certificate and public key of the M2M credential.

Extract the public certificate and private key

The following information describes how to extract the public certificate and private key using OpenSSL from your M2M credential keystore. This is used as an example. Other software or methods can be used to extract the public certificate and private key.

Extracting the public certificate

1. Download and install OpenSSL https://slproweb.com/products/Win32OpenSSL.html.
2. Open the keystore xxxx.xml in a text editor.
3. Copy the public x.509 certificate and convert into xxx.cer by
   • copying <publicCertificate> base 64 encoded content into a new text editor
   • adding a line -----BEGIN CERTIFICATE----- to the top
   • adding a line -----END CERTIFICATE----- to the end
   • saving the file as xxx.p7b
   • opening the command prompt and *cd to the directory
   • running the command: openssl pkcs7 -print_certs -in xxx.p7b -out xxx.cer
   • opening the xxx.cer file using a text editor to view the public x.509 certificate (the first certificate in the list).

Extracting the private key

1. Copy the private key into an encrypted PKCS8 file xxx.key by
   • copying the <protectedPrivateKey> base 64 encoded content into a text editor
   • adding the line -----BEGIN ENCRYPTED PRIVATE KEY----- to the top
   • adding the line -----END ENCRYPTED PRIVATE KEY----- to the end
   • saving the file as xxx.key.
2. Convert xxx.cer and xxx.key into PKCS12 by
   • opening the command prompt and *cd to the directory
   • running the command openssl pkcs12 -export -in xxx.cer -inkey xxx.key -out xxx.p12 -passin pass:<password> -passout pass:<password>.
3. Extract the private key from the PPKCS12 file xxx.p12 by
   • running the command openssl pkcs12 -info -in xxx.p12 -nodes -nocerts
   • entering the keystore password
   • viewing the private key, which will be shown between 'begin private key' and 'end private key'.

Scopes

Scopes will vary for each API and will be available in the corresponding API documentation of each API (see API catalogue).

Scopes will be the same for sandbox testing and production use.

Authorisation in Access Manager

For sandbox testing use the test credentials provided. These have been set up with the required authorisations.

For production calls

• directly connected software - your users will need to set up any required authorisations (depending on their use case) in AM
• online service providers - your subscribing users will need to
  • set up any required authorisations (depending on their use case) in AM
  • notify us that they are using your cloud-hosted software by recording the Software ID (provided by your software), in Access Manager.

Consumer (API) Key

Consumer (API) keys are provided in your team app in the API portal.

For sandbox testing, use the sandbox consumer key (API key) of your team app. The sandbox consumer (API) key will be available as soon as you have created your team app.

For production calls, use the production consumer key (API key) of your team app. The production consumer (API) key will be available after you have been approved for production access.

Your consumer (API) keys must be subscribed to the APIs you want to call.

Step 1a: Create private key JWT

This step is applicable for both directly connected software and online service providers.

The private key JWT is used in the client_assertion parameter in the request to the ATO SSO/IdP for an access token.

To construct your private key JWT, use your preferred libraries to sign and verify your JWT. You can download libraries in your preferred language from JSON Web Token Libraries - jwt.io.

JWT Header

The header must contain the following mandatory parts:

• x5c: the x.509 public signing certificate in an array as described in section 4.1.6 of the JSON Web Signature standard (include the signing certificate only, not the whole certificate chain - see Extracting the public certificate)
• alg: must be ‘RS256’
• typ: must be ‘JWT’.

An example header is:

 { "x5c": [ "MIIFgTCCBGmgAwIBA… WirKotuUYyTEhzH/TiY/G2H" ], "alg": "RS256", "typ”: "JWT" }

JWT Payload

The payload must contain the following mandatory claims:

• aud: must be token endpoint for the request
• iss: must be the client id
• sub: must be the client id
• jti: unique identifier for the JWT
• iat: issued at time.
• exp: expiration time.

An example payload for directly connected software is:

 { "aud": " https://auth.evte.ato.gov.au/core2/connect/token", "iss": "https://testclientapp.ato.gov.au", "sub": "https://testclientapp.ato.gov.au", "jti": "85deac03-3e11-400e-a79a-c3ee4940446e", "iat": 1651635085, "exp": 1683174685 }

An example payload for online service providers is:

 { "aud": " https://auth.evte.ato.gov.au/core2/connect/token", "iss": "https://testclientapp.ato.gov.au/jwtbearer", "sub": "https://testclientapp.ato.gov.au/jwtbearer", "jti": "85deac03-3e11-400e-a79a-c3ee4940446e", "iat": 1651635085, "exp": 1683174685 }

JWT Signature

The signature should be created using the:

• public certificate - the x.509 public signing certificate, include the signing certificate only, not the whole certificate chain - see Extracting the public certificate
• private key - the private key of the signing certificate - see Extracting the private key.

An example signature is:

 RSASHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), (public_certificate, private_key) )

The final JWT token which is the private key JWT is a concatenation of the Base64-URL encoded JWT Header, the Base64-URL encoded JTW Payload and the Base64-URL encoded JWT Signature, separated by a dot(.).

private_key_jwt = <base64url-encoded jwt header>.<base64url-encoded jwt payload>.<base64url-encoded jwt signature>

Step 1b: Create grant JWT (only for OSPs)

This step is only applicable for online service providers when an API call is being made on behalf of an intermediary or business. When a call is not being made on behalf of an intermediary or business (for example, making a call to the OAuth dynamic client registration API to register a software instance with ATO SSO/IdP), a grant JWT is not required.

The grant JWT is used in the assertion parameter in the request to the ATO SSO/IdP for an access token.

To construct your grant JWT, use your preferred libraries to sign and verify your JWT. Libraries can be downloaded from JSON Web Token Libraries - jwt.io in your preferred language.

JWT Header

The header must contain the following mandatory parts:

• x5c: the x.509 public signing certificate in an array as described in section 4.1.6 of the JSON Web Signature standard (include the signing certificate only, not the whole certificate chain - see Extracting the public certificate)
• alg: must be ‘RS256’
• typ: must be ‘JWT’.

An example header is:

 { "x5c": [ "MIIFgTCCBGmgAwIBA… WirKotuUYyTEhzH/TiY/G2H" ], "alg": "RS256", "typ”: "JWT" }

JWT Payload

The payload must contain the following mandatory claims:

• aud: must be token endpoint for the request
• iss: must be the client id
• sub: must be the client id
• entityTypeCd: type of consuming client identifier to which the OSP has been granted access (i.e. “ABN”, “ACN", “ARBN”)
• entityId: value of the consuming client identifier to which the OSP has been granted access
• scope: scope(s) of the API(s) you want to call (if there are multiple scopes, separate each scope with a space)
• ssid: software subscriber ID of the software, which you issued to your consuming client, and which is recorded in AM
• jti: unique identifier for the JWT
• iat: issued at time
• exp: expiration time.

An example payload is:

 { "aud": "https://auth.evte.ato.gov.au/core2/connect/token", "iss": "https://testclientapp.ato.gov.au/jwtbearer", "entityTypeCd": "ABN", "entityId": 36089616740, "sub": "https://testclientapp.ato.gov.au/jwtbearer", "scope": "ato.super.stapledsuperfund.c,r" "ssid": 1234567895, "jti": "85deac03-3e11-400e-a79a-c3ee4940446e", "iat": 1651635086, "exp": 1683174686 }

JWT Signature

The signature should be created using the:

• public certificate - the x.509 public signing certificate, include the signing certificate only, not the whole certificate chain (see Extracting the public certificate)
• private key - the private key of the signing certificate (see Extracting the private key).

An example signature is:

 RSASHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), (public_certificate, private_key) )

The final JWT token which is the grant JWT is a concatenation of the Base64-URL encoded JWT Header, the Base64-URL encoded JTW Payload and the Base64-URL encoded JWT Signature, separated by a dot(.).

grant_jwt = <base64url-encoded jwt header>.<base64url-encoded jwt payload>.<base64url-encoded jwt signature>

Step 2: Request an access token from ATO SSO/IdP

Public token API endpoints

• Production: https://auth.ato.gov.au/core2/connect/token
• Test: https://auth.evte.ato.gov.au/core2/connect/token

Sending a request to ATO SSO/IdP

This step is applicable for both directly connected softwareand online service providers.

Send a HTTP Post request to ATO SSO/IdP public token API endpoint with the following mandatory parameters:

For directly connected software in all scenarios, and online service providers when not making an API call on behalf of an intermediary or business (for example, making a call to the OAuth dynamic client registration API to register a software instance with ATO SSO/IdP):

• grant_type: must be "client_credentials"
• scope: scope(s) of the API(s) you want to call (if there are multiple scopes, separate each scope with a space)
• client_assertion_type: must be “urn:ietf:params:oauth:client-assertion-type:jwt-bearer”
• client_assertion: signed private key JWT (see: private key JWT creation).

An example request (with line breaks added for clarity) is

 POST /core2/connect/token HTTP/1.1 Host: auth.evte.ato.gov.au Content-Type: application/x-www-form-urlencoded  grant_type=client_credentials& scope=ato.super.stapledsuperfund.c%2Cr& client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer& client_assertion=<private_key_jwt>

An example using curl command

 curl POST https://auth.evte.ato.gov.au/core2/connect/token --header "Content-Type: application/x-www-form-urlencoded” --data "grant_type=client_credentials" --data "scope=ato.super.stapledsuperfund.c,r" --data "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer” --data "client_assertion=<private_key_jwt>"

For online service providers making an API call on behalf of an intermediary or business:

• grant_type: must be “urn:ietf:params:oauth:grant-type:jwt-bearer”
• scope: scope(s) of the API(s) you want to call (if there are multiple scopes, separate each scope with a space)
• client_assertion_type: must be “urn:ietf:params:oauth:client-assertion-type:jwt-bearer”
• client_assertion: signed private key JWT (see: private key JWT creation)
• assertion: signed grant JWT (see: grant JWT creation).

An example request (with line breaks added for clarity) is:

 POST /core2/connect/token HTTP/1.1 Host: auth.evte.ato.gov.au Content-Type: application/x-www-form-urlencoded  grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer& scope=ato.super.stapledsuperfund.c%2Cr& client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer& client_assertion=<private_key_jwt> assertion=<grant_jwt>

An example using curl command

 curl POST https://auth.evte.ato.gov.au/core2/connect/token --header "Content-Type: application/x-www-form-urlencoded” --data "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" --data "scope=ato.super.stapledsuperfund.c,r" --data "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer” --data "client_assertion=<private_key_jwt>" --data "assertion=<grant_jwt>"

Successful response

The successful invocation will result in a HTTP response of 200 OK containing a JSON object with the following elements:

• access_token: the opaque access token generated by the authorisation server
• token_type: set to ‘Bearer’
• expires_in: the lifetime of the token in seconds.

An example response is:

 { “access_token”:“ eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz…VUvZG”, “expires_in”:3600, “token_type”:“Bearer” }

Error response

Any unsuccessful invocation will result in a HTTP response of 400 (Bad Request Error) containing a JSON object with error - an error code describing the error from the set of errors defined by the OAuth 2.0 standard.

An example error response is:

 { “error”:“invalid_client” }

Step 3: Make calls to the API gateway

This step is applicable for both directly connected software and online service providers.

Once you have received an access token from the ATO SSO/IdP, you can use it in conjunction with your consumer key (API key) to make calls to the API gateway.

To meet the basic authentication requirements, in every API call, the following headers must be present:

• Authorization: Bearer <access token>
• apikey: <consumer key (API key)>

There may be additional requirements for specific APIs, so make sure you read the API documentation for the APIs you are calling.

Test credentials for sandbox testing

This section is applicable for both desktop service providers and online service providers.

For sandbox testing, use the credentials provided below. These credentials have been configured to enable you to test different use cases.

Credential information

If you do not already have access to the M2M keystore (to obtain your test M2M credentials), our Digital Partnership Office (DPO) will give you access to it when you have created a new API portal Team, or you can contact us.