From db4172e29ed8780a3474ece4346086dcfe839a58 Mon Sep 17 00:00:00 2001 From: Dalton Hubble Date: Sun, 30 Aug 2015 17:30:53 -0700 Subject: [PATCH] Update godocs and README --- CHANGES.md | 2 +- README.md | 75 ++++++++++++++++++++++++++++++++++++---------- doc.go | 88 +++++++++++++++++++++++++++++++++++------------------- 3 files changed, 117 insertions(+), 48 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 9895e21..daeaea8 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,6 @@ # OAuth1 Changelog -## latest (TBD) +## v.1.0.0-rc1 (2015-08-30) * Improved OAuth 1 spec compliance and test coverage. * Added `func StaticTokenSource(*Token) TokenSource` diff --git a/README.md b/README.md index 6de3037..adc876f 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ OAauth1 is a Go implementation of the [OAuth 1 spec](https://tools.ietf.org/html/rfc5849). -It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (.e.g API calls). +It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from [golang.org/x/oauth2](https://godoc.org/golang.org/x/oauth2), providing an `http.Client` which handles request signing and authorization. @@ -17,22 +17,58 @@ Read [GoDoc](https://godoc.org/github.com/dghubble/oauth1) ### Authorization Flow -The OAuth 1 authorization flow to request that a user grant an application access to his/her account (via an access token) typically looks like: +Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. -* User visits Consumer's "/login" route (via "Login with Provider" button) -* Login handler calls `config.GetRequestToken()` -* Login handler redirects user to `config.AuthorizationURL(rt *RequestToken)` -* Provider calls Consumer's CallbackURL with a `verifier` -* `config.GetAccessToken(rt *RequestToken, verifier string)` -* Consumer application stores access token. Optionally creates some form of unforgeable session state. +```go +import ( + "github.com/dghubble/oauth1" + "github.com/dghubble/oauth1/twitter"" +) +... + +config := oauth1.Config{ + ConsumerKey: "consumerKey", + ConsumerSecret: "consumerSecret", + CallbackURL: "http://mysite.com/oauth/twitter/callback", + Endpoint: twitter.AuthorizeEndpoint, +} +``` + +1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). + + ```go + requestToken, requestSecret, err = config.RequestToken() + // handle err + ``` -For more details, see the Twitter PIN-based login [example](examples). +2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. -The [gologin](https://github.com/dghubble/gologin) packages provide higher-level login handlers for common OAuth1 and OAuth2 providers. + ```go + authorizationURL, err := config.AuthorizationURL(requestToken) + // handle err + http.Redirect(w, req, authorizationURL.String(), htt.StatusFound) + ``` + + Receive the callback from the OAuth1 provider in a handler. + + ``` + requestToken, verifier, err := oauth1.ParseAuthorizationCallback(req) + // handle err + ``` + +3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. + + ```go + accessToken, accessSecret, err := config.AccessToken(requestToken, requestSecret, verifier) + // handle error + token := NewToken(accessToken, accessSecret) + ``` + +Check the [examples](examples) to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. ### Authorized Requests -After an access `Token` has been obtained, authorized requests can be made on behalf of the user. +Use an access `Token` to make authorized requests on behalf of a user. ```go import ( @@ -55,17 +91,24 @@ func main() { } ``` -See more request [examples](examples). +Check the [examples](examples) to see Twitter and Tumblr requests in action. + +## Higher Level Packages + +To implement "Login with X", you may wish to use the [gologin](https://github.com/dghubble/gologin) packages which provide login handlers for OAuth1 and OAuth2 providers. + +To make requests, you may wish to use the Twitter and Tumblr Go API clients. -The [go-twitter](https://github.com/dghubble/go-twitter) package provides a higher-level API client to the Twitter API. +* [github.com/dghubble/go-twitter](https://github.com/dghubble/go-twitter) +* [github.com/benfb/go-tumblr](https://github.com/benfb/go-tumblr) ### Components -An `Endpoint` groups an OAuth provider's URLs for getting a request token, allowing users to authorize applications, and getting access tokens. Endpoints for common providers like [twitter](twitter) and [dropbox](dropbox) are provided in subpackages. +An `Endpoint` groups an OAuth provider's token and authorization URLs.Endpoints for common providers are provided in subpackages. -A `Config` stores a consumer application's consumer key and secret, the callback URL, and the Endpoint to which the consumer is registered. It provides OAuth 1 authorization flow methods and a `Client(token *Token)` method which returns an `http.Client` which will transparently authorize requests. +A `Config` stores a consumer application's consumer key and secret, the callback URL, and the Endpoint to which the consumer is registered. It provides OAuth1 authorization flow methods. -An OAuth1 `Token` is an access token which allows requests to be made as a particular user. It has fields `Token` and `TokenSecret`. If you already have an access token, skip to [Authorized Requests](#Authorized Requests). +An OAuth1 `Token` is an access token which allows requests to be made as a particular user. See [Authorized Requests](#Authorized Requests) for details. If you've used [golang.org/x/oauth2](https://godoc.org/golang.org/x/oauth2) before, this organization is similar. diff --git a/doc.go b/doc.go index b3c9de8..a78f445 100644 --- a/doc.go +++ b/doc.go @@ -1,46 +1,62 @@ /* -Package oauth1 is a Go implementation of the OAuth1 spec. +Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. -Components +It allows end-users to authorize a client (consumer) to access protected +resources on their behalf (e.g. login) and allows clients to make signed and +authorized requests on behalf of a user (e.g. API calls). -An Endpoint groups an OAuth provider's URLs for getting a request token, -allowing users to authorize applications, and getting access tokens. Endpoints -for common providers like Twitter and Dropbox are provided in subpackages. +It takes design cues from golang.org/x/oauth2, providing an http.Client which +handles request signing and authorization. -A Config stores a consumer application's consumer key and secret, the -callback URL, and the Endpoint to which the consumer is registered. It -provides OAuth 1 authorization flow methods and a Client(token *Token) -method which returns an http.Client which will transparently authorize -requests. +Authorization Flow + +Perform the OAuth 1 authorization flow to ask a user to grant an application +access to his/her resources via an access token. + + import ( + "github.com/dghubble/oauth1" + "github.com/dghubble/oauth1/twitter"" + ) + ... -An OAuth1 Token is an access token which allows requests to be made as a -particular user. It has fields Token and TokenSecret. If you already have -an access token, skip to Authorized Requests. + config := oauth1.Config{ + ConsumerKey: "consumerKey", + ConsumerSecret: "consumerSecret", + CallbackURL: "http://mysite.com/oauth/twitter/callback", + Endpoint: twitter.AuthorizeEndpoint, + } -If you've used https://godoc.org/golang.org/x/oauth2 before, this organization -is similar. +1. When a user performs an action (e.g. "Login with X" button calls "/login" +route) get an OAuth1 request token (temporary credentials). -Authorization Flow + requestToken, requestSecret, err = config.RequestToken() + // handle err -The OAuth 1 authorization flow to request that a user grant an application -access to his/her account (via an access token) typically looks like: +2. Obtain authorization from the user by redirecting them to the OAuth1 +provider's authorization URL to grant the application access. - * User visits Consumer's "/login" route (via "Login with Provider" - button) - * Login handler calls config.GetRequestToken() - * Login handler redirects user to config.AuthorizationURL(rt *RequestToken) - * Provider calls Consumer's CallbackURL with a verifier - * config.GetAccessToken(rt *RequestToken, verifier string) - * Consumer application stores access token. Optionally creates some form of - unforgeable session state. + authorizationURL, err := config.AuthorizationURL(requestToken) + // handle err + http.Redirect(w, req, authorizationURL.String(), htt.StatusFound) -For more details, see the Twitter PIN-based login example or the -https://github.com/dghubble/go-twitter login package. +Receive the callback from the OAuth1 provider in a handler. + + requestToken, verifier, err := oauth1.ParseAuthorizationCallback(req) + // handle err + +3. Acquire the access token (token credentials) which can later be used +to make requests on behalf of the user. + + accessToken, accessSecret, err := config.AccessToken(requestToken, requestSecret, verifier) + // handle error + token := NewToken(accessToken, accessSecret) + +Check the examples to see this authorization flow in action from the command +line, with Twitter PIN-based login and Tumblr login. Authorized Requests -After an access Token has been obtained, authorized requests can be made on -behalf of the user. +Use an access Token to make authorized requests on behalf of a user. import ( "github.com/dghubble/oauth1" @@ -61,6 +77,16 @@ behalf of the user. fmt.Printf("Raw Response Body:\n%v\n", string(body)) } -See more request examples in the examples subpackage. +Check the examples to see Twitter and Tumblr requests in action. + +Higher Level Packages + +To implement "Login with X", you may wish to use the https://github.com/dghubble/gologin +packages which provide login handlers for OAuth1 and OAuth2 providers. + +To make requests to Twitter or Tumblr, you may wish to use the +https://github.com/dghubble/go-twitter and https://github.com/benfb/go-tumblr +Go API clients. + */ package oauth1