From fbd522701d1bf4ffbbd5f3d30f2138c5043d8304 Mon Sep 17 00:00:00 2001
From: Dalton Hubble <dghubble@gmail.com>
Date: Sun, 26 Apr 2015 19:47:54 -0700
Subject: [PATCH] Add example Twitter access token grant flow (PIN-based)

---
 examples/README.md                          | 41 +++++++++++++
 examples/twitter-login.go                   | 66 +++++++++++++++++++++
 examples/{twitter.go => twitter-request.go} |  0
 twitter/twitter.go                          |  2 +-
 4 files changed, 108 insertions(+), 1 deletion(-)
 create mode 100644 examples/README.md
 create mode 100644 examples/twitter-login.go
 rename examples/{twitter.go => twitter-request.go} (100%)

diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..b35140b
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,41 @@
+
+# examples
+
+## Twitter
+
+### Login Flow (PIN)
+
+A consumer application can obtain a Twitter Access Token for a user by requesting the user grant access via [3-legged](https://dev.twitter.com/oauth/3-legged) or [PIN-based](https://dev.twitter.com/oauth/pin-based) OAuth 1. 
+
+    export TWITTER_CONSUMER_KEY=xxx
+    export TWITTER_CONSUMER_SECRET=yyy
+
+    go run twitter-login.go
+
+    Open this URL in your browser:
+    https://api.twitter.com/oauth/authenticate?oauth_token=xxx
+    Paste your PIN here: ddddddd
+    Consumer was granted an access token to act on behalf of a user.
+    token: ddddd-xxxxx
+    secret: yyyyyy
+
+Note that website backends should define a CallbackURL which can receive a verifier string and request an access token, "oob" is for PIN-based agents such as the command line.
+
+The OAuth 1 flow can be used to implement Sign in with Twitter if receipt of an access token by your server is used to gate creation of some form of unforgeable session state. Consider using the [go-twitter](https://github.com/dghubble/go-twitter) `login` package if you're implementing Sign in with Twitter in Go.
+
+### Authorized Requests
+
+Use an Access Token to make requests on behalf of a Twitter user.
+
+    export TWITTER_CONSUMER_KEY=xxx
+    export TWITTER_CONSUMER_SECRET=xxx
+    export TWITTER_ACCESS_TOKEN=xxx
+    export TWITTER_ACCESS_TOKEN_SECRET=xxx
+
+Run to perform requests as the user (reads only, it won't tweet anything)
+
+    go run twitter-request.go
+
+
+
+
diff --git a/examples/twitter-login.go b/examples/twitter-login.go
new file mode 100644
index 0000000..e6088f9
--- /dev/null
+++ b/examples/twitter-login.go
@@ -0,0 +1,66 @@
+package main
+
+import (
+	"fmt"
+	"github.com/dghubble/oauth1"
+	twauth "github.com/dghubble/oauth1/twitter"
+	"log"
+	"os"
+)
+
+const outOfBand = "oob"
+
+var config oauth1.Config
+
+// main performs PIN-based 3-legged auth to show the Oauth 1 user flow in a
+// simple command line program.
+func main() {
+	// read credentials from environment variables
+	consumerKey := os.Getenv("TWITTER_CONSUMER_KEY")
+	consumerSecret := os.Getenv("TWITTER_CONSUMER_SECRET")
+	if consumerKey == "" || consumerSecret == "" {
+		log.Fatal("Required environment variable missing.")
+	}
+
+	config = oauth1.Config{
+		ConsumerKey:    consumerKey,
+		ConsumerSecret: consumerSecret,
+		CallbackURL:    outOfBand,
+		Endpoint:       twauth.AuthorizeEndpoint,
+	}
+
+	requestToken, err := login()
+	if err != nil {
+		log.Fatalf("Request Token Phase: %s", err.Error())
+	}
+	accessToken, err := receivePIN(requestToken)
+	if err != nil {
+		log.Fatalf("Access Token Phase: %s", err.Error())
+	}
+
+	fmt.Println("Consumer was granted an access token to act on behalf of a user.")
+	fmt.Printf("token: %s\nsecret: %s\n", accessToken.Token, accessToken.TokenSecret)
+}
+
+func login() (*oauth1.RequestToken, error) {
+	requestToken, err := config.GetRequestToken()
+	if err != nil {
+		return nil, err
+	}
+	authorizationURL, err := config.AuthorizationURL(requestToken)
+	if err != nil {
+		return nil, err
+	}
+	fmt.Printf("Open this URL in your browser:\n%s\n", authorizationURL.String())
+	return requestToken, err
+}
+
+func receivePIN(requestToken *oauth1.RequestToken) (*oauth1.Token, error) {
+	fmt.Printf("Paste your PIN here: ")
+	var verifier string
+	_, err := fmt.Scanf("%s", &verifier)
+	if err != nil {
+		return nil, err
+	}
+	return config.GetAccessToken(requestToken, verifier)
+}
diff --git a/examples/twitter.go b/examples/twitter-request.go
similarity index 100%
rename from examples/twitter.go
rename to examples/twitter-request.go
diff --git a/twitter/twitter.go b/twitter/twitter.go
index f89b394..ffb0ea6 100644
--- a/twitter/twitter.go
+++ b/twitter/twitter.go
@@ -1,4 +1,4 @@
-// Package twitter implements the Twitter OAuth 1 endpoints.
+// Package twitter provides constants for using OAuth1 to access Twitter.
 package twitter
 
 import (