OAuth2

What is it?

OAuth2 is summarized in RFC 6749 as follows:

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

Here is an overview of how the process works:

OAuth2 workflow diagram

The OAuth2 App

OAuth2 support is available in ownCloud via an OAuth2 application which is available from the ownCloud Marketplace. The app aims to:

  1. Connect ownCloud clients (both desktop and mobile) in a standardized and secure way.

  2. Make 3rd party software integrations easier by providing an unified authorization interface.

Requirements

To use the OAuth2 app, your ownCloud installation will need to meet the following dependencies:

  • Apache: If you are hosting your ownCloud installation using the Apache web server, then mod_rewrite and mod_headers modules must be installed and enabled.

    1. Redis: You will need to have a Redis server available, ideally the latest, stable, version

    2. PHP: You PHP installation must have the phpredis extension (>= 4.2) installed and enabled.

      We strongly recommend that you configured PHP to store sessions in Redis. Here is an example configuration.

      ; Redis configuration
SESSION_SAVE_HANDLER=redis
SESSION_SAVE_PATH=tcp://[REDIS_SERVER]:6397
REDIS_SESSION_LOCKING_ENABLED=1
REDIS_SESSION_LOCK_RETRIES=750
REDIS_SESSION_LOCK_WAIT_TIME=20000

      The configuration parameters above are taken from the available ones. According to an issue in the phpredis repository, the default values are too small for common usage. It suggested using the ones above instead. However, please adjust these values to meet your needs.

Installation

To install the application, place the content of the OAuth2 app inside your installation’s app directory, or use the Market application.

Basic Configuration

To enable token-only based app or client logins in config/config.php set token_auth_enforced to true.

Restricting Usage

  • Enterprise installations can limit the access of authorized clients, preventing unwanted clients from connecting.

Endpoints

Description URI

Authorization URL

/index.php/apps/oauth2/authorize

Access Token URL

/index.php/apps/oauth2/api/v1/token

Protocol Flow

Client Registration

The clients first have to be registered in the admin settings: /settings/admin?sectionid=authentication. You need to specify a name for the client (the name is unrelated to the OAuth 2.0 protocol and is just used to recognize it later) and the redirection URI. A client identifier and client secret are generated when adding a new client, which both consist of 64 characters. For further information about client registration, please refer to the official client registration RFC from the IETF.

Authorization Request

For every registered client an authorization request can be made. The client redirects the resource owner to the authorization URL and requests authorization. The following URL parameters have to be specified:

Parameter Required Description

response_type

yes

Needs to be code because at this time only the authorization code flow is implemented.

client_id

yes

The client identifier obtained when registering the client.

redirect_uri

yes

The redirection URI specified when registering the client.

state

no

Can be set by the client "to maintain state between the request and callback". See `RFC 6749`_ for more information.

For further information about client registration, please refer to the official authorization request RFC from the IETF.

Authorization Response

After the resource owner’s authorization, the app redirects to the redirect_uri specified in the authorization request and adds the authorization code as URL parameter code. An authorization code is valid for 10 minutes. For further information about client registration, please refer to the official authorization response RFC from the IETF.

Access Token Request

With the authorization code, the client can request an access token using the access token URL. Client authentication is done using basic authentication with the client identifier as username and the client secret as a password. The following URL parameters have to be specified:

Parameter Required Description

grant_type

Either authorization_code or refresh_token.

code

if the grant type authorization_code is used.

redirect_uri

if the grant type authorization_code is used.

refresh_token

if the grant type refresh_token is used.

For further information about client registration, please refer to the official access token request RFC from the IETF.

Access Token Response

The app responses to a valid access token request with a JSON response like the following. An access token is valid for 1 hour and can be refreshed with a refresh token.

{
    "access_token" : "1vtnuo1NkIsbndAjVnhl7y0wJha59JyaAiFIVQDvcBY2uvKmj5EPBEhss0pauzdQ",
    "token_type" : "Bearer",
    "expires_in" : 3600,
    "refresh_token" : "7y0wJuvKmj5E1vjVnhlPBEhha59JyaAiFIVQDvcBY2ss0pauzdQtnuo1NkIsbndA",
    "user_id" : "admin",
    "message_url" : "https://www.example.org/owncloud/index.php/apps/oauth2/authorization-successful"
}

For further information about client registration, please refer to the official access token response RFC from the IETF.

For a succinct explanation of the differences between access tokens and authorization codes, check out this answer on StackOverflow.

Limitations

  • Since the app does not handle user passwords, only master key encryption works (similar to the Shibboleth app).

  • Clients cannot migrate accounts from Basic Authorization to OAuth2, if they are currently using the user_ldap backend.

  • It is not possible to explicitly end user sessions when using OAuth2. Have a read through User Authentication with OAuth 2.0 to find out more.

Further Reading