Introduction

The OAuth 2.0 authorization framework enables a third-party application (the client) to obtain limited access to an HTTP service on behalf of a resource owner (the end user). For instance, a tool for generating advanced meta analysis graphs (the client) could obtain access to read and possibly modify a review author's (the end user's) reviews in Archie.

The full specification of the OAuth 2.0 authorization framework can be found at: http://tools.ietf.org/html/rfc6749. In the following this is referred to as "the specification". 

Keycloack Keycloak is implementing all four authorization grant types or 'flows' described in the specification:

...

OAuth 2.0 can also be used for single sign on, i.e. the ability for the end user to log into the client using his or her Cochrane Account, by utilising the authentication part of the OAuth flow only, and not using the access token for further API calls. 

Registration

Before a client can use the system it must be registered with Keycloack Keycloak with the following information:

...

In addition, for the client credentials flow, an Keycloack Keycloak user must be associated with the client. The access token obtained with this flow will be associated with this user and the user's permissions.

...

• A confidential client is one that is capable of keeping its client credentials secret and the access token hidden from the end user. This typically means that a server has to be involved where the access token can be stored in a user session object. A confidential client is using the server-side flow to obtain the access token server-to-server without involving the browser, and in this process it authenticates itself to Keycloack using Keycloak using its client ID and client secret. Since this is the most secure type of client it has more privileges than a public client, e.g. the ability to refresh access tokens that are about to expire. Confidential clients may also use the client credentials flow to obtain an access token server-to-server without involving an end user.
• The typical example of a public client is a pure HTML5/JavaScript app. Since the source code and memory can be inspected by the end user in the browser this type of client is not capable of keeping the access token hidden from the end user. And since the client secret would be visible in the source code there's no point in assigning a secret to a public client. A public client is using the client-side flow to obtain short lived (e.g. 4 hours) access tokens. 

Endpoints

All endpoints require a secure connection (HTTPS). If plain HTTP is used an error status code 403 (forbidden) is returned.

For the VNO version of each endpoint, replace hostname with https://vno-account.cochrane.org

Primary endpoints

Authorization endpoint:

hostname/auth/realms/master/protocol/openid-connect/auth

...

hostname/auth/realms/master/protocol/openid-connect/token

Authorization Code Grant (server-side) flow

Step A: Authorization code grant

The server-side flow is optimised for confidential clients, although in theory it could be use by a public client. The first step is for the client to obtain an authorization code from KeycloackKeycloak.

The client directs the end user's browser (e.g. in a pop-up window) to the authorization endpoint with the following query parameters ("application/x-www-form-urlencoded" format) added to the endpoint URI:

...

code: The authorization code generated by KeycloackKeycloak.

state (optional): The state parameter provided by the client, if any.

In case of an error condition, depending on the error type, an error message will be displayed either directly to the end user (if there is a problem with the client ID or redirect URI), or it will be provided as an error parameter in the redirect URI to the client. For instance, if the end user does not give his or her consent, an "access_denied" error is returned to the client. See the specification section 4.1.2.1 for details.

Step B: Access token request

In the second step the client exchanges the authorization code with an access token server-to-server without involving the user's browser.

...

redirect_uri (optional): Required if the redirect_uri parameter was provided in step A, in which case the parameter must have the exact same value. This parameter is not used for redirecting at this step, only for added security.

Client authentication

For any call to the token endpoint, including this, the client must provide its credentials as Basic HTTP authentication with client ID as user name and client secret as password. The authentication must be provided in the Authorization header for a confidential client.

Before building the header for Basic authentication, client IDs and client secrets containing special characters including %, +, and all non-ASCII characters  must be encoded using the UTF-8 character encoding scheme first; the resulting octet sequence then needs to be further application/x-www-form-urlencoded (see section 2.3.1 of the specification). To build the header, the encoded credentials are separated by a colon, the resulting string is base 64 encoded, and the result is prefixed with "Basic ".

Access code response

The response to the POST request is a JSON object (MIME type "application/json") like this:

...

The first field is the actual access token which should be kept on the server and never passed to the end user's browser. The token_type will always be "Bearer" in this implementation. The number of seconds that the token is valid is given in expires_in. A refresh_token field is only returned if the access_type in step A is set to "offline".

Error response

In case of an error condition Keycloack Keycloak responds with a HTTP 400 status code with the error message included in the body of the response as a JSON object, e.g.:

...

For further details see section 5.2 of the specification.

Implicit Grant (client-side) flow

The client-side flow is optimised for public clients such as pure HTML5/JavaScript clients.

...

access_token: The access token issued by KeycloackKeycloak.

token_type: Always "Bearer" .

...

In case of an error condition, depending on the error type, an error message will either be displayed directly to the end user (if there is a problem with the client ID or redirect URI), or it will be provided as an error parameter in the fragment component of the redirect URI to the client. See the specification section 4.2.2.1 for details.

Resource Owner Password Credentials

The Resource Owner Password Credentials flow allows client to obtain an access token using resource owner's credentials (username and password). The Password grant is one of the simplest OAuth grants and involves only one step: client uses resource owner's username and password to make POST request to the server to exchange password for access token.  This authorization grant type requires that the application collect the user’s password.

...

• "none": The default, single sign on only, no access to data

• "person: Manage person records

• "group": Manage groups

• "document": Manage documents and reviews

• "workflow": Manage tasks and workflows

• "crs": Manage studies in CRS

• "crso": Manage studies in CRSO

• "linked_data": Access to linked data resources

• "all": Manage any resource type

Access Code Response

The response to the POST request is a JSON object (MIME type "application/json") like this:

{
    "access_token": "3e8ec1a3d43c983b57df0616b498c04807b466e919999aa0f3f3aabca1dd48cc",
    "token_type": "Bearer",
    "expires_in": "14400"
}

Client Credentials Grant flow

The client credentials flow allows a confidential client (server) to obtain an access token server-to-server without involving an end user. Before this flow is used, an Keycloack Keycloak user must be associated with the client. The access token obtained with this flow will be associated with the user and the user's permissions.

...

Authentication must be provided in the Authorization header as described for the Authorization Code Grant under client authentication.

Access code response

The response to the POST request is a JSON object (MIME type "application/json") like this:

...

The access_token field contains the actual access token. The token_type will always be "Bearer" in Keycloack implementationKeycloak implementation. The number of seconds that the token is valid is given in expires_in.

Error response

In case of an error condition Keycloack responds Keycloak responds with a HTTP 400 status code with the error message included in the body of the response as a JSON object, e.g.:

...

{
    "user_name": "testuser",
    "scope": "document",
    "expires_in": "2410",
    "client_id": "my_account",
    "person_id": "11143"
}

{
    "user_name": "testuser",
    "scope": "person",
    "expires_in": "3192",
    "client_id": "my_account",
    "person_id": "11143",
    "user_id": "08573771072139469457090803092242",
    "name": "Test User",
    "first_name": "Test",
    "last_name": "User",
    "email": "test-user@cochrane.org",
    "permissions": [
        {
            "resource": "person",
            "entity": "D37BDF5182E26AA2013C72096D0CE6B1",
            "grants": ["view", "view_private", "write"]

        }
    ]
}

Refreshing an access token

Refresh tokens can be used to obtain a new access token without asking for the end user's consent. Access tokens expire after 4 hours unless they are revoked. Refresh tokens are valid for 180 days or until they are used to obtain a new access token.

...

Using an access token to access the API

The access token must be passed to the API in the Authorization header, e.g.:

...

See Review Document API for more examples.

Checking permissions for a single review

As another example, the API contains a method to get the user's permissions for a single review:

...