Authentication Guide

Client Auth

Initial Authorisation Request:

Make user go to auth server by making a request of type application/x-www-form-urlencoded

Parameters:

• response_type: either code (auth code), token (access token) or code_and_token (both, may be removed).
• client_id: client identifier. API key. Whatever.
• redirect_uri: where to send the user after auth
• scope: OPTIONAL. Access request scope. Space delim strings
• state: OPTIONAL. Used to maintain state. Auth server includes this in the callback

This MUST be done through GET (and some servers can optionally support POST).

In case of error, the redirect_url is used with error codes set.

Initial Authorisation Response:

• code: The auth code. ONLY INCLUDED IF REQUESTED.
• access_token: The access token. ONLY INCLUDED IF REQUESTED.
• expires_in: lifetime of the access token in seconds. OPTIONAL.
• scope: The valid scope of the access token. OPTIONAL.
• state: The state as given in the request. OPTIONAL.

The code is passed back as a URL parameter. The access_token an expires in are passed back on the fragment.

Error Response:

• error: the error code. See below
• error_description: OPTIONAL. Human readable description.
• error_uri: OPTIONAL. Human readable webpage with the error details
• state: OPTIONAL. State parameter as passed in the request.

Error Codes:

• invalid_request
• invalid_client
• unauthorized_client
• redirect_uri_mismatch
• access_denied
• unsupported_response_type
• invalid_scope

Access Tokens

Request:

HTTP POST to the needed endpoint.

Params:

• grant_type: either authorization_code, password, assertion, refresh_token, or none
• client_id: required unless inferred through some other means (e.g. assertion)
• scope: required scope of access token.

The client MUST also provide the parameters required for the authentication scheme.

Schemes:

Auth Code:

• code: the auth code already obtained
• redirect_uri: the redirect URI as used above.

Resource Owner:

• username: user’s username
• password: user’s password

Assertion:

• assertion_type: Assertion type as defined by the assertion server.
• assertion: The assertion

Refresh Token:

• refresh_token: the refresh token associated with the access token.

h2.Response:

Returned as JSON.

• access_token: The issued access token.
• expires_in: OPTIONAL. When the access token expires
• refresh_token: OPTIONAL. Refresh token for re-auth.
• scope: OPTIONAL. The valid scope of the token.

Errors: Just see the RFC. Section 4.3.1.

Making a Request:

Header field:

In the authorization header field, put OAuth

URI Param:

Put ?oauth_token= on the end of the URI.

Request Body:

Same as above, but put it in the actual request body.

In case of error, the error is placed in the WWW-Authenticate header, e.g.
WWW-Authenticate: OAuth realm=‘Example Service’, error=‘expired-token’
Also, HTTP 401 is returned.