Overview:
This document contains information and instructions for performing OAuth 2.0 authorization and authentication with NowInfinity’s auth server when consuming Nowinfinity API's. The Nowinfinity OAuth flows are categorised into three flows.
Terminology
| OAuth Term | Meaning | Mapping to NowInfinity |
| Resource Owner | An entity capable of granting permission to access a protected resource. If this is a person then it is referred to as the “end-user”. | NowInfinity user |
| Resource Server | The server hosting the protected resource. | NowInfinity platform |
| Client | An application wanting to access the protected resource on behalf of the resource owner, such as GreatSoft. | External app connecting to NowInfinity api |
| Auth Server | The server issuing tokens to the client after successful authentication and authorisation of the resource owner. | NowInfinity Auth Server |
Supported OAuth Flows
NowInfinity supports the following OAuth 2.0 flows:
| Flow | Description and usage |
| Authorization Code | The preferred method of connecting to the NowInfinity api for server-side applications such as ASP.NET and similar. |
| Resource Owner | Basic authorisation using your NowInfinity account username and password. |
Authorisation Code Grant Flow
Authorization Code grant flow is the method of integrating with the NowInfinity API for server-side applications such as those built using ASP.NET. The source code of the application won't be shown to the public, the client application will not see the users credentials. The client is issued an authorization code and access token.
Authorisation Code grant flow consists of the following steps:
- The client redirects the end-user to the auth server to request permission to access the user’s data.
- When permission is granted, the auth server returns the end-user to the client and provides a unique code that can be exchanged for a JWT auth token.
- The client sends the unique code to the auth server.
- The auth server returns a JWT security token to the client.
Step 1: Request authorisation code
The client redirects the end-user to NowInfinity’s auth server, where the end-user grants permission for the client to access their NowInfinity data.
NowInfinity auth server url to redirect the end-user to:
https://auth.nowinfinity.com.au/connect/authorize
Request query string parameters to provide:
| Parameter | Description | Value to use |
| client_id | Identifies the client to NowInfinity | Client ID provided to the client by NowInfinity. |
| redirect_uri | Url back to the client app to return the user to after authentication. | Determined by the client. |
| response_type | This effectively identifies the particular OAuth grant flow being used. This should always be the value “code” for Authorisation Code grant flow. | This value: code |
| scope | A space-delimited set of scopes requested by the client. Scopes identify the type of access the client wants into the resource server. | This value: api1 offline_access read write |
| state | Optional CSRF token provided by the client and returned back to the client via their redirect_uri parameters. Enables to client to correlate requests with responses. | Guid or similar unique identifier provided by the client. |
| display | Optional parameter allowing the client to specify whether the auth server interface should appear as a popup vs regular web page. | Specify value “popup” for the auth UI to display in a popup. Omit to display in a regular web page. |
Example URL:
https://auth.nowinfinity.com.au/connect/authorize?client_id=my_client_id&redirect_uri=http%3A%2F%2Fmysite.com&response_type=code&scope=api1%20offline_access%20read%20write
If all query string parameters are correct, the user will be presented with a UI requesting them to log in to their NowInfinity account (this step will be skipped if the user is already logged into their NowInfinity account):
If an incorrect client_id or redirect_uri is specified in the query string then the user will be presented with an error message similar to:
Upon logging into NowInfinity, the user will be presented with a UI prompting them to grant permission to the client to access their NowInfinity data:
When the user allows the grant, their web browser will be redirected to the redirect_uri. The redirect will contain a query string parameter “code” whose value is a unique code that the client can then exchange for a JWT security token.
The following query string parameters may be provided in the redirect:
| Parameter | Value |
| code | Unique code that the client can exchange for a JWT. |
| state | The value of the state parameter originally provided by the client, if the client provided a state parameter. |
http://localhost:45343/?code=7d24e738a7afb14208ca1099ee312ab4
Step 2: Exchange authorisation code for security token
The client sends the authorisation code to NowInfinity’s auth server to exchange it for a security token. This security token can then be used to query the NowInfinity api to access the end-user’s data.
NowInfinity Auth server token exchange url:
https://auth.nowinfinity.com.au/connect/token
Request form fields to supply:
| Parameter | Description | Value to use |
| grant_type | Identifies the purpose of the request (effectively) | This value: authorization_code |
| client_id | Identifies the client to NowInfinity | Client ID provided to the client by NowInfinity. |
| client_secret | Authenticates the client with NowInfinity | Client secret provided to the client by NowInfinity |
| redirect_uri | Url back to the client app to return the user to after authentication. | The same redirect_uri value as was used in step 1 |
| code | The authorization code obtained in step 1 | The authorization code obtained in step 1 |
NowInfinity’s auth server returns a security token if the request was successful.
Example successful request response body:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InB4Z3BZakJBX3VzZENhMTd0VWM4cmFDam9tYyIsImtpZCI6InB4Z3BZakJBX3VzZENhMTd0VWM4cmFDam9tYyJ9.eyJpc3MiOiJodHRwczovL2F1dGgtZHVibGluLmxlby5ub3dpbmZpbml0eS5jb20uYXUiLCJhdWQiOiJodHRwczovL2F1dGgtZHVibGluLmxlby5ub3dpbmZpbml0eS5jb20uYXUvcmVzb3VyY2VzIiwiZXhwIjoxNTk5NTI0MDA4LCJuYmYiOjE1OTk1MjM2NDgsImNsaWVudF9pZCI6Im1hdHRAbm93aW5maW5pdHkuY29tLmF1X2NvZGUiLCJzY29wZSI6ImFwaTEiLCJzdWIiOiI0ZWU3YWJkYi1iZDMyLWUHJcbiAgXCJoZWFsdGgtY2VudGVyXCIsXHJcbiAgXCJoZWFsdGgtY2VudGVyLXBhZ2VcIixcclxuICBcImluZGl2aWR1YWxzLXJlZ2lzdHJ5XCIsXHJcbiAgXCJwZW5kby1lbmFibGVkXCIsXHJcbiAgXCJzZlwiXHJcbl0iLCJhbXIiOlsicGFzc3dvcmQiXX0.ppno3uZxRNLFtgWsO4uaXeABeAe4HLZ1Q2NwJrtKR3Jz63wjjVxWyfbpasClcwphhx93eVOlXxORC0t7yT9pDjKTj3FOTPalcY561dRBYVjqBfXkmhK5UIAWVklKd59aVKtfn5Ak9JiVQvcQrH7e3iWawTAwDFbSVF4pRn7bHzfilW1VckBxmX7idGE_lxlxdj8s4jHHF8SnU6dun_ZcPUmghtKfJcrOyeCti-tSKp6-8WP6T9dvZEc4nxlBMtBMfX6uyxi6jcojE-6I-Y754EHAEbyPE7-sEUQjI3F3Fze7tf-O3eKr6M28tZ8oCaMn3z1IMOsx_UBxKV99gKaYTw",
"expires_in": 360,
"token_type": "Bearer",
"refresh_token": "222f4988703c8a36b8bcd4191b776063"
}Example response when any of the request body values (grant_type, client_id, client_secret, redirect_uri or code) are incorrect:
{
"error": "invalid_grant"
}