Permalink
Browse files

Update documentation and authorization examples

* Update README.md
* Add save button to auth flow examples
  • Loading branch information...
1 parent ea76fba commit 2032d6dfc799152925bc1980a283cc77c6dcfc50 @astrada committed Jan 14, 2012
View
@@ -22,7 +22,7 @@ Old versions:
### Features
* Monadic interface
-* Functional lenses to access data structures
+* [Functional lenses](src/gapi/gapiLens.mli) to access data structures
* Service generator (experimental): a tool for generating client libraries for
APIs based on the Google API Discovery format.
@@ -56,27 +56,40 @@ packages for Debian](http://ocaml.debian.net/debian/ocaml-3.12.1/)):
[pa_monad]: http://www.cas.mcmaster.ca/~carette/pa_monad/
[OUnit]: http://ounit.forge.ocamlcore.org/
-### Building
+### Configuration and installation
-To build the library, execute
+This project provides 2 libraries:
- $ cd src
- $ ocamlbuild gdata/gdata.cma
+* gapi: Google APIs client library
+* gdata: Google Data Protocol client library
-To build the tests, execute
+and 1 executable:
- $ cd src
- $ ocamlbuild test/testSuite.byte
+* serviceGenerator: Tool used to generate strongly typed client libraries for
+ Discovery-based services
-To run the tests, see [tests README](src/test/README.md).
+To build and install the libraries and the executable, run
-To generate the documentation, execute
+ $ ocaml setup.ml -configure
+ $ ocaml setup.ml -build
+ $ ocaml setup.ml -install
- $ cd src
- $ ocamlbuild gapi/gapi.docdir/index.html
+To run the tests, execute
-Then you can access the HTML documentation starting from
-`src/gapi.docdir/index.html`.
+ $ ocaml setup.ml -test
+
+See [tests README](src/test/README.md) for further details regarding the tests.
+
+To generate the documentation, run
+
+ $ ocaml setup.ml -doc
+
+Then you can browse the HTML documentation starting from
+`gapi-ocaml.docdir/index.html`, but is not installed by default.
+
+To uninstall anything that was previously installed, execute
+
+ $ ocaml setup.ml -uninstall
### Usage
@@ -89,3 +102,6 @@ monadic interface.
See [calendar v3 test](src/test/testCalendarModelV3.ml) for an example of how
to use functional lenses to read and modify calendar data.
+See [tools README](src/tools/README.md) for the instructions of how to run the
+service generator utility.
+
View
@@ -69,7 +69,6 @@ Library gdata
Document "gapi-ocaml"
Title: API reference for Google APIs client library
Type: ocamlbuild (0.2)
- Install: true
InstallDir: $htmldir/html
DataFiles: doc/style.css
BuildTools: ocamldoc
File renamed without changes.
@@ -7,31 +7,35 @@ gapi-ocaml examples
How to obtain credentials
-------------------------
+The preferred authorization mechanism to access Google services is OAuth 2.0,
+the other authorization methods are useful for development purposes only.
+
+All the utilities use a file named `auth.conf` in the [config](../../config)
+directory to read authentication credentials.
+
+You can start from the
+[auth.config.template](../../../config/auth.config.template):
+
+ $ cp auth.config.template auth.config
+
+and then fill in the values obtained by the following tools.
+
### Client login
To obtain an authorization token, you can use the `clientLoginFlow` utility
that request an access token to your calendar feeds.
- 1. Create a file named `auth.conf` in this directory containing these lines:
+ 1. Fill in these values in `auth.conf`
cl_user=Google account username
cl_pass=Google account password
- 2. Go to the [src](../..) directory:
-
- $ cd ../..
-
- 3. Build `clientLoginFlow`
-
- $ ocamlbuild examples/auth/clientLoginFlow.byte
-
- 4. Run the program
+ 2. Run the program
$ ./clientLoginFlow.byte
This program will print the obtained authorization token that you can put in
-`cl_token` of file `test.config` (in [test directory](/src/test)) to run tests
-based on Client Login.
+`cl_token` of the config file to run tests based on Client Login.
**WARNING**: There is no easy way to revoke an authorization token obtained
in this way. So, be careful to not disclose these values online.
@@ -41,33 +45,27 @@ in this way. So, be careful to not disclose these values online.
To obtain an OAuth token and corresponding secret, you can use the oauth1Flow
utility that request an access token to your calendar feeds.
- 1. Create a file named `auth.conf` in this directory containing these lines:
+ 1. Fill in these values in `auth.conf`
oa1_displayname=anonymous
oa1_cons_secret=anonymous
oa1_cons_key=anonymous
oa1_callback=http://localhost:8091/oauth1callback
- 2. Go to the [src](../..) directory:
-
- $ cd ../..
-
- 3. Build oauth1Flow
-
- $ ocamlbuild examples/auth/oauth1Flow.byte
-
- 4. Run the server
+ 2. Run the server
$ ./oauth1Flow.byte
This program will show a link to the Google authorization URL that you must
open using a web browser, then it will start a web server listening to port
`8091` (be sure that this port is not already in use). After signin in with
your Google account, you will be asked for authorization, then you will be
-redirected to the page specified in the `oa1_callback` of the `oauth.conf`
+redirected to the page specified in the `oa1_callback` of the `auth.conf`
file. That page will show the access token with its corresponding secret. You
-can put these values in `oa1_token` and `oa1_secret` of file `test.config` (in
-[test directory](/src/test)) to run tests based on OAuth1.
+can put these values manually in `oa1_token` and `oa1_secret` of the config
+file to run tests based on OAuth1, or you can automatically save them using
+the `Save` button of the form, then copy back the saved file to the `config`
+directory.
You can revoke the access token in your Google Account settings.
@@ -92,32 +90,29 @@ https://code.google.com/apis/console/ to register your application:
Then
- 1. Create a file named `auth.conf` in this directory containing these lines:
+ 1. Fill in these values in `auth.conf`
oa2_id=OAuth2 client ID from previous step
oa2_secret=OAuth2 client secret from previous step
oa2_uri=http://localhost:8091/oauth2callback
- 2. Go to the [src](../..) directory:
-
- $ cd ../..
-
- 3. Build `oauth2Flow`
-
- $ ocamlbuild examples/auth/oauth2Flow.byte
-
- 4. Run the server
+ 2. Run the server
$ ./oauth2Flow.byte
This program will show a link to the Google authorization URL that you must
open using a web browser, then it will start a web server listening to port
`8091` (be sure that this port is not already in use). After signin in with
your Google account, you will be asked for authorization, then you will be
-redirected to the page specified in the `oa2_callback` of the `oauth.conf`
+redirected to the page specified in the `oa2_callback` of the `auth.conf`
file. That page will show the access token and the refresh token. You can put
-these values in `oa2_token` and `oa2_refresh` of file `test.config` (in [test
-directory](/src/test)) to run tests based on OAuth2.
+these values manually in `oa2_token` and `oa2_refresh` of the config file to
+run tests based on OAuth2, or you can automatically save them using the `Save`
+button of the form, then copy back the saved file to the `config` directory.
You can revoke the refresh token in your Google Account settings.
+**Important!** Try to keep your client secret and developer key secret! Anyone
+who has access to those can potentially abuse all the privileges granted to
+your application.
+
@@ -16,6 +16,6 @@ let _ =
in
match auth_token with
GapiAuthResponse.ClientLoginAuthToken token ->
- Printf.printf "token=%s\n" token
+ Printf.printf "Client Login auth token:\n%s\n" token
| _ -> failwith "Not supported auth response")
@@ -21,24 +21,47 @@ let get_access_token
~oauth_verifier
~oauth_secret
session in
- let output =
+ let (access_token, access_token_secret) =
match response with
GapiAuthResponse.OAuth1GetAccessToken token ->
- Printf.sprintf "oauth_token=%s; oauth_token_secret=%s\n"
- token.GapiAuthResponse.OAuth1.access_token
- token.GapiAuthResponse.OAuth1.access_token_secret
- | _ -> failwith "Not supported OAuth1 response"
+ (token.GapiAuthResponse.OAuth1.access_token,
+ token.GapiAuthResponse.OAuth1.access_token_secret)
+ | _ -> failwith "Not supported OAuth1 response" in
+ let output =
+ Printf.sprintf
+ "<form method=\"post\" action=\"\">\
+ <fieldset>\
+ <legend>OAuth1 token:</legend>\
+ oa1_token: <input type=\"text\" name=\"oa1_token\" value=\"%s\" size=\"50\" /><br />\
+ oa1_secret: <input type=\"text\" name=\"oa1_secret\" value=\"%s\" size=\"50\" /><br />\
+ <input type=\"submit\" name=\"save\" value=\"Save\" />\
+ </fieldset>\
+ </form>"
+ access_token
+ access_token_secret
in
Common.output_page "OAuth1 Flow" "Success" output cgi
with Failure error ->
Common.output_error_page "OAuth1 Flow" error cgi)
-let oauth1_callback
- oauth_secret
- (cgi : Netcgi.cgi_activation) =
- let oauth_token = cgi#argument_value "oauth_token" in
- let oauth_verifier = cgi#argument_value "oauth_verifier" in
- get_access_token oauth_token oauth_secret oauth_verifier cgi
+let save (cgi : Netcgi.cgi_activation) =
+ let oa1_token = cgi#argument_value "oa1_token" in
+ let oa1_secret = cgi#argument_value "oa1_secret" in
+ let filename = "/tmp/auth.config" in
+ Config.set test_config "oa1_token" oa1_token;
+ Config.set test_config "oa1_secret" oa1_secret;
+ Config.save ~filename test_config;
+ Common.output_page "OAuth1 Flow" "Success"
+ ("<p>OAuth1 token saved to " ^ filename ^ "</p>")
+ cgi
+
+let oauth1_callback oauth_secret (cgi : Netcgi.cgi_activation) =
+ if cgi#argument_value "save" <> "" then
+ save cgi
+ else
+ let oauth_token = cgi#argument_value "oauth_token" in
+ let oauth_verifier = cgi#argument_value "oauth_verifier" in
+ get_access_token oauth_token oauth_secret oauth_verifier cgi
let get_request_token () =
Common.do_request
@@ -14,24 +14,52 @@ let get_access_token code (cgi : Netcgi.cgi_activation) =
~code
~redirect_uri
session in
- let output =
+ let (access_token, token_type, expires_in, refresh_token) =
match response with
GapiAuthResponse.OAuth2AccessToken token ->
- Printf.sprintf "access_token=%s; token_type=%s; expires_in=%d; refresh_token=%s\n"
- token.GapiAuthResponse.OAuth2.access_token
- token.GapiAuthResponse.OAuth2.token_type
- token.GapiAuthResponse.OAuth2.expires_in
- token.GapiAuthResponse.OAuth2.refresh_token
- | _ -> failwith "Not supported OAuth2 response"
+ (token.GapiAuthResponse.OAuth2.access_token,
+ token.GapiAuthResponse.OAuth2.token_type,
+ token.GapiAuthResponse.OAuth2.expires_in,
+ token.GapiAuthResponse.OAuth2.refresh_token)
+ | _ -> failwith "Not supported OAuth2 response" in
+ let output =
+ Printf.sprintf
+ "<form method=\"post\" action=\"\">\
+ <fieldset>\
+ <legend>OAuth2 tokens:</legend>\
+ oa2_token: <input type=\"text\" name=\"oa2_token\" value=\"%s\" size=\"50\" /><br />\
+ oa2_refresh: <input type=\"text\" name=\"oa2_refresh\" value=\"%s\" size=\"50\" /><br />\
+ <input type=\"submit\" name=\"save\" value=\"Save\" />\
+ </fieldset>\
+ </form>\
+ <p>token_type: %s</p>\
+ <p>expires_in: %d</p>"
+ access_token refresh_token token_type expires_in
in
Common.output_page "OAuth2 Flow" "Success" output cgi)
-let oauth2_callback (cgi : Netcgi.cgi_activation) =
+let save (cgi : Netcgi.cgi_activation) =
+ let oa2_token = cgi#argument_value "oa2_token" in
+ let oa2_refresh = cgi#argument_value "oa2_refresh" in
+ let filename = "/tmp/auth.config" in
+ Config.set test_config "oa2_token" oa2_token;
+ Config.set test_config "oa2_refresh" oa2_refresh;
+ Config.save ~filename test_config;
+ Common.output_page "OAuth2 Flow" "Success"
+ ("<p>OAuth2 token saved to " ^ filename ^ "</p>")
+ cgi
+
+let error (cgi : Netcgi.cgi_activation) =
let error = cgi#argument_value "error" in
- let code = cgi#argument_value "code" in
- if error <> "" then
- Common.output_error_page "OAuth2 Flow" error cgi
- else
+ Common.output_error_page "OAuth2 Flow" error cgi
+
+let oauth2_callback (cgi : Netcgi.cgi_activation) =
+ if cgi#argument_value "save" <> "" then
+ save cgi
+ else if cgi#argument_value "error" <> "" then
+ error cgi
+ else
+ let code = cgi#argument_value "code" in
get_access_token code cgi
let main () =
View
@@ -8,7 +8,6 @@ gapi-ocaml tests
if you want to run them, it is better to create a test account, and use it
instead of your real Google account (to avoid unpleasant side effects).
-
How to obtain credentials
-------------------------
@@ -53,11 +52,11 @@ Google OAuth 2.0 endpoint.
### Configuring tests
To run the test suite you need to provide a configuration file based on
-[test.config.template](test.config.template) that contains the credentials of
-the test account. So, create the configuration file `test.config` copying the
-template:
+[auth.config.template](../../config/auth.config.template) that contains the
+credentials of the test account. So, create the configuration file
+`auth.config` copying the template:
- $ cp test.config.template test.config
+ $ cp auth.config.template auth.config
Then edit this file, and fill in the following fields:
@@ -84,7 +83,12 @@ OAuth2:
oa2_token=access token
oa2_refresh=refresh token
-`test.config` example:
+Additional parameters:
+
+ key=API key (The API key is displayed in the Simple API Access section)
+ debug=enable/disable debugging output (true/false)
+
+`auth.config` example:
cl_user=username@gmail.com
cl_pass=password
@@ -100,4 +104,6 @@ OAuth2:
oa2_uri=http://localhost:8091/oauth2callback
oa2_token=bbbaaaddd
oa2_refresh=000aaAADD
+ key=12121212121212121212121
+ debug=false
Oops, something went wrong.

0 comments on commit 2032d6d

Please sign in to comment.