This article applies to VDG Sense 2.6.7 and before. OAuth2 is not used anymore in VDG Sense 2.6.8 and later version.
What is OAuth2?
OAuth2 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service. It works by delegating user authentication to the service that hosts the user account, and authorizing third-party applications to access the user account. OAuth2 provides authorization flows for web and desktop applications, and mobile devices.
Open standard for authentication
Authorizing third-party applications
Developed for HTTP
Why OAuth2?
OAuth was created as a response to the direct authentication pattern. This pattern was made famous by HTTP Basic Authentication, where the user is prompted for a username and password. Basic Authentication is still used as a primitive form of API authentication for server-side applications: instead of sending a username and password to the server with each request, the user sends an API key ID and secret. Before OAuth, sites would prompt you to enter your username and password directly into a form and they would login to your data.
It enables apps to obtain limited access (scopes) to a user’s data without giving away a user’s password. It decouples authentication from authorization and supports multiple use cases addressing different device capabilities. It supports server-to-server apps, browser-based apps, mobile/native apps, and consoles/TVs.
Problems before OAuth2
Apps store the user’s password
Apps get complete access to user’s account
Users can’t revoke access to an app except changing their password
Compromised apps export the user’s password
Definitions
Resource owner: end-user
The resource owner is the user who authorizes an application to access their account. The application's access to the user's account is limited to the "scope" of the authorization granted (e.g. read or write access).
Authorization service: OAuth2 endpoints
The resource server hosts the protected user accounts, and the authorization server verifies the identity of the user then issues access tokens to the application. From an application developer's point of view, a service's API fulfills both the resource and authorization server roles.
Resource service: REST endpoints
The resource service handles authenticated requests after the application has obtained an access token. The resource service hosts the protected resources like users, devices, etc.
Clients: websites and (mobile) apps
The client is the application that wants to access the user's account. Before it may do so, it must be authorized by the user, and the authorization must be validated by the API.
Other definitions
Grants: authentication flows
Codes: temporary authorization strings
Secrets: client passwords (not user)
Tokens: temporary ‘session keys’
Application Registration
Before using OAuth with your application, you must register your application. This is done in the web configurator of VDG Sense (https://localhost/config), where you will provide the following information:
Application Name
Grant Types
Redirect URI or Callback URL (optional)
In case of the authorization grant, the redirect URI is where the service will redirect the user after they authorize (or deny) your application, and therefore the part of your application that will handle authorization codes or access tokens.
Client ID and Client Secret
Once your application is registered, the web config will issue "client credentials" in the form of a client identifier and a client secret. The Client ID is a publicly exposed string that is used by the service API to identify the application, and is also used to build authorization URLs that are presented to users. The Client Secret is used to authenticate the identity of the application to the service API when the application requests to access a user's account, and must be kept private between the application and the API.
Tokens
Access tokens are the token the client uses to access the Resource Service. They’re meant to be short-lived; 1 hour. You don’t need a confidential client to get an access token. You can get access tokens with public clients. They’re designed to optimize for internet scale problems. Because these tokens can be short lived and scale out, they can’t be revoked, you just have to wait for them to time out.
The other token is the refresh token. This is much longer-lived; 90 days. This can be used to get new tokens. To get a refresh token, applications typically require confidential clients with authentication.
In future releases the refresh token can be revoked. When revoking an application’s access in the web configurator, you’re killing its refresh token. This gives you the ability to force the clients to rotate secrets. What you’re doing is you’re using your refresh token to get new access tokens and the access tokens are going over the wire to hit all the API resources. Each time you refresh your access token you get a new cryptographically signed token.
The OAuth spec doesn’t define what a token is. VDG Sense uses JSON Web Tokens. In a nutshell, a JWT (pronounced “jot”) is a secure and trustworthy standard for token authentication. JWTs allow you to digitally sign information (referred to as claims) with a signature and can be verified at a later time with a secret signing key.
Tokens are retrieved from endpoints on the authorization server. The two main endpoints are the authorize endpoint (/oauth/authorize/) and the token endpoint (/oauth/token/) . They’re separated for different use cases. The authorize endpoint is where you go to get consent and authorization from the user. This returns an authorization grant that says the user has consented to it. Then the authorization is passed to the token endpoint. The token endpoint processes the grant and return the tokens.
You can use the access token to get access to APIs. Once it expires, you’ll have to go back to the token endpoint with the refresh token to get a new access token.
Grant Types
Client Credentials Grant
The client credentials grant type provides an application a way to access its own service account. Examples of when this might be useful include if an application wants to update its registered description or redirect URI, or access other data stored in its service account via the API. This grant is only available to products produced by TKH Security.
Clients
Native apps
Password Grant
With the password grant type, the user provides their service credentials (username and password) directly to the application, which uses the credentials to obtain an access token from the service. This grant type should only be enabled on the authorization server if other flows are not viable. Also, it should only be used if the application is trusted by the user (e.g. it is owned by the service, or the user's desktop OS).
Clients
Native apps
Authorization Code Grant
The authorization code grant type is the most commonly used because it is optimized for server-side applications, where source code is not publicly exposed, and Client Secretconfidentiality can be maintained. This is a redirection-based flow, which means that the application must be capable of interacting with the user-agent (i.e. the user's web browser) and receiving API authorization codes that are routed through the user-agent. Supports PKCY against interception attacks
Clients
Native mobile apps
Server-side web apps
Refresh Token Grant
After an access token expires, using it to make a request from the API will result in an "Authentication error". At this point, if a refresh token was included when the original access token was issued, it can be used to request a fresh access token from the authorization server. Available to clients with Password Grant and Authorization Code Grant.
Clients
Native clients
Native mobile apps
Server-side web apps
Example
Request the list of users without any authentication. The resource service will return an authentication error.
GET https://localhost/api/v1/users
401 Unauthorized
{
"status": 401,
"name": "access_token",
"message": "jwt must be provided"
}
|
Request an access token with for example the password grant. The basic authentication header contains the client id and secret.
POST https://localhost/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic dkJuMzdDM3NSSld0VzNYRDpLa0xKNTZZaFU3Tlc4YnFCZ2JxVzhjenI=
grant_type=password&username=administrator&password=!DVadmin
200 OK
{
"access_token": "eyJhbGciOiJSUz...6LgjQmpFjw",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "0f6eef93...709f2b8d"
}
|
Request the list of users with the access token in the authorization header.
GET https://localhost/api/v1/users/
Authorization: Bearer eyJhbGciOiJSUz...6LgjQmpFjw
200 OK
{
"href": "https://localhost:443/api/v1/users?offset=0&limit=25",
"offset": 0,
"limit": 25,
"first": {
"href": "https://localhost:443/api/v1/users?offset=0&limit=25"
},
"previous": {
"href": null
},
"next": {
"href": null
},
"last": {
"href": "https://localhost:443/api/v1/users?offset=0&limit=25"
},
"count": 2,
"items": [
...
]
}
|
LegacyAPI
The legacy API are all endpoints that start with "/command" in path of the url. For authentication the VDG Sense legacy API supports HTTP Basic, BasicXML and DigestXML. In the OpenAPI passwords will be securely stored with a bcrypt hashing algorithm. Besides incorporating a salt to protect against rainbow table attacks, bcrypt is an adaptive function: over time, the iteration count can be increased to make it slower, so it remains resistant to brute-force search attacks even with increasing computation power. Because of this, the authentication calls will become much slower. In VDG Sense 2.6 the these authentication methods remain functioning. We advise you to no longer use HTTP Basic and use one of the other authentication methods. When using BasicXML or DigestXML, authenticate once and reuse the session key for all other request. Instead of requesting a new session key over and over again, keep it alive by executing any legacy API request.To increase the security of your integration we advise you to implement one of the new OAuth2 authentication flows. This way you no longer require to store passwords and all traffic will go over a secure connection. Once you retrieved an access token as described in an earlier chapter, you can request a session key for the legacy API.
POST https://localhost/webservice Content-type: application/xml <?xml version='1.0'?> <AuthenticateAccessToken> <token>eyJhbGciOiJSUz...6LgjQmpFjw</token> </AuthenticateAccessToken> <?xml version='1.0' encoding='UTF-8'?> <AuthenticateAccessTokenResponse> <result>OK</result> <sessionkey>275000862</sessionkey> </AuthenticateAccessTokenResponse> |
Depreciation Warning
In a future release of VDG Sense we will depreciate the old authentication methods (HTTP Basic, BasicXML and DigestXML). In the meantime we strongly advise you to start implementing the OAuth2 flows and the method above to request a session key. Session keys will also be dropped in this future release. You will be able to use the access token as a bearer token in the authorization header like all resources in the new OpenAPI.
GET https://localhost/command?command=getDeviceList Authorization: Bearer eyJhbGciOiJSUz...6LgjQmpFjw 200 OK <result errorcode='0'> <devices count='1'> <device> <name>[string]</name> <serverid>[uid]</serverid> <deviceid>[uid]</deviceid> <status>[string] </status> <type>[string] </type> <brand>[string] </brand> <location>[string] </location> <ptztype>[string]</ptztype> <ipaddress>[ip-address]</ipaddress> <port>[number]</port> </device> </devices> </result> |