The authorization chapter was really exiting, we got to delve into the gritty details and ended up with the much sought after Access token. This chapter is admittedly not as exciting. It’s more a transport stage between getting the Access token and actually using the different services.
This chapter is about aID’s general way of using web services. What you learn here can be used for all our services, and most other web services that support OAuth access tokens as well.
aID follows the specification set by in RFC-6750 to use OAuth Access tokens with web services.
We assume that you have a valid Access token, nothing will work without it. In the examples, this token will be d4bbad00. The service used in the examples here doesn’t exist, neither does the access token. So don’t expect these examples to work, replace the service URLs with the real one you need to use, and the access token with your real token.
Providing access token
There are three different ways of sending the Access token to the webservices. The first is to use a HTTP header, this is the recommended way of sending the Access token. The second alternative is to use a query parameter, and the third is to use a form-encoded body parameter, which doesn’t make sense for GET requests.
If possible, please use the first method. This keeps the access token from ending up in access logs etc. by mistake.
By Authenticate HTTP header
The best way to provide the access token is as a bearer token in the Authorization HTTP header, like this:
The HTTP request needs to have a HEADER present called “Authorization”. The value of this header needs to start with “Bearer”, then a space followed by the access token provided after OAuth authentication.
Authorization: Bearer <your access token here>
If possible, this method should be used. If it’s not possible, you’re probably sending the Access token to a browser and using it in Ajax requests or something, which is a very bad idea. The Access token should only be used between servers, if used in Javascript, the token can leak everywhere (evil ads etc. can steal it).
By access_token URI query parameter
The alternative for GET requests is to provide the access token as a parameter called “access_token”, like this:
For POST requests and other requests with Content-Type set to “application/x-www-form-urlencoded”, the Access token can be sent as a body parameter, like this:
$ curl-X POST -d"access_token=d4bbad00" https://www.aid.no/api/vespasian/v1/test
{"status":"success"}
This will NOT work for GET requests.
Errors
OAuth 2.0 provides no way of telling a Client Application that an Access Token is no longer valid, so each call to a web service comes with an inherent risk of failing. It’s the responsibility of the Client Application to handle failures in a graceful manner that will affect the user as little as possible.
RFC-6750 lists three common errors. These have been implemented in aID and are explained here. These errors will set a WWW-Authenticate header in the HTTP response, and also provide a common response body. If possible, please use the header and not the response, the header is the only RFC-6750 standard response. The body might change to adhere to other standards for web services.
These error responses described here are only related to the OAuth aspect of the endpoints they will respond to. The various endpoints might implement a multitude of other responses as well, but these responses will be sent if something is broken regarding the use of OAuth Access tokens.
invalid_request
This response signifies that the request can not be handled as an OAuth request.
The following applies for invalid_request responses:
Response code: 400
Sets HTTP response header WWW-Authenticate to error="invalid_request"
Sets HTTP response header Content-Type to application/json
Response body to: {"error":"invalid_request"}
When this response is given, the caller has not provided an Authorization header containing Bearer and an access token, and not provided an access_token parameter. Only one of these are required for a given request, this response means that none are provided.
This usually means that something is wrong with the implementation at the client side.
Example:
HTTP/1.1 400 Bad RequestWWW-Authenticate: error="invalid_request"Content-Type: application/json
{"error":"invalid_request"}
invalid_token
This response signifies that the provided access token is not valid, for some unknown reason.
The following applies for invalid_token responses:
Response code: 401
Sets HTTP response header WWW-Authenticate to error="invalid_token"
Sets HTTP response header Content-Type to application/json
Response body to: {"error":"invalid_token"}
When this response is given, the Client Application can delete the provided access token, and ask the user to log in by sending the user to the Authorize endpoint endpoint.
This response signifies that the provided access token is valid, but the current resource requires a wider scope than provided by the token.
For example if the access token was provided for an authorization request with scope=id+name, and the current endpoint requires the access scope, an insufficient_scope error is returned.
The following applies for insufficient_scope responses:
Response code: 403
Sets HTTP response header WWW-Authenticate to error="insufficient_scope"
Sets HTTP response header Content-Type to application/json
Response body to: {"error":"insufficient_scope"}
When this response is given, the Client Application can decide between handling this as a normal situation, and just ignore this endpoint or ask the user to log in again with a wider set of scopes (ie. scope=id+name+access in the Authorize endpoint endpoint).