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:
The OAuth2 App
OAuth2 support is available in ownCloud via an OAuth2 application which is available from the ownCloud Marketplace. The app aims to:
-
Connect ownCloud clients (both desktop and mobile) in a standardized and secure way.
-
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.
-
Redis: You will need to have a Redis server available, ideally the latest, stable, version
-
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 |
|
Access Token URL |
|
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 |
---|---|---|
|
yes |
Needs to be |
|
yes |
The client identifier obtained when registering the client. |
|
yes |
The redirection URI specified when registering the client. |
|
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 |
---|---|---|
|
Either |
|
|
if the grant type |
|
|
if the grant type |
|
|
if the grant type |
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.