oauth1

README

OAuth1

OAauth1 is a Go implementation of the OAuth 1 spec.

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, providing an http.Client which handles request signing and authorization.

Install

go get github.com/dghubble/oauth1

Documentation

Read GoDoc

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""
)
...

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).

   requestToken, requestSecret, err = config.RequestToken()
   // handle err
   

2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access.

   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.

   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

Use an access Token to make authorized requests on behalf of a user.

import (
    "github.com/dghubble/oauth1"
)

func main() {
    config := oauth1.NewConfig("consumerKey", "consumerSecret")
    token := oauth1.NewToken("token", "tokenSecret")

    // httpClient will automatically authorize http.Request's
    httpClient := config.Client(token)

    // example Twitter API request
    path := "https://api.twitter.com/1.1/statuses/home_timeline.json?count=2"
    resp, _ := httpClient.Get(path)
    defer resp.Body.Close()
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Printf("Raw Response Body:\n%v\n", string(body))
}

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 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.

• github.com/dghubble/go-twitter
• github.com/benfb/go-tumblr

Components

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 OAuth1 authorization flow methods.

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 before, this organization is similar.

Contributing

See the Contributing Guide.

License

MIT License

Documentation

Overview

Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849.

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, providing an http.Client which handles request signing and authorization.

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""
)
...

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).

requestToken, requestSecret, err = config.RequestToken()
// handle err

2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access.

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.

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

Use an access Token to make authorized requests on behalf of a user.

import (
	"github.com/dghubble/oauth1"
)

func main() {
    config := oauth1.NewConfig("consumerKey", "consumerSecret")
    token := oauth1.NewToken("token", "tokenSecret")

    // httpClient will automatically authorize http.Request's
    httpClient := config.Client(token)

    // example Twitter API request
    path := "https://api.twitter.com/1.1/statuses/home_timeline.json?count=2"
    resp, _ := httpClient.Get(path)
    defer resp.Body.Close()
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Printf("Raw Response Body:\n%v\n", string(body))
}

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.

Index

• func NewClient(config *Config, token *Token) *http.Client
• func ParseAuthorizationCallback(req *http.Request) (requestToken, verifier string, err error)
• func PercentEncode(input string) string
• type Config
  • func NewConfig(consumerKey, consumerSecret string) *Config
  • func (c *Config) AccessToken(requestToken, requestSecret, verifier string) (accessToken, accessSecret string, err error)
  • func (c *Config) AuthorizationURL(requestToken string) (*url.URL, error)
  • func (c *Config) Client(t *Token) *http.Client
  • func (c *Config) RequestToken() (requestToken, requestSecret string, err error)
• type Endpoint
• type Signer
  • func (s *Signer) SetAccessTokenAuthHeader(req *http.Request, requestToken, requestSecret, verifier string) error
  • func (s *Signer) SetRequestAuthHeader(req *http.Request, accessToken *Token) error
  • func (s *Signer) SetRequestTokenAuthHeader(req *http.Request) error
• type Token
  • func NewToken(token, tokenSecret string) *Token
• type TokenSource
  • func StaticTokenSource(token *Token) TokenSource
• type Transport
  • func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

Functions

func NewClient

func NewClient(config *Config, token *Token) *http.Client

NewClient returns a new http Client which signs requests via OAuth1.

func ParseAuthorizationCallback

func ParseAuthorizationCallback(req *http.Request) (requestToken, verifier string, err error)

ParseAuthorizationCallback parses an OAuth1 authorization callback request from a provider server. The oauth_token and oauth_verifier parameters are parsed to return the request token from earlier in the flow and the verifier string. See RFC 5849 2.2 Resource Owner Authorization.

func PercentEncode

func PercentEncode(input string) string

PercentEncode percent encodes a string according to RFC 3986 2.1.

Types

type Config

type Config struct {
	// Consumer Key (Client Identifier)
	ConsumerKey string
	// Consumer Secret (Client Shared-Secret)
	ConsumerSecret string
	// Callback URL
	CallbackURL string
	// Provider Endpoint specifying OAuth1 endpoint URLs
	Endpoint Endpoint
}

Config represents an OAuth1 consumer's (client's) key and secret, the callback URL, and the provider Endpoint to which the consumer corresponds.

func NewConfig

func NewConfig(consumerKey, consumerSecret string) *Config

NewConfig returns a new Config with the given consumer key and secret.

func (*Config) AccessToken

func (c *Config) AccessToken(requestToken, requestSecret, verifier string) (accessToken, accessSecret string, err error)

AccessToken obtains an access token (token credential) by POSTing a request (with oauth_token and oauth_verifier in the auth header) to the Endpoint AccessTokenURL. Returns the access token and secret (token credentials). See RFC 5849 2.3 Token Credentials.

func (*Config) AuthorizationURL

func (c *Config) AuthorizationURL(requestToken string) (*url.URL, error)

AuthorizationURL accepts a request token and returns the *url.URL to the Endpoint's authorization page that asks the user (resource owner) for to authorize the consumer to act on his/her/its behalf. See RFC 5849 2.2 Resource Owner Authorization.

func (*Config) Client

func (c *Config) Client(t *Token) *http.Client

Client returns an HTTP client which uses the provided access Token.

func (*Config) RequestToken

func (c *Config) RequestToken() (requestToken, requestSecret string, err error)

RequestToken obtains a Request token and secret (temporary credential) by POSTing a request (with oauth_callback in the auth header) to the Endpoint RequestTokenURL. The response body form is validated to ensure oauth_callback_confirmed is true. Returns the request token and secret (temporary credentials). See RFC 5849 2.1 Temporary Credentials.

type Endpoint

type Endpoint struct {
	// Request URL (Temporary Credential Request URI)
	RequestTokenURL string
	// Authorize URL (Resource Owner Authorization URI)
	AuthorizeURL string
	// Access Token URL (Token Request URI)
	AccessTokenURL string
}

Endpoint represents an OAuth1 provider's (server's) request token, owner authorization, and access token request URLs.

type Signer

type Signer struct {
	// contains filtered or unexported fields
}

Signer handles signing requests and setting the authorization header.

func (*Signer) SetAccessTokenAuthHeader

func (s *Signer) SetAccessTokenAuthHeader(req *http.Request, requestToken, requestSecret, verifier string) error

SetAccessTokenAuthHeader sets the OAuth1 header for the access token request (token credential) according to RFC 5849 2.3.

func (*Signer) SetRequestAuthHeader

func (s *Signer) SetRequestAuthHeader(req *http.Request, accessToken *Token) error

SetRequestAuthHeader sets the OAuth1 header for making authenticated requests with an AccessToken (token credential) according to RFC 5849 3.1.

func (*Signer) SetRequestTokenAuthHeader

func (s *Signer) SetRequestTokenAuthHeader(req *http.Request) error

SetRequestTokenAuthHeader adds the OAuth1 header for the request token request (temporary credential) according to RFC 5849 2.1.

type Token

type Token struct {
	Token       string
	TokenSecret string
}

Token is an AccessToken (token credential) which allows a consumer (client) to access resources from an OAuth1 provider server.

func NewToken

func NewToken(token, tokenSecret string) *Token

NewToken returns a new Token with the given token and token secret.

type TokenSource

type TokenSource interface {
	Token() (*Token, error)
}

A TokenSource can return a Token.

func StaticTokenSource

func StaticTokenSource(token *Token) TokenSource

StaticTokenSource returns a TokenSource which always returns the same Token. This is appropriate for tokens which do not have a time expiration.

type Transport

type Transport struct {
	// contains filtered or unexported fields
}

Transport is an http.RoundTripper which makes OAuth1 HTTP requests. It wraps a default RoundTripper and adds an Authorization header using an OAuth1 signer and TokenSource.

Transport is a low-level component, most users should use Config to create an http.Client instead.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip authorizes the request with a signed OAuth1 authorization header using the transport token source and signer.