Commit 56a4d0f1 authored by Sofia Papagiannaki's avatar Sofia Papagiannaki
Browse files

docs: Update Changelog, upgrade notes and guides

parent a88d1615
...@@ -29,6 +29,8 @@ Synnefo-wide ...@@ -29,6 +29,8 @@ Synnefo-wide
notifactions to users listed in 'ADMINS' setting about unhandled exceptions notifactions to users listed in 'ADMINS' setting about unhandled exceptions
in the code. in the code.
* Extend astakosclient to request and validate OAuth 2.0 access tokens
Astakos Astakos
------- -------
...@@ -77,11 +79,19 @@ Astakos ...@@ -77,11 +79,19 @@ Astakos
'ASTAKOS_ADMIN_STATS_PERMITTED_GROUPS' setting. Statistics are also availble 'ASTAKOS_ADMIN_STATS_PERMITTED_GROUPS' setting. Statistics are also availble
from 'snf-manage stats-astakos' management command. from 'snf-manage stats-astakos' management command.
* Implement OAuth 2.0 Authorization Code Grant
Add API calls for authorization code and access token generation
* Add API call for validating OAuth 2.0 access tokens
* Management commands: * Management commands:
* Introduced new commands: * Introduced new commands:
* component-show * component-show
* quota-list (replacing quota, supports various filters) * quota-list (replacing quota, supports various filters)
* quota-verify (replacing quota) * quota-verify (replacing quota)
* oauth2-client-add (register OAuth 2.0 client)
* oauth2-client-list (list registered oauth 2.0 clients)
* oauth2-client-remove (remove OAuth 2.0 client)
* Changed commands: * Changed commands:
* component-add got options --base-url and --ui-url * component-add got options --base-url and --ui-url
* resource-modify --limit became --default-quota * resource-modify --limit became --default-quota
...@@ -189,6 +199,19 @@ Pithos ...@@ -189,6 +199,19 @@ Pithos
* Introduced new command: * Introduced new command:
* file-show * file-show
* Change view authentication
The pithos views do not use the cookie information for user authentication.
They request (from Astakos) and use a short-term access token for a
specific resource.
* Remove PITHOS_ASTAKOS_COOKIE_NAME setting, since it is no longer useful
* Add PITHOS_OAUTH2_CLIENT_CREDENTIALS setting to authenticate the views with
astakos during the resource access token generation procedure
* Add PITHOS_SERVE_API_DOMAIN setting to restrict file serving endpoints to a
specific host
* Refactor metadata schema (table attributes) in Pithos DB to speedup current * Refactor metadata schema (table attributes) in Pithos DB to speedup current
objects by domain attribute. This is used by Plankton for listing VM images. objects by domain attribute. This is used by Plankton for listing VM images.
......
...@@ -1504,6 +1504,9 @@ group-list List available groups ...@@ -1504,6 +1504,9 @@ group-list List available groups
user-list List users user-list List users
user-modify Modify user user-modify Modify user
user-show Show user details user-show Show user details
oauth2-client-add Create an oauth2 client
oauth2-client-list List oauth2 clients
oauth2-client-remove Remove an oauth2 client along with its registered redirect urls
============================ =========================== ============================ ===========================
Pithos snf-manage commands Pithos snf-manage commands
......
...@@ -20,6 +20,7 @@ Document Revisions ...@@ -20,6 +20,7 @@ Document Revisions
========================= ================================ ========================= ================================
Revision Description Revision Description
========================= ================================ ========================= ================================
0.15 (December 02, 2013) Extent token api with validate token call
0.15 (October 29, 2013) Remove GET /authenticate in favor of POST /tokens 0.15 (October 29, 2013) Remove GET /authenticate in favor of POST /tokens
0.14 (June 03, 2013) Remove endpoint listing 0.14 (June 03, 2013) Remove endpoint listing
0.14 (May 28, 2013) Extend token api with authenticate call 0.14 (May 28, 2013) Extend token api with authenticate call
...@@ -428,3 +429,51 @@ Return Code Description ...@@ -428,3 +429,51 @@ Return Code Description
401 (Unauthorized) Invalid token or invalid creadentials or tenantName does not comply with the provided token 401 (Unauthorized) Invalid token or invalid creadentials or tenantName does not comply with the provided token
500 (Internal Server Error) The request cannot be completed because of an internal error 500 (Internal Server Error) The request cannot be completed because of an internal error
=========================== ===================== =========================== =====================
Validate token
^^^^^^^^^^^^^^
This calls validates an access token and confirms that it belongs to a
specified scope.
========================================= ========= ==================
Uri Method Description
========================================= ========= ==================
``/identity/v2.0/tokens/<token_id>`` GET Validates an access token and confirms that it belongs to a specified scope.
========================================= ========= ==================
|
====================== =========================
Request Parameter Name Value
====================== =========================
belongsTo Validates that a access token has the specified scope.
The belongsTo parameter is optional.
====================== =========================
Example response
::
{"access": {
"token": {
"expires": "2013-12-02T15:57:34.300266+00:00",
"id": "2YotnFZFEjr1zCsicMWpAA",
"tenant": {
"id": "c18088be-16b1-4263-8180-043c54e22903",
"name": "Firstname Lastname"
}
},
"user": {
"roles_links": [],
"id": "c18088be-16b1-4263-8180-043c54e22903",
"roles": [{"id": 1, "name": "default"}],
"name": "Firstname Lastname"}}}
|
=========================== =====================
Return Code Description
=========================== =====================
404 Unknown or expired access token or the access token does not belong to the specified scope
=========================== =====================
...@@ -8,7 +8,7 @@ synnefo version 0.15, the pithos view will be deployed in a domain outside the ...@@ -8,7 +8,7 @@ synnefo version 0.15, the pithos view will be deployed in a domain outside the
astakos cookie domain. The current document describes how the pithos view can astakos cookie domain. The current document describes how the pithos view can
grant access to the protected pithos resources. grant access to the protected pithos resources.
The proposed scheme follows the guidelines of the Oauth 2.0 authentication The proposed scheme follows the guidelines of the OAuth 2.0 authentication
framework as described in http://tools.ietf.org/html/rfc6749/. framework as described in http://tools.ietf.org/html/rfc6749/.
Briefly the pithos view requests a short-term access token for a specific Briefly the pithos view requests a short-term access token for a specific
...@@ -31,11 +31,11 @@ to be asked. ...@@ -31,11 +31,11 @@ to be asked.
We can register an oauth 2.0 client with the following command:: We can register an oauth 2.0 client with the following command::
snf-manage oa2-client-add <client_id> --secret=<secret> --is-trusted --url <redirect_uri> snf-manage oauth2-client-add <client_id> --secret=<secret> --is-trusted --url <redirect_uri>
For example:: For example::
snf-manage oa2-client-add pithos-view --secret=12345 --is-trusted --url https://pithos.synnefo.live/pithos/ui/view snf-manage oauth2-client-add pithos-view --secret=12345 --is-trusted --url https://pithos.synnefo.live/pithos/ui/view
Configure view credentials in pithos Configure view credentials in pithos
...@@ -43,13 +43,13 @@ Configure view credentials in pithos ...@@ -43,13 +43,13 @@ Configure view credentials in pithos
To set the credentials issued to pithos view in order to authenticate itself To set the credentials issued to pithos view in order to authenticate itself
with astakos during the resource access token generation procedure we have to with astakos during the resource access token generation procedure we have to
change the ``PITHOS_OA2_CLIENT_CREDENTIALS`` setting. change the ``PITHOS_OAUTH2_CLIENT_CREDENTIALS`` setting.
The value should be a (<client_id>, <client_secret>) tuple. The value should be a (<client_id>, <client_secret>) tuple.
For example:: For example::
PITHOS_OA2_CLIENT_CREDENTIALS = ('pithos-view', 12345) PITHOS_OAUTH2_CLIENT_CREDENTIALS = ('pithos-view', 12345)
Authorization Code Grant Flow Authorization Code Grant Flow
============================= =============================
...@@ -99,7 +99,7 @@ the following parameters to the query component using the ...@@ -99,7 +99,7 @@ the following parameters to the query component using the
For example, the client directs the user-agent to make the following HTTP For example, the client directs the user-agent to make the following HTTP
request using TLS (with extra line breaks for display purposes only):: request using TLS (with extra line breaks for display purposes only)::
GET /astakos/oa2/auth?response_type=code&client_id=pithos-view GET /astakos/oauth2/auth?response_type=code&client_id=pithos-view
&redirect_uri=https%3A//pithos.synnefo.live/pithos/ui/view/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png &redirect_uri=https%3A//pithos.synnefo.live/pithos/ui/view/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png
&scope=/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png HTTP/1.1 &scope=/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png HTTP/1.1
Host: accounts.synnefo.live Host: accounts.synnefo.live
...@@ -124,13 +124,14 @@ request entity-body: ...@@ -124,13 +124,14 @@ request entity-body:
the "redirect_uri" parameter was included in the authorization request the "redirect_uri" parameter was included in the authorization request
Since the pithos view is registered as a confidential client it MUST Since the pithos view is registered as a confidential client it MUST
authenticate with astakos by providing an Authorization header including the encoded client credentials as described authenticate with astakos by providing an Authorization header including the
encoded client credentials as described in
http://tools.ietf.org/html/rfc2617#page-11. http://tools.ietf.org/html/rfc2617#page-11.
For example, the view makes the following HTTP request using TLS (with extra For example, the view makes the following HTTP request using TLS (with extra
line breaks for display purposes only):: line breaks for display purposes only)::
POST /astakos/oa2/token HTTP/1.1 POST /astakos/oauth2/token HTTP/1.1
Host: accounts.synnefo.live Host: accounts.synnefo.live
Authorization: Basic cGl0aG9zLXZpZXc6MTIzNDU= Authorization: Basic cGl0aG9zLXZpZXc6MTIzNDU=
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
...@@ -186,7 +187,7 @@ Authorization code and access token invalidation ...@@ -186,7 +187,7 @@ Authorization code and access token invalidation
Authorization codes can be used only once (they are deleted after a Authorization codes can be used only once (they are deleted after a
successful token creation) successful token creation)
Token expiration can be set by changing the ``OA2_TOKEN_EXPIRES`` setting. Token expiration can be set by changing the ``OAUTH2_TOKEN_EXPIRES`` setting.
By default it is set to 20 seconds. By default it is set to 20 seconds.
Tokens granted to a user are deleted after user logout or authentication token Tokens granted to a user are deleted after user logout or authentication token
...@@ -197,10 +198,11 @@ Expired tokens presented to the validation endpoint are also deleted. ...@@ -197,10 +198,11 @@ Expired tokens presented to the validation endpoint are also deleted.
Authorization code and access token length Authorization code and access token length
========================================== ==========================================
Authorization code length is adjustable by the ``OA2_AUTHORIZATION_CODE_LENGTH`` Authorization code length is adjustable by the
setting. By default it is set to 60 characters. ``OAUTH2_AUTHORIZATION_CODE_LENGTH`` setting. By default it is set to
60 characters.
Token length is adjustable by the ``OA2_TOKEN_LENGTH`` setting. Token length is adjustable by the ``OAUTH2_TOKEN_LENGTH`` setting.
By default it is set to 30 characters. By default it is set to 30 characters.
Restrict file serving endpoints to a specific host Restrict file serving endpoints to a specific host
......
...@@ -137,7 +137,7 @@ Drafts ...@@ -137,7 +137,7 @@ Drafts
Resource-pool projects design <design/resource-pool-projects> Resource-pool projects design <design/resource-pool-projects>
Resource defaults design <design/resource-defaults> Resource defaults design <design/resource-defaults>
Pithos view authentication <design/pithos-view-authentication.rst> Pithos view authorization <design/pithos-view-authorization.rst>
Contact Contact
......
...@@ -918,6 +918,23 @@ numeric value, i.e. 10240 MB, 10 GB etc. ...@@ -918,6 +918,23 @@ numeric value, i.e. 10240 MB, 10 GB etc.
# snf-manage resource-modify --default-quota-interactive # snf-manage resource-modify --default-quota-interactive
.. _pithos_view_registration:
Register pithos view as an OAuth 2.0 client
-------------------------------------------
Starting from synnefo version 0.15, the pithos view, in order to get access to
the data of a protect pithos resource, has to be granted authorization for the
specific resource by astakos.
During the authorization grant procedure, it has to authenticate itself with
astakos since the later has to prevent serving requests by unknown/unauthorized
clients.
To register the pithos view as an OAuth 2.0 client in astakos, we have to run
the following command::
snf-manage oauth2-client-add pithos-view --secret=<secret> --is-trusted --url https://node2.example.com/pithos/ui/view
Servers Initialization Servers Initialization
---------------------- ----------------------
...@@ -1075,6 +1092,13 @@ The ``CLOUDBAR_SERVICES_URL`` and ``CLOUDBAR_MENU_URL`` options are used by the ...@@ -1075,6 +1092,13 @@ The ``CLOUDBAR_SERVICES_URL`` and ``CLOUDBAR_MENU_URL`` options are used by the
Pithos web client to get from astakos all the information needed to fill its Pithos web client to get from astakos all the information needed to fill its
own cloudbar. So we put our astakos deployment urls there. own cloudbar. So we put our astakos deployment urls there.
The ``PITHOS_OAUTH2_CLIENT_CREDENTIALS`` setting is used by the pithos view
in order to authenticate itself with astakos during the authorization grant
procedure and it should container the credentials issued for the pithos view
in `the pithos view registration step`__.
__ pithos_view_registration_
Pooling and Greenlets Pooling and Greenlets
--------------------- ---------------------
......
...@@ -143,7 +143,25 @@ The upgrade to v0.15 consists in the following steps: ...@@ -143,7 +143,25 @@ The upgrade to v0.15 consists in the following steps:
pithos-host$ pithos-migrate upgrade head pithos-host$ pithos-migrate upgrade head
2.3 Update configuration files .. _pithos_view_registration:
2.3 Register pithos view as an oauth 2.0 client in astakos
----------------------------------------------------------
Starting from synnefo version 0.15, the pithos view, in order to get access to
the data of a protect pithos resource, has to be granted authorization for the
specific resource by astakos.
During the authorization grant procedure, it has to authenticate itself with
astakos since the later has to prevent serving requests by unknown/unauthorized
clients.
To register the pithos view as an OAuth 2.0 client in astakos, use the
following command::
snf-manage oauth2-client-add pithos-view --secret=<secret> --is-trusted --url https://pithos.synnefo.live/pithos/ui/view
2.4 Update configuration files
------------------------------ ------------------------------
The ``ASTAKOS_BASE_URL`` setting has been replaced (both in Cyclades and The ``ASTAKOS_BASE_URL`` setting has been replaced (both in Cyclades and
...@@ -240,6 +258,12 @@ value / string and make sure that it's the same as the ``STATS_SECRET_KEY`` ...@@ -240,6 +258,12 @@ value / string and make sure that it's the same as the ``STATS_SECRET_KEY``
setting (used to decrypt the instance hostname) in setting (used to decrypt the instance hostname) in
``20-snf-stats-settings.conf`` on your Stats host. ``20-snf-stats-settings.conf`` on your Stats host.
In addition to this, we have to change the ``PITHOS_OAUTH2_CLIENT_CREDENTIALS``
setting in the ``20-snf-pithos-app-settings.conf`` file to set the credentials
issued for the pithos view in `the previous step`__.
__ pithos_view_registration_
3. Create floating IP pools 3. Create floating IP pools
=========================== ===========================
......
...@@ -43,7 +43,7 @@ from astakos.oa2.models import Client, RedirectUrl ...@@ -43,7 +43,7 @@ from astakos.oa2.models import Client, RedirectUrl
class Command(SynnefoCommand): class Command(SynnefoCommand):
args = "<identfier>" args = "<identfier>"
help = "Create a oauth2 client" help = "Create an oauth2 client"
option_list = SynnefoCommand.option_list + ( option_list = SynnefoCommand.option_list + (
make_option('--secret', make_option('--secret',
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment