OAuth Dynamic Client Registration API

Last modified
Version
1.0.69
Status
Active
On this page:

Description

The OAuth dynamic client registration (DCR) API enables you to register instances of your software with the ATO authorisation server (ATO SSO/IdP). This is based on the OAuth 2.0 Dynamic Client Registration Standard.

Registration with the ATO SSO/IdP is a pre-requisite step to using any other production API listed in the API catalogue. You will receive a unique client id as the output of your registration, which is used in the authentication process to call other APIs (see Client authentication).

In addition, you will receive a registration access token and a registration client URI which will be used in the future for lifecycle management of the software instance registration. 

All three of the client id, registration access token and registration client URI will need to be stored by the software product.

Business usage and process flow

The registration of a software instance via DCR involves the following steps:

The model for directly connected software and online service providers is the same.

Pre-Requisite Information

Generic registration client id
  • For production calls: ato_registration_client_id
  • For sandbox testing: ato_registration_client_id_eve

 

Registration scope

ato.idp.relyingParties.c

Token endpoints

 

Consumer (API) keys

 
  • 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.

M2M credential
  • You will need to extract the public certificate and public key of the M2M credential. See Extracting the public certificate and Extracting the private key.
  • If the M2M credential will expire within 6 months of registration, it will need to be renewed prior to registration of the software instance.

 

Step 1: Create private key JWT

The private key JWT is used in the client_assertion parameter in the request to the ATO SSO/IdP for a registration 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)
  • 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 registration client id
  • sub: must be the registration client id
  • 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": "ato_registration_client_id_eve", "sub": "ato_registration_client_id_eve", "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
  • private key – the private key of the signing certificate

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 2: Request initial access token from ATO SSO/IdP

Sending a request to ATO SSO/IdP

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

  • grant_type: must be "client_credentials"
  • scope: registration scope
  • 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.idp.relying.Parties.c& 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.idp.relying.Parties.c" --data "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer” --data "client_assertion=<private_key_jwt>"

Successful response – initial access token

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

An example response is:

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

This initial registration access token can only be used to call the OAuth DCR API.

Step 3: Register software instance via OAuth DCR API

Make a call to this OAuth DCR API to register a software instance with ATO SSO/IdP (refer to the OAuth DCR API specification).

To meet the authentication requirements, the following headers must be present:

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

A successful call will return a unique client id, registration access token (different from the initial registration access token generated in the previous step) and registration client URI for the registered software instance.

The client id is used in the authentication process to call other APIs. The registration access token and registration client URI will be used for future lifecycle management of the software instance registration. Therefore, all three must be stored by the software product.

Diagram

The basic steps for registering a software instance with the ATO SSO/Idp (as described above).

Scopes

Registration scope: ato.idp.relyingParties.c

API risk rating

1 - No risk

For more information, see API risk rating.

Test scenarios

The OAuth dynamic client registration test scenarios are given in the sandbox environment to guide you in the development of your software. We recommended testing to ensure an optimal user experience.

In addition to these scenarios, developers are free to conduct further validation testing against the API-specific response messages outlined in the relevant API documentation, without the need for setting up test data.

Production requirements

Before you can request production access for this API product, you must meet the requirements for production access.

Rate limit

Not applicable.

Response messages

For response messages specific to the OAuth DCR API, see OAuth dynamic client registration API - response messages.

For response messages common to all the APIs available in our API catalogue, see Common response messages.

Release notes

Business content updated 03 April, 2023.

Information to the following sections; business usage and process flow, scopes, test scenarios, production requirements, rate limit, response messages.

Version 1.0.69 released on 03 March, 2023.

This is an initial draft version of the API. It outlines the proposed open API specifications for review and feedback.