Support centre

Three-Legged OAuth2 Authentication

Last Updated: Nov 24, 2017 01:48PM NZDT

Some APIs at api.business.govt.nz require an end user to provide consent for the API to access a system on their behalf, including the Companies API and some operations for the NZBN API. This requires the use of a three-legged OAuth2 token for authentication and authorisation, which is a more complex integration than the standard  two-legged authentication.

 

This article explains:

For details on how to revoke tokens and use tokens in API calls see our other support article on OAuth2 use for MBIE APIs.

 

Application registration

You will need to have registered at API Explorer and have subscribed to an API that requires end user authorisation, such as the Companies Maintenance API.

 

You also need to provide a callback URL to receive a code during the token generation process. This URL needs to be entered for the application that you have subscribed with.

 

Note: The name of the application that you subscribe with will be presented to end users during the authorisation process.

 

 

Generating a Three-Legged Token

The sequence for obtaining consent from a user for your software to act on their behalf is:

  

1. Software initiates authorisation flow

 

Your software invites a user to allow your product to access their business information on the Companies Register (e.g. “Would you like to be able to use [PRODUCT NAME] to maintain your company information for you?”).

  

2. Software directs user to log in

 

If the user agrees, the software sends an OAuth Authorize API call to https://api.business.govt.nz/oauth2/authorize.

Parameter

Description

response_type

REQUIRED. Value MUST be set to "code".

client_id

REQUIRED. The Consumer Key for the application you have subscribed with. You can get this from the My Subscriptions screen.

redirect_uri

REQUIRED. The callback URI for the application, as set in the My Applications screen.

scope

REQUIRED. Set to the scope required by the API that the token is to be used with.
For NZBN and Companies APIs use openid
For PPSR sandbox API use PPSR:manage

state

RECOMMENDED. An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting back to the application.

Example:

GET https://api.business.govt.nz/oauth2/authorize?scope=openid&response_type=code&redirect_uri=https://www.mycompaniesapp.co.nz/MBIE-OAuth-Callback&client_id=ABCDE12345XYZ789&state=b4fa9af1-a29d-4093

 

 

3. Login page presented

 

The API Authorisation Server redirects the user’s browser to a login page as shown below, where the user enters their RealMe credentials as used on the system that the API is accessing (e.g. Companies Register).


  

4.User gives consent

 

The API Authorisation Server presents the request shown below for the user to confirm that your product has consent to access their resources. Note that the name of your subscribed application is presented to the user.



 

  

5. Authorisation Server sends your software the result of consent

 

If the user approves access then the API Authorisation Server sends an authorisation code, and the state value if included in the request, back to the application’s callback URL. E.g.

 

https://www.mycompaniesapp.co.nz/MBIE-OAuth-Callback?code=abcdeb1c730bc6f370c25103f596840&state=b4fa9af1-a29d-4093

 

If the user denies access the Authorisation Server will send e.g.

 

https://www.mycompaniesapp.co.nz/MBIE-OAuth-Callback?error= access_denied&error_description=User%20denied%20access&state=b4fa9af1-a29d-4093

  

6. Software gets OAuth token

 

Your software retrieves a three-legged OAuth token by calling the token API at  https://api.business.govt.nz/oauth2/token using these parameters:

Parameter Name Parameter Type Description
Content-Type: Header application/x-www-form-urlencoded
Authorization Header Basic access authentication

Basic <consumer_key:consumer_secret>
 
Where consumer_key:consumer_secret are base64 encoded
 
E.g. if consumer_key is MyKey and consumer_secret is MySecret:
Authorization: Basic TXlLZXk6TXlTZWNyZXQ=
code Query Code as returned in step 5
grant_type Query authorization_code
redirect_uri Query The callback URI for the application that the API subscription is under.

 

Example:


POST https://api.business.govt.nz/oauth2/token?code=abcdeb1c730bc6f370c25103f596840&grant_type=authorization_code&redirect_uri=https://www.mycompaniesapp.co.nz/MBIE-OAuth-Callback

cURL request:

curl "https://api.business.govt.nz/oauth2/token?code=abcdeb1c730bc6f370c25103f596840&grant_type=authorization_code&redirect_uri=https://www.mycompaniesapp.co.nz/MBIE-OAuth-Callback" --user "ABCDE12345XYZ789:TestPassword" -X POST
 

  

Example response:


{
  "scope": "openid",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "abcdef67f14b793880bc87633198765",
  "id_token": "eyJhbGciOiJSUzI1NiIsIng1dCI6Ik56QmxZV0ZrTnpCalpqVXdNVE0yT1dZd05tUTRPR00zTVdSa1ptWTRNbUkzWXpKbU1EZGtNUSJ9.eyJhdXRoX3RpbWUiOjE0Nzg2NDMwNjUsImV4cCI6MTQ3ODY0NjY2NSwic3ViIjoiQUtMMUZGNTk1OUI5RkFCNEYwMDgxNEQ5NzAxRDA5MjA3QjBAY2FyYm9uLnN1cGVyIiwiYXpwIjoiTWxLcmlTRWNBQXhodnA1R1VlbXl4b3JvR3A0YSIsImF0X2hhc2giOiI3dnpjN1F3Z0NLSVBicXBZUWgzbTBBIiwiYXVkIjpbIk1sS3JpU0VjQUF4aHZwNUdVZW15eG9yb0dwNGEiXSwiaXNzIjoiaHR0cHM6XC9cL2FwaS5lYXQuYnVzaW5lc3MuZ292dC5uejo0NDNcL29hdXRoMlwvdG9rZW4iLCJodHRwOlwvXC93c28yLm9yZ1wvY2xhaW1zXC9yb2xlIjoiTUJJRVN1YnNjcmliZXIiLCJpYXQiOjE0Nzg2NDMwNjV9.Z5dCCZ4qv_988Y0eMMsRmAg6uuIlh8-gIqPVG1SnySF_YzFsvH6cmDvUWg7gqG88OaHHog1apqHbzX36BeBPKZpCRb0T-rjbZgeI00PJVRLeFqHpdyX8hRLwVdLVyjCTNo0z0ITetMQYTvHsFT6W2gqSOE_pWFn9aKmp6IJl2_36Kl35Zpfc4ZZfnvxxMmny0JhmNAEKb8lA0y_nJCW16Go3uI9Cchc2HW1aWtmyZwVPV5YHaokOPMqxWrOcS7yx0GHPHlJYcuZzzPf8V9tbuOMI952TUKKwTNre6sxTHFKIG0z0215D3VyxN3-AZhUivAoWTVpoTJKTm9_LV_SySVbL8E5WKuENKq6wJ1ZUgOCRTFSRvFSX0JlrHTLo0CzgUugWp0iiuz-8rjCgzmdhC2jVQLrs94c06AsgNsMdgsj2_31DPV0MoG13i7JgXpainZjdSNR0eCC3AvJ5p-Nc7kJyobqGz75b8hlpqsp0lE1B6gl765rKZLno1uPJvjbQMVUEFjvdrz4MQVaVv-biDEcldFBa6OWWSQbrl2cadXmNrmcMLz7moUoNYzt9J2Skv9yBIkOsbUWVNMnnZ_oGRKZ-f-VD-1s8n6wKnVCmRNdHu82dNG0nyzhFpoEAL7ZhaGfvLGDw_cEfa_KWnH5O9TwaH0nEM_JyBjojdKTwMN4",
  "access_token": "daf1c973029cd6cfb5debfaca40764d5"
}

 
Response Parameter Name Description
Expires_in Time to expiry for token (seconds). The access token has a one hour expiry time. The refresh token may be used to generate a new access token after that time, without requiring the end user to go through the consent process again.
Access_token Authorization that needs to be passed in the http request header for the API call.
Refresh_token This token can be used to get a new token once an access_token expires. Refresh tokens are valid for 14 months. If the refresh token is not used to generate new tokens in that time then the end user will need to provide consent again.

  

7. Software stores token

 

Your software stores the access and refresh tokens for use in future API requests that require that user’s consent.  The access token is passed in the Authorisation header of an API call.

  

Using the Refresh Token

The refresh token can be used to generate a new access token after one has expired, without requiring the end user to go through the consent process again.

 

Call the token API at  https://api.business.govt.nz/oauth2/token using these parameters:

Parameter Name Parameter Type Description
Content-Type: Header application/x-www-form-urlencoded
Authorization Header Basic access authentication

Basic <consumer_key:consumer_secret>
 
Where consumer_key:consumer_secret are base64 encoded
 
E.g. if consumer_key is MyKey and consumer_secret is MySecret:
Authorization: Basic TXlLZXk6TXlTZWNyZXQ=
refresh_token Query The refresh_token value as returned from the previous call to the token API.
grant_type Query refresh_token
 

 

Example:


POST https://api.business.govt.nz/oauth2/token?grant_type=refresh_token&refresh_token=abcdef67f14b793880bc87633198765

 

cURL request:

curl "https://api.business.govt.nz/oauth2/token?grant_type=refresh_token&refresh_token=abcdef67f14b793880bc87633198765" --user "ABCDE12345XYZ789:TestPassword" -X POST
 

The response is the same as the call to the token API shown in step 6 above.




Contact us

Call us

  • 0800 624 301

06331954b2882b2fe5350819c54a3b70@mbieapi.desk-mail.com
https://cdn.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete