OAuth 2 API

OAuth 2 is an industry-standard protocol for authorization. The mechanism for APIs that allows applications to use time-limited tokens for access to resources. A common use case for the OAuth 2 API is when implementing a web application that uses the OS Data Hub APIs. As the user’s browser is not a trusted environment, the author of the web application should not embed the project API key in the application code, but they do need the application to be able to access the API.

Implementing a server backend

One solution to this paradox is to implement a server backend which requests OAuth 2 access tokens using stored authentication credentials. The server backend can then provide the access token to the frontend application code. Once the frontend application code has the access token, it can use it to make HTTP calls directly to any of the OS Data Hub APIs that have been added to your OS Data Hub project. In the near future when the access token expires, the frontend application should call into the server backend requesting a new token before making further OS Data Hub API calls.

Using this implementation pattern prevents end-users from seeing your API authentication credentials, and as a result helps to prevent use of your subscription limits outside of your application.

Hiding API credentials

Please note that using the OAuth 2 API in this way hides your API credentials from public view. However, you should take additional steps in your server backend to ensure that you do not hand out access tokens to unauthorised users. A common option is to only grant access to tokens once the user has logged into the application. Once the end-user has received an access token you cannot monitor or control their use of it, as they can now invoke the OS Data Hub APIs directly.

Implementing a proxy

An alternative way to protect your API key is to implement a server backend that acts as a proxy for the OS Data Hub APIs. Using this approach, the proxy should validate the users’ request before adding in your Project API Key and passing the request on to the OS Data Hub API endpoint. As each request is passing through your proxy, you can exercise fine-grained control over the requests that you allow through. Common options would be to check that the user is logged in before allowing access, and/or validating that the query that the application is making matches a list of permitted queries.

There is no inherent difference to the level of security provided by the OAuth 2 or Proxy approaches, as the API access credentials are stored server-side in both cases.

For more information about OAuth 2, please see oauth.net and aaronparecki.com.

Things to remember for OAuth2 API

You can:

• Create time limited access tokens.

• Hide your API access credentials from end-users.

• Restrict the available APIs within the project.

You can't:

• Restrict which data layers can be accessed using an access token.

• View mapping or data without making additional calls to the relevant APIs.