README
¶
OAuth2 for Go
oauth2 package contains a client implementation for OAuth 2.0 spec.
Installation
go get golang.org/x/oauth2
See godoc for further documentation and examples.
Contributing
Fork the repo, make changes, run the tests and open a pull request.
Before we can accept any pull requests we have to jump through a couple of legal hurdles, primarily a Contributor License Agreement (CLA):
- If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an individual CLA.
- If you work for a company that wants to allow you to contribute your work, then you'll need to sign a corporate CLA.
You can sign these electronically (just scroll to the bottom). After that, we'll be able to accept your pull requests.
Documentation
¶
Overview ¶
Package oauth2 provides support for making OAuth2 authorized and authenticated HTTP requests. It can additionally grant authorization with Bearer JWT.
Example (JWT) ¶
package main
import (
"log"
"net/http"
"golang.org/x/oauth2"
)
func main() {
opts, err := oauth2.New(
// The contents of your RSA private key or your PEM file
// that contains a private key.
// If you have a p12 file instead, you
// can use `openssl` to export the private key into a pem file.
//
// $ openssl pkcs12 -in key.p12 -out key.pem -nodes
//
// It only supports PEM containers with no passphrase.
oauth2.JWTClient(
"xxx@developer.gserviceaccount.com",
[]byte("-----BEGIN RSA PRIVATE KEY-----...")),
oauth2.Scope("SCOPE1", "SCOPE2"),
oauth2.JWTEndpoint("https://provider.com/o/oauth2/token"),
// If you would like to impersonate a user, you can
// create a transport with a subject. The following GET
// request will be made on the behalf of user@example.com.
// Subject is optional.
oauth2.Subject("user@example.com"),
)
if err != nil {
log.Fatal(err)
}
// Initiate an http.Client, the following GET request will be
// authorized and authenticated on the behalf of user@example.com.
client := http.Client{Transport: opts.NewTransport()}
client.Get("...")
}
Output:
Example (Regular) ¶
package main
import (
"fmt"
"log"
"net/http"
"golang.org/x/oauth2"
)
func main() {
opts, err := oauth2.New(
oauth2.Client("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET"),
oauth2.RedirectURL("YOUR_REDIRECT_URL"),
oauth2.Scope("SCOPE1", "SCOPE2"),
oauth2.Endpoint(
"https://provider.com/o/oauth2/auth",
"https://provider.com/o/oauth2/token",
),
)
if err != nil {
log.Fatal(err)
}
// Redirect user to consent page to ask for permission
// for the scopes specified above.
url := opts.AuthCodeURL("state", "online", "auto")
fmt.Printf("Visit the URL for the auth dialog: %v", url)
// Use the authorization code that is pushed to the redirect URL.
// NewTransportWithCode will do the handshake to retrieve
// an access token and initiate a Transport that is
// authorized and authenticated by the retrieved token.
var code string
if _, err = fmt.Scan(&code); err != nil {
log.Fatal(err)
}
t, err := opts.NewTransportFromCode(code)
if err != nil {
log.Fatal(err)
}
// You can use t to initiate a new http.Client and
// start making authenticated requests.
client := http.Client{Transport: t}
client.Get("...")
}
Output:
Index ¶
- type Option
- func Client(id, secret string) Option
- func Endpoint(authURL, tokenURL string) Option
- func HTTPClient(c *http.Client) Option
- func JWTClient(email string, key []byte) Option
- func JWTEndpoint(aud string) Option
- func RedirectURL(url string) Option
- func Scope(scopes ...string) Option
- func Subject(user string) Option
- type Options
- type Token
- type TokenStore
- type Transport
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
Option represents a function that applies some state to an Options object.
func Client ¶
Client requires the OAuth 2.0 client credentials. You need to provide the client identifier and optionally the client secret that are assigned to your application by the OAuth 2.0 provider.
func HTTPClient ¶
HTTPClient allows you to provide a custom http.Client to be used to retrieve tokens from the OAuth 2.0 provider.
func JWTEndpoint ¶
JWTEndpoint requires the JWT token endpoint of the OAuth 2.0 provider.
func RedirectURL ¶
RedirectURL requires the URL to which the user will be returned after granting (or denying) access.
type Options ¶
type Options struct {
// ClientID is the OAuth client identifier used when communicating with
// the configured OAuth provider.
ClientID string
// ClientSecret is the OAuth client secret used when communicating with
// the configured OAuth provider.
ClientSecret string
// RedirectURL is the URL to which the user will be returned after
// granting (or denying) access.
RedirectURL string
// Email is the OAuth client identifier used when communicating with
// the configured OAuth provider.
Email string
// PrivateKey contains the contents of an RSA private key or the
// contents of a PEM file that contains a private key. The provided
// private key is used to sign JWT payloads.
// PEM containers with a passphrase are not supported.
// Use the following command to convert a PKCS 12 file into a PEM.
//
// $ openssl pkcs12 -in key.p12 -out key.pem -nodes
//
PrivateKey *rsa.PrivateKey
// Scopes identify the level of access being requested.
Subject string
// Scopes optionally specifies a list of requested permission scopes.
Scopes []string
// AuthURL represents the authorization endpoint of the OAuth 2.0 provider.
AuthURL *url.URL
// TokenURL represents the token endpoint of the OAuth 2.0 provider.
TokenURL *url.URL
// AUD represents the token endpoint required to complete the 2-legged JWT flow.
AUD *url.URL
// TokenStore reads a token from the store and writes it back to the store
// if a token refresh occurs.
// Optional.
TokenStore TokenStore
TokenFetcherFunc func(t *Token) (*Token, error)
Client *http.Client
}
Options represents an object to keep the state of the OAuth 2.0 flow.
func New ¶
New builds a new options object and determines the type of the OAuth 2.0 (2-legged, 3-legged or custom) by looking at the provided options. If the flow type cannot determined automatically, an error is returned.
func (*Options) AuthCodeURL ¶
AuthCodeURL returns a URL to OAuth 2.0 provider's consent page that asks for permissions for the required scopes explicitly.
State is a token to protect the user from CSRF attacks. You must always provide a non-zero string and validate that it matches the the state query parameter on your redirect callback. See http://tools.ietf.org/html/rfc6749#section-10.12 for more info.
Access type is an OAuth extension that gets sent as the "access_type" field in the URL from AuthCodeURL. It may be "online" (default) or "offline". If your application needs to refresh access tokens when the user is not present at the browser, then use offline. This will result in your application obtaining a refresh token the first time your application exchanges an authorization code for a user.
Approval prompt indicates whether the user should be re-prompted for consent. If set to "auto" (default) the user will be prompted only if they haven't previously granted consent and the code can only be exchanged for an access token. If set to "force" the user will always be prompted, and the code can be exchanged for a refresh token.
func (*Options) NewTransport ¶
NewTransport returns a Transport.
func (*Options) NewTransportFromCode ¶
NewTransportFromCode exchanges the code to retrieve a new access token and returns an authorized and authenticated Transport.
func (*Options) NewTransportFromTokenStore ¶
func (o *Options) NewTransportFromTokenStore(store TokenStore) (*Transport, error)
NewTransportFromTokenStore reads the token from the store and returns a Transport that is authorized and the authenticated by the returned token.
type Token ¶
type Token struct {
// A token that authorizes and authenticates the requests.
AccessToken string `json:"access_token"`
// Identifies the type of token returned.
TokenType string `json:"token_type,omitempty"`
// A token that may be used to obtain a new access token.
RefreshToken string `json:"refresh_token,omitempty"`
// The remaining lifetime of the access token.
Expiry time.Time `json:"expiry,omitempty"`
// contains filtered or unexported fields
}
Token represents the crendentials used to authorize the requests to access protected resources on the OAuth 2.0 provider's backend.
type TokenStore ¶
type TokenStore interface {
// ReadToken reads the token from the store.
// If the read is successful, it should return the token and a nil error.
// The returned tokens may be expired tokens.
// If there is no token in the store, it should return a nil token and a nil error.
// It should return a non-nil error when an unrecoverable failure occurs.
ReadToken() (*Token, error)
// WriteToken writes the token to the cache.
WriteToken(*Token)
}
TokenStore implementations read and write OAuth 2.0 tokens from a persistence layer.
type Transport ¶
type Transport struct {
// contains filtered or unexported fields
}
Transport is an http.RoundTripper that makes OAuth 2.0 HTTP requests.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package google provides support for making OAuth2 authorized and authenticated HTTP requests to Google APIs.
|
Package google provides support for making OAuth2 authorized and authenticated HTTP requests to Google APIs. |
|
Package jws provides encoding and decoding utilities for signed JWS messages.
|
Package jws provides encoding and decoding utilities for signed JWS messages. |