<commit_before>#<a name="top"></a>OAuth2 in Cosmos APIs
Content:

* [Requesting a token](#section1)
* [Using the token](#section2)

##<a name="section1"></a>Requestig a token
Before using any REST API protected by [OAuth2](http://oauth.net/2/), you must request a token to the Cosmos Tokens Generator you must have installed somewhere. This is a service that will be listening in TCP/13000 port (in FIWARE Lab, this is `computing.cosmos.lab.fiware.org:13000`. You can do this using any REST client of your choice, the easiest way is using the `curl` command:

    $ curl -k -X POST "https://<tokens_generator_host>:13000/cosmos-auth/v1/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username=<registered_email_in_imd>&password=<<PASSWORD>>"
    {"access_token": "<KEY>", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "<PASSWORD>"}

As you can see, some Identity Manager credentials are required in the payload, in the form of a password-based grant type. This is because the Cosmos Tokens Generator relies on an Identity Manager instance.

[Top](#top)

##<a name="section2"></a>Using the token
Use cosmos-proxy to protect any Cosmos Http based resource.

For instance, if aiming to protect WebHDFS simply re-configure the service for running in an alternative port different than the default one, e.g. TCP/41000 instead or TCP/14000. Then, configure the proxy for listening in the original WebHDFS port, i.e. TCP/14000 and specify the new target port, i.e. TCP/41000. From here on, all the requests sent to the WebHDFS service will be really sent to the proxy, attaching the required `X-Auth-Token` for authentication and authorization purposes:

    $ curl -X GET "http://storage.cosmos.lab.fiware.org:14000/webhdfs/v1/user/frb?op=liststatus&user.name=frb" -H "X-Auth-Token: <PASSWORD>"
    "FileStatuses":{"FileStatus":[{"pathSuffix":".Trash","type":"DIRECTORY","length":0,"owner":"frb","group":"frb","permission":"700","accessTime":0,"modificationTime":1468519200094,"blockSize":0,"replication":0},{"pathSuffix":...

You may have a look on the proxy and see how authentication and authorization has been done:

    {"level":"info","message":"Authentication OK: {\"organizations\": [], \"displayName\": \"frb\", \"roles\": [{\"name\": \"provider\", \"id\": \"106\"}], \"app_id\": \"4d1af2eec3754099a4f8dc86bf735068\", \"email\": \"<EMAIL>\", \"id\": \"frb\"}","timestamp":"2016-07-14T11:48:15.332Z"}
    {"level":"info","message":"Authorization OK: user frb is allowed to access /webhdfs/v1/user/frb","timestamp":"2016-07-14T11:48:15.332Z"}
    {"level":"info","message":"Redirecting to http://0.0.0.0:41000","timestamp":"2016-07-14T11:48:15.332Z"}

[Top](#top)<commit_msg>Update using_oauth2.md<commit_after>#<a name="top"></a>OAuth2 in Cosmos APIs
Content:

* [Requesting a token](#section1)
* [Using the token](#section2)
* [Using the token in Hive](#section3)

##<a name="section1"></a>Requestig a token
Before using any REST API protected by [OAuth2](http://oauth.net/2/), you must request a token to the Cosmos Tokens Generator you must have installed somewhere. This is a service that will be listening in TCP/13000 port (in FIWARE Lab, this is `computing.cosmos.lab.fiware.org:13000`. You can do this using any REST client of your choice, the easiest way is using the `curl` command:

    $ curl -k -X POST "https://<tokens_generator_host>:13000/cosmos-auth/v1/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username=<registered_email_in_imd>&password=<<PASSWORD>>"
    {"access_token": "<KEY>", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "V<KEY>"}

As you can see, some Identity Manager credentials are required in the payload, in the form of a password-based grant type. This is because the Cosmos Tokens Generator relies on an Identity Manager instance.

[Top](#top)

##<a name="section2"></a>Using the token in Http APIs
This is the case cosmos-proxy has been used to protect any Cosmos Http based resource.

For instance, all the requests sent to the WebHDFS service will be really sent to the proxy, attaching the required `X-Auth-Token` for authentication and authorization purposes:

    $ curl -X GET "http://storage.cosmos.lab.fiware.org:14000/webhdfs/v1/user/frb?op=liststatus&user.name=frb" -H "X-Auth-Token: <mytoken>"
    "FileStatuses":{"FileStatus":[{"pathSuffix":".Trash","type":"DIRECTORY","length":0,"owner":"frb","group":"frb","permission":"700","accessTime":0,"modificationTime":1468519200094,"blockSize":0,"replication":0},{"pathSuffix":...
    
Authentication process is transparent to the user, everything is done at cosmos-proxy.

[Top](#top)

##<a name="section3"></a>Using the token in Hive
Use cosmos-hive-auth-provider to protect HiveServer2 JDBC interface with OAuth2.

In this case, users provide their credentials as usual, but instead of a password they pass a valid OAuth2 token. For instance, if using the Hive clients available in the [resources folder](https://github.com/telefonicaid/fiware-cosmos/tree/master/resources/hiveclients), you can connect this way:

    $ python hiveserver2-client.py computing.cosmos.lab.fiware.org 10000 default frb <mytoken>

Authentication process is transparent to the user, everything is done at cosmos-hive-auth-provider.

[Top](#top)
{'fraction_non_alphanumeric': 0.14350112697220135, 'fraction_numerical': 0.04169797145003756, 'mean_word_length': 5.3925570228091235, 'pattern_counts': {'":': 51, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 3, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 1, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3745540', 'n_tokens_mistral': 1792, 'n_tokens_neox': 1631, 'n_words': 544}