From f806c643d9d4823604602397f4487d8c9b7bfeae Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Wed, 18 Oct 2017 15:58:53 +0200 Subject: [PATCH 1/6] Draft OAuth2 documenation Very much a WIP. --- .../configuration/server/security/oauth2.rst | 182 ++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 admin_manual/configuration/server/security/oauth2.rst diff --git a/admin_manual/configuration/server/security/oauth2.rst b/admin_manual/configuration/server/security/oauth2.rst new file mode 100644 index 000000000..f3a8e1ab9 --- /dev/null +++ b/admin_manual/configuration/server/security/oauth2.rst @@ -0,0 +1,182 @@ +====== +OAuth2 +====== + +What is it? +----------- + +Quoting `RFC 6749`_: + + 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. + +:: + + +----------+ + | 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) + +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 +-------------- + +Installing the app +~~~~~~~~~~~~~~~~~~ + +Place the content of this repository in **owncloud/apps/oauth2**. + +Using the app +~~~~~~~~~~~~~ + +Endpoints +^^^^^^^^^ + +================= ======================================= +Description URI +================= ======================================= +Authorization URL ``/index.php/apps/oauth2/authorize`` +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``. +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. + +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 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 an 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`_. + +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`_). + + +.. 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 From 67297965a53f85065ac719ea7c2d054553783d8a Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Fri, 17 Nov 2017 12:12:35 +0100 Subject: [PATCH 2/6] Rework the OAuth2 documentation --- .../configuration/server/security/oauth2.rst | 84 +++++++++---------- 1 file changed, 38 insertions(+), 46 deletions(-) diff --git a/admin_manual/configuration/server/security/oauth2.rst b/admin_manual/configuration/server/security/oauth2.rst index f3a8e1ab9..83df9cfb0 100644 --- a/admin_manual/configuration/server/security/oauth2.rst +++ b/admin_manual/configuration/server/security/oauth2.rst @@ -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: :: @@ -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 @@ -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. @@ -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: ================= ============================= =================================================== @@ -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 @@ -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 @@ -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 + From d1e91ff111b5f7ea08e8c91f6ed7dcb275c3c90b Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Thu, 15 Mar 2018 14:15:09 +0100 Subject: [PATCH 3/6] Document the mod_headers is mandatory for OAuth2 support This relates to https://github.com/owncloud/oauth2/issues/110 and #3464. --- admin_manual/installation/source_installation.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/admin_manual/installation/source_installation.rst b/admin_manual/installation/source_installation.rst index bc1816d8c..bd9b3efe4 100644 --- a/admin_manual/installation/source_installation.rst +++ b/admin_manual/installation/source_installation.rst @@ -366,13 +366,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 `` Date: Thu, 15 Mar 2018 14:15:09 +0100 Subject: [PATCH 4/6] Document the mod_headers is mandatory for OAuth2 support This relates to https://github.com/owncloud/oauth2/issues/110 and #3464. --- admin_manual/configuration/server/security/oauth2.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/admin_manual/configuration/server/security/oauth2.rst b/admin_manual/configuration/server/security/oauth2.rst index 83df9cfb0..ff68e0456 100644 --- a/admin_manual/configuration/server/security/oauth2.rst +++ b/admin_manual/configuration/server/security/oauth2.rst @@ -141,6 +141,11 @@ Installation To install the application, place the content of the OAuth2 app inside your installation's ``app`` directory. +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 ------------------- @@ -171,4 +176,6 @@ Revoking Sessions .. _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 From ac4d5278d0ea5bd06fc3db05a765f66e2b0cba7c Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Thu, 15 Mar 2018 14:18:14 +0100 Subject: [PATCH 5/6] Document OAuth2 limitations and requirements Relates to #3464. --- admin_manual/configuration/server/security/oauth2.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/admin_manual/configuration/server/security/oauth2.rst b/admin_manual/configuration/server/security/oauth2.rst index ff68e0456..ed3216117 100644 --- a/admin_manual/configuration/server/security/oauth2.rst +++ b/admin_manual/configuration/server/security/oauth2.rst @@ -139,7 +139,7 @@ For further information about client registration, please refer to `the official Installation ------------ -To install the application, place the content of the OAuth2 app inside your installation's ``app`` directory. +To install the application, place the content of the OAuth2 app inside your installation's ``app`` directory, or use the Market application. Requirements ------------ @@ -152,11 +152,13 @@ Basic Configuration 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`_). +- 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 ----------------------------- From 8a233a880df323b95cc283425a4efa6f7496b02b Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Thu, 15 Mar 2018 14:18:14 +0100 Subject: [PATCH 6/6] Document OAuth2 limitations and requirements Relates to #3464. --- admin_manual/configuration/server/security/oauth2.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/admin_manual/configuration/server/security/oauth2.rst b/admin_manual/configuration/server/security/oauth2.rst index ed3216117..e1a2f267c 100644 --- a/admin_manual/configuration/server/security/oauth2.rst +++ b/admin_manual/configuration/server/security/oauth2.rst @@ -136,6 +136,9 @@ 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`_. +.. note:: + For a succinct explanation of the differences between access tokens and authorization codes, check out `this answer on StackOverflow`_. + Installation ------------ @@ -149,6 +152,8 @@ If you are hosting your ownCloud installation from the Apache web server, then b Basic Configuration ------------------- +To enable token-only based app or client logins in ``config/config.php`` set ``token_auth_enforced`` to ``true``. + Restricting Usage ----------------- @@ -180,4 +185,4 @@ Revoking Sessions .. _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