OAuth Dynamic Client Registration API

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.

Back to top

Business usage and process flow

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

• Step 1: Create private key JWT
• Step 2: Request initial registration access token from ATO SSO/IdP
• Step 3: Register software instance via OAuth DCR API

The model for desktop and online service providers is the same.

Pre-Requisite Information

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.

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" }

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 }

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), signature = (public_certificate, private_key) )

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:clientassertion-
  type:jwt-bearer”
• client_assertion: signed private key JWT (see private key JWT creation).

An example request is

POST https://auth.evte.ato.gov.au/core2/connect/token HTTP/1.1 Content-Type:application/x-www-form-urlencoded grant_type:client_credentials scope: ato.idp.relyingParties.c' client_assertion_type:urn:ietf:params:oauth:client-assertion-type:jwtbearer' 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:

• access_token: this is the initial access token that will be used to call the oAuth DCR API for the initial registration of a software instance (next step)
• 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” }

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

Back to top

Scopes

Registration scope: ato.idp.relyingParties.c

Back to top

API risk rating

1 - No risk

For more information, see API risk rating.

Back to top

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.

Back to top

Production requirements

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

Back to top

Rate limit

Not applicable.

Back to top

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.