Authorization

Vernon Browser uses the OAuth 2.0 protocol to secure incoming API requests from clients. Currently, only the authorization code grant type is supported. Every incoming API request requires an access token to be included in the HTTP request headers (authorization header) in the following form:

Authorization Bearer <your access token>
e.g. Authorization Bearer some.access.token

API Keys

The client ID & client secret credentials are required to generate the access token. Both these credentials are generated when an API Key is created in Vernon Browser.

clientId - A unique code that identifies a client and is used when requesting an authorization code.
clientSecret - A secret for the client and when used along with authorization code can generate an access token.

The client secret should not be made public and if compromised the API Key must be revoked in Vernon Browser.

Authorization Flow

The authorization flow using the OAuth 2.0 authorization code grant type is a two-step process. The steps involve getting an authorization code and then exchanging the authorization code for an access token which subsequently can be used for making API requests.

Step 1 - Get the authorization code

Authorization Request

Send a request to following API endpoint to get the authorization code:

GET /api/v3/oauth/authorize

The following query parameters must be included while making this request:

clientId=<your client ID>
The client ID is generated when creating an API key in Vernon Browser.
responseType=code
Currently, Vernon Browser only supports OAuth 2.0 using authorization code grant type hence this value will always be "code".
redirectURI=<your registered redirect URI>
The redirectURI is useful when the authorization request is made by the client's web page however in most cases the authorization request will be made by a backend client application. In cases where a backend client is making the authorization request, the redirectURI can be set to the client application's URL.

The backend client application making the authorization request should be set to stop following redirects automatically.
Vernon Browser will send back an HTTP 302 response with the redirectURI. Avoid following redirects automatically to allow the backend client application to parse the authorization code from the HTTP response Location header.
state=<any random alphanumeric value>
The client should generate a random alphanumeric code for the state query parameter. The state will also be returned in the HTTP response by Vernon Browser. The client must verify that the value for the state sent with the request and the one received in the response match. If the state do not match then the client must refuse the authorization code.

The maximum length for the state query parameter is 255.
codeChallengeMethod=S256 or codeChallengeMethod=PLAIN
The only values permitted are either S256 or PLAIN.
If the client supports SHA256 hashing and Base64 URL encoding use S256 or else use PLAIN.
codeChallenge=<calculated alphanumeric value>
Generate a random alphanumeric code called code verifier.

When using code challenge method as PLAIN use the code verifier as the code challenge.
e.g. The PLAIN code challenge for code verifier f9752bd2-4346-439c-b14b-0c870b48ca82 is f9752bd2-4346-439c-b14b-0c870b48ca82

When using the code challenge method as S256 generate a SHA256 hash of the code verifier and then Base64 URL encode it i.e. Base64URLEncode(SHA256(code verifier)).
e.g. The S256 code challenge for code verifier f9752bd2-4346-439c-b14b-0c870b48ca82 is xnD-u3lQbKrV5sWVLtiVXZuv3Z32uwmrVd411_IsXT8=

Example

GET /api/v3/oauth/authorize?clientId=<your client ID>&responseType=code&redirectURI=<your registered redirect URI>&state=<any random alphanumeric value>&codeChallengeMethod=S256&codeChallenge=<calculated aphanumeric value>

Authorization Response

If the request is valid Vernon Browser will return a 302 response with the redirect URI, authorization code & state in the HTTP Location response header. Vernon Browser will return a bad request response (application/json) if any of the query parameters are not as expected.

The authorization code & state will be passed as query parameters to the redirect URI. Use the authorization code as quickly possible as it is a very short-lived token.

Example

302 https://<your.redirect.uri>?state=<state value sent in request>&code=<authorisation code>

Ensure the value of state returned from response matches the state that was originally sent while making the request. If they don't ignore the authorization code.

Step 2 - Get the access token

Access Token Request

Once the client has the authorization code it can exchange it along with the client secret for an access token. Send a request to following API endpoint to get the authorization code:

POST [application/json] /api/v3/oauth/token

The following parameters must be included in the request body (application/json) while making this request:

code: <authorization code>
The authorization code received in step 1.
grantType: code
The grant type would always be code.
redirectURI: <your registered redirect URI>
The registered redirect URI.
clientId: <your client ID>
The client ID is generated when creating an API key in Vernon Browser.
clientSecret: <your client secret>
The client secret is generated when creating an API key in Vernon Browser.
codeVerifier: <authorization code>
The code verifier that was generated in step 1.

Example

POST /api/v3/oauth/token


				{
				
   "code": "<authorization code received in step 1>",
				
   "grantType": "code",
				
   "redirectURI": "<your registered redirect URI>",
				
   "clientId": "<your client ID>",
				
   "clientSecret": "<your client secret>",
				
   "codeVerifier": "<code verifier generated in step 1>"
				
}

Access Token Response

If the parameters passed as part of the request body are as expected the server will issue the access token. Vernon Browser will throw a bad request if it fails to validate the credentials. The response from the server will always be in application/json format. The expiry in seconds for the access token is included as part of the response.

Example


			{
			
   "accessToken": "<access token>",
			
   "tokenType": "bearer",
			
   "expires": "<expiry in seconds>",
			
}

Basic authentication

Vernon Browser currently supports an easier form of authorization for clients who cannot use the OAuth 2.0. This is turned off by default and if you wish to use it contact us at vsl@vernonsystems.com and we can share the basic key.

Though the basic token is easier to implement, the trade-off is it is less secure and every API request requires additional validation which increases the response time. The increased response time might be acceptable in some cases if the client is harvesting the data rather than looking it up real-time from the client application.

Authorization Basic <your basic key>
e.g. Authorization Basic some.basic.key

The basic key never expires and if compromised must be revoked in Vernon Browser.