Authentication and Authorization

Overview

VisualVault HTTP APIs use the OAuth 2.0 protocol for authentication and authorization. VisualVault supports common OAuth 2.0 security flows such as those for web server, installed, and client-side applications.

A simplified summary of the OAuth 2.0 protocol is that a registered client application (or a developer/service account) authenticates with an OAuth 2.0 Authorization Server and is then provided with an access token. Access tokens prove you have been authenticated and define what API resources you have access to. An access token is used to authorize each API request.

Authentication

Authentication is the process of verifying that someone or something is who they claim to be. Authentication requires evidence, known as credentials, to prove identity. User name and password are one such example of evidence used to prove identity.

OAuth2 authentication exchanges credentials for an access token using one of four security flows known as Grant Types.

OAuth2 Grant Types

Authorization Code

The Authoriation Code grant type prevents the client application from knowing the user's credentials and is appropriate for web-server based client applications which can receive an 'authorization code' and 'access token' via a callback URL. The web application may be configured to run inside a VisualVault i-frame (page viewer portal control).

The client id (API key) and client secret (API secret) are used to authenticate the client application, the user (resource owner) is prompted to grant access to the client application. If the user grants access, an authorization code is sent to the client application's redirect URL. The client application then exchanges the authorization code for an access token and refresh token.

The client application is responsible for storing the refresh token associated with each user. The persisted refresh token may be used to request a new access token up to the point the refresh token has expired. VisualVault allows you to define the refresh token expiration period when you register an application. The default token expiration period is 20 minutes.

Implicit

The Implicit grant type is intended for use where the client application is JavaScript running in a web browser. In this scenario, using the client secret (API secret) is not an option because the client secret would be exposed to anyone examining the script. The client application must be pre-registered along with its pre-defined callback URL. The client application sends its client id, redirect URL, and requested scope to the access token URL.

The client id (API key) and callback URL are used to authenticate the client application, the user (resource owner) is prompted to grant access to the client application. If the user grants access, an access token is sent directly back to the redirect URL. The implicit grant type does not support the use of refresh tokens.

Resource Owner Password Credentials

The resource owner password credentials grant type is suitable in cases where the user (resource owner) has a trust relationship with the client application. A mobile device application is an example of a suitable use case for this grant type where the user is prompted to enter their credentials and the client application has direct access to the user credentials. The client application directly exchanges the user credentials for an access token and refresh token. The client application may optionally persist the refresh token rather than storing the user credentials and use the refresh token for subsequent access token requests.

Client Credentials

The client credentials grant type is used in cases where the client application directly owns resources. This is essentially a 'service account' scenario where the client application is a VisualVault account rather than a registered application. The client application sends its client id (API key) and client secret (API secret) and directly exchanges its credentials for an access token and refresh token.

Authentication Steps

1. Log in and obtain an API Key/Secret
   • Login and obtain an API Key and API Secret available from a VisualVault account properties screen. Only accounts with administrative access may be issued an API Key/Secret at this time.
2. Obtain an access token from the VisualVault Authorization Server
   • Each API is a specific URL representing either a 'resource' or an 'action'. Before a client application can access private data using the VisualVault APIs, the client application must authenticate and obtain an Access Token. An access token grants access to APIs belonging to a specific scope. The scope you provide when requesting an access token determines the set of resources and operations the access token permits. A single access token can grant access to multiple APIs associated with the same scope.

Authorization

Authorization is the process of granting an authenticated identity access to resources or actions.

Authorization Steps

1. Send an access token to an API
   • After a client application obtains an access token, it sends the token to a VisualVault API in an HTTP "authorization" header. The documentation for each API resource includes an example of the HTTP request which includes the access token Authorization header.
   • Access tokens are valid only for the set of resources and actions requested in the scope of the access token request. For example, if an access token is issued for a VisualVault customer database (scope='vault'), it does not grant access to the VisualVault Administration API or other customer database APIs. You can, however, send that access token to multiple APIs within the same scope multiple times until the access token expires.
2. Refresh the access token if necessary
   • Access tokens have limited lifetimes defined by an expiration date returned with the access token. If your application needs API access beyond the lifetime of an access token, a refresh token may be used to obtain a new access token. When you request an access token a refresh token is also included in the HTTP response. Refresh tokens have a longer lifetime than access tokens and allow you to request a new access token without providing the client application credentials or end user credentials a second time.