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

Commit

Permalink
Rework the OAuth2 documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@settermjd
settermjd committed Nov 17, 2017
1 parent f806c64 commit 6729796
Showing 1 changed file with 38 additions and 46 deletions.
84 changes: 38 additions & 46 deletions admin_manual/configuration/server/security/oauth2.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@ OAuth2
What is it?
-----------

Quoting `RFC 6749`_:
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.
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:

::

Expand Down Expand Up @@ -39,34 +39,18 @@ Quoting `RFC 6749`_:
| |<---(E)----- Access Token -------------------'
+---------+ (w/ Optional Refresh Token)

OAuth2 support is available via `an OAuth2 application`_, available from the ownCloud Marketplace.
The aim of it is to:

- Connect the ownCloud clients (both desktop and mobile) in a standardized and secure way
- To make integrations in 3rd party software easier by providing an authorization interface.

Benefits
--------

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

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

Administration
The OAuth2 App
--------------

Installing the app
~~~~~~~~~~~~~~~~~~

Place the content of this repository in **owncloud/apps/oauth2**.
OAuth2 support is available in ownCloud via `an OAuth2 application`_ which is available from the ownCloud Marketplace.
The app aims to:

Using the app
~~~~~~~~~~~~~
#. 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
Expand All @@ -76,20 +60,18 @@ Access Token URL ``/index.php/apps/oauth2/api/v1/token``
================= =======================================

Protocol Flow
^^^^^^^^^^^^^
~~~~~~~~~~~~~

Client Registration
''''''''''''''''''''
^^^^^^^^^^^^^^^^^^^^

First the clients have to be registered in the admin settings: ``/index.php/settings/admin?sectionid=additional#oauth2``.
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 is being generated when adding a new client.
They both consist of 64 characters.

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.
Expand All @@ -108,18 +90,17 @@ Parameter Required Description
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`.
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 password.
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:

================= ============================= ===================================================
Expand All @@ -137,9 +118,9 @@ Parameter Required Description
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 an JSON response like the following.
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
Expand All @@ -155,18 +136,28 @@ An access token is valid for 1 hour and can be refreshed with a refresh token.
For further information about client registration, please refer to `the official access token response RFC from the IETF`_.

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

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

Basic Configuration
~~~~~~~~~~~~~~~~~~~
-------------------

Restricting Usage
~~~~~~~~~~~~~~~~~

-----------------


Limitations
~~~~~~~~~~~
-----------

Since no user passwords are handled by the app at all only master key encryption is working (similar to `the Shibboleth app`_).
Since the app handles no user passwords, only master key encryption works (similar to `the Shibboleth app`_).

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

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


.. Links
Expand All @@ -180,3 +171,4 @@ Since no user passwords are handled by the app at all only master key encryption
.. _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

0 comments on commit 6729796

Please sign in to comment.