Skip to content
This repository has been archived by the owner on Feb 20, 2019. It is now read-only.

Commit

Permalink
Merge pull request #3464 from owncloud/document-oauth2
Browse files Browse the repository at this point in the history 
Draft OAuth2 Documenation
  • Loading branch information
@settermjd
settermjd authored Jun 1, 2018
2 parents ff35784 + 8a233a8 commit 12549e1
Show file tree
Hide file tree
Showing 2 changed files with 199 additions and 2 deletions.
188 changes: 188 additions & 0 deletions admin_manual/configuration/server/security/oauth2.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,188 @@
======
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:

::

+----------+
| Resource |
| Owner |
| |
+----------+
^
|
(B)
+----|-----+ Client Identifier +---------------+
| -+----(A)-- & Redirection URI ---->| |
| User- | | Authorization |
| Agent -+----(B)-- User authenticates --->| Server |
| | | |
| -+----(C)-- Authorization Code ---<| |
+-|----|---+ +---------------+
| | ^ v
(A) (C) | |
| | | |
^ v | |
+---------+ | |
| |>---(D)-- Authorization Code ---------' |
| Client | & Redirection URI |
| | |
| |<---(E)----- Access Token -------------------'
+---------+ (w/ Optional Refresh Token)


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.

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.

.. code-block:: json
{
"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`_.

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

Installation
------------

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

Requirements
------------

If you are hosting your ownCloud installation from the Apache web server, then both the `mod_rewrite`_ and `mod_headers`_ modules are required to be installed and enabled.

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.

Limitations
-----------

- Since the app handles no 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.

Connecting Clients via OAuth2
-----------------------------

Revoking Sessions
-----------------


.. Links
.. _an OAuth2 application: https://marketplace.owncloud.com/apps/oauth2
.. _the Shibboleth app: https://marketplace.owncloud.com/apps/user_shibboleth
.. _the official client registration RFC from the IETF: https://tools.ietf.org/html/rfc6749#section-2
.. _the official authorization request RFC from the IETF: https://tools.ietf.org/html/rfc6749#section-4.1.1
.. _the official authorization response RFC from the IETF: https://tools.ietf.org/html/rfc6749#section-4.1.2
.. _the official access token request RFC from the IETF: https://tools.ietf.org/html/rfc6749#section-4.1.3
.. _the official access token response RFC from the IETF: https://tools.ietf.org/html/rfc6749#section-4.1.4
.. _RFC 6749: https://tools.ietf.org/html/rfc6749#section-4.1.1
.. _Client authentication: https://tools.ietf.org/html/rfc6749#section-2.3
.. _mod_rewrite: http://httpd.apache.org/docs/current/mod/mod_rewrite.html
.. _mod_headers: http://httpd.apache.org/docs/current/mod/mod_headers.html
.. _this answer on StackOverflow: https://stackoverflow.com/a/16341985/222011
13 changes: 11 additions & 2 deletions admin_manual/installation/source_installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -455,13 +455,19 @@ Additional Apache Configurations

a2enmod rewrite
Additional recommended modules are ``mod_headers``, ``mod_env``, ``mod_dir`` and ``mod_mime``::
Additional recommended modules are ``mod_headers``, ``mod_env``, ``mod_dir`` and ``mod_mime``

::
a2enmod headers
a2enmod env
a2enmod dir
a2enmod mime
.. note::
If you want to use `the OAuth2 app`_, then `mod_headers`_ must be installed and
enabled.

- You must disable any server-configured authentication for ownCloud, as it uses Basic authentication internally for DAV services. If you have turned on authentication on a parent folder (via, e.g., an ``AuthType Basic`` directive), you can disable the authentication specifically for the ownCloud entry. Following the above example configuration file, add the following line in the ``<Directory`` section

::
Expand Down Expand Up @@ -566,6 +572,9 @@ In the event that a load-balancer is in place, there will be no issues as long a
.. _Apache prefork: https://httpd.apache.org/docs/2.4/mod/prefork.html
.. _not thread safe: https://secure.php.net/manual/en/install.unix.apache2.php

.. Apache Modules
.. _mod_headers: http://httpd.apache.org/docs/current/mod/mod_headers.html

.. PHP Extension Links
.. _Bzip2: https://php.net/manual/en/book.bzip2.php
Expand Down Expand Up @@ -618,4 +627,4 @@ In the event that a load-balancer is in place, there will be no issues as long a
.. Forum Links
.. _in the forums: https://central.owncloud.org/t/no-basic-authentication-headers-were-found-message/819

.. _the OAuth2 app: https://marketplace.owncloud.com/apps/oauth2

0 comments on commit 12549e1

Please sign in to comment.