Draft OAuth2 Documenation #3464
Conversation
Very much a WIP.
|
Pls add possible changes soon, then I suggest to merge this and add/change content with additional PR´s. 10.0.4 is released soon ... IMHO better this than nothing |
| The OAuth2 App | ||
| -------------- | ||
|
|
||
| OAuth2 support is available in ownCloud via `an OAuth2 application`_ which is available from the ownCloud Marketplace. |
There was a problem hiding this comment.
Does the App work as Authorisation Server in ownCloud (what I believe so reading the text)? If yes than it should be stated to make the role more clear. If not or if not only, than describe the role(s) to get a link to the picture above.
There was a problem hiding this comment.
As I read that text, it is saying that via the OAuth2 application from the Marketplace, OAuth2 client support can be added to ownCloud.
There was a problem hiding this comment.
Proposal:
OAuth2 support is available --> OAuth2 authorisation server support is available
This would make the role of the app clear.
Because an external client independent coming from owncloud itself or from any other source authorizes and connects to the server. When owncloud connects eg to dropbox via the dp-app, the dp-app is in the role of the client where db is in the role of the server.
Reduces confusion: aahhh Oauth2 app - let´s connect to sharepoint which is exactly not the possible because of the role of the app...
| ^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| 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. |
There was a problem hiding this comment.
What happens after the 10min? Is there a user interaction necessary or are there processes running in the background automatically ? If yes which or what happens?
There was a problem hiding this comment.
Isn't this rather something for a developer documentation? I think here we need to document what administrators need to know. Technical overview, benefits, configuration details, minimum client versions, etc..
There was a problem hiding this comment.
Actually, @pmaier1, on reading the text again, it makes sense to keep the background information and configuration documentation together, rather than have the admin/user search for one or the other. I'd suggest to keep it as it is.
There was a problem hiding this comment.
Proposal:
An authorization code is valid for 10 minutes. --> For security reasons, an authorization code is valid for 10 minutes. If the client tries to use the authorization code more than once, the authorization server denies the request.
| ^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| 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. |
There was a problem hiding this comment.
Above, the token is valid for 10min. Now the token is valid for 1h...
Additionally same question as above, what happens if it expires... Can be refreshed means what ?
There was a problem hiding this comment.
I guess above is referring to the authorization code, with this being valid for 10 minutes. An authorization code can then be used for requesting an access token, with this being valid for max 1 hour. Or at least this is what I understood..
There was a problem hiding this comment.
I'd suggest there's some confusion between authorization code and access token going on. Here's a good description of them.
There was a problem hiding this comment.
Why not adding the link (good description) to ease understanding?
| Installation | ||
| ------------ | ||
|
|
||
| To install the application, place the content of the OAuth2 app inside your installation's ``app`` directory. |
There was a problem hiding this comment.
Respectively use the Market App
There was a problem hiding this comment.
As with other ownCloud apps we do not have to document the installation process as it's always the same. Either you install it manually as described or you use the market app. IMO we only need to explain installation when there are dependencies on other software like Collabora or full text search or stuff like that.
| Limitations | ||
| ----------- | ||
|
|
||
| Since the app handles no user passwords, only master key encryption works (similar to `the Shibboleth app`_). |
There was a problem hiding this comment.
What to do in case of any other encryption type ?
There was a problem hiding this comment.
Where does this info come from? I use OAuth on an instance that uses credential-based storage encryption. Works like a charm.
There was a problem hiding this comment.
Correction: The statement regarding credential-based storage encryption is correct. Sorry, my bad.
There was a problem hiding this comment.
Add a link to owncloud/oauth2#105?
|
@DeepDiver1975 |
| To install the application, place the content of the OAuth2 app inside your installation's ``app`` directory. | ||
|
|
||
| Basic Configuration | ||
| ------------------- |
There was a problem hiding this comment.
You basically don't have to configure anything in oC itself. Here we need information on configuring the basic infrastructure around it and how to cover special cases like SSO #3456 owncloud/oauth2#49
|
|
||
| Restricting Usage | ||
| ----------------- | ||
|
|
There was a problem hiding this comment.
Here we need info about how to "lock-out" the original oC clients and e.g. only allow the usage of branded clients with special client id/secret.
There was a problem hiding this comment.
Ref. owncloud/oauth2#72
There was a problem hiding this comment.
I've added content around this point, taken from owncloud/oauth2#72.
|
|
||
| Connecting Clients via OAuth2 | ||
| ----------------------------- | ||
|
|
There was a problem hiding this comment.
- Basic howto is explained in the blog post
- Basic auth will still be possible for e.g. legacy WebDAV clients that don't support OAuth
|
Requires references to owncloud/oauth2#110 |
There was a problem hiding this comment.
This owncloud/core#29300 is also worth a mention somewhere in the docs.
| ----------------- | ||
|
|
||
|
|
||
| Limitations |
There was a problem hiding this comment.
One more limitation: owncloud/oauth2#109 (comment) -> clients are unable to migrate an account from Basic Auth. to OAuth2 if they come from the user_ldap backend.
|
|
||
| Restricting Usage | ||
| ----------------- | ||
|
|
There was a problem hiding this comment.
Ref. owncloud/oauth2#72
This relates to owncloud/oauth2#110 and #3464.
This relates to owncloud/oauth2#110 and #3464.
Relates to #3464.
|
@SamuAlfageme, as owncloud/core#29300 and owncloud/core#29324 are not yet implemented, can you create an issue to document it when that functionality is completed and merged, pls? Edit: |
|
@SamuAlfageme, reference to owncloud/oauth2#110 has been added. |
They're tho, see status and refer to owncloud/core#29300 (comment) for instructions on how to enable token-only based logins. |
|
Enable token-only based logins: config.sample.php: |
|
@SamuAlfageme @mmattel are your final two comments all that's left to be implemented on this PR? |
|
If you add my 2 proposal texts I am fine. It is better to have that merged soon instead discussing / keeping this open endless. |
|
@mmattel doing that today. |
|
@mmattel your changes have been integrated in the text. |
|
Is it correct to say: To enable token-only based logins in |
|
From that whatI understood the key was implemented for - yes. |
Relates to #3464.
settermjd
force-pushed
the
document-oauth2
branch
from
cc031e1
to
8a233a8
Compare
|
@mmattel, line added. Thanks for the further suggestion. |
|
Let´s merge this, additions can be added later. |
This relates to owncloud/oauth2#110 and #3464.
This relates to owncloud/oauth2#110 and #3464.
|
Backported to Antora build in 482a918. |
Very much a WIP.
Fixes #3299