Documentation

Overview

    Package oauth implements an http.Handler that has two main purposes listed below:

    (1) Uses OAuth to authenticate and then renders a page that

    displays all the blessings that were provided for that Google user.
    The client calls the /listblessings route which redirects to listblessingscallback which
    renders the list.
    

    (2) Performs the oauth flow for seeking a blessing using the principal tool

    located at v.io/x/ref/cmd/principal.
    The seek blessing flow works as follows:
    (a) Client (principal tool) hits the /seekblessings route.
    (b) /seekblessings performs oauth with a redirect to /seekblessingscallback.
    (c) Client specifies desired caveats in the form that /seekblessingscallback displays.
    (d) Submission of the form sends caveat information to /sendmacaroon.
    (e) /sendmacaroon sends a macaroon with blessing information to client
        (via a redirect to an HTTP server run by the tool).
    (f) Client invokes bless rpc with macaroon.
    

    Index

    Constants

    View Source
    const (
    	ListBlessingsRoute = "listblessings"
    
    	SeekBlessingsRoute = "seekblessings"
    )

    Variables

    This section is empty.

    Functions

    func ClientIDAndSecretFromJSON

    func ClientIDAndSecretFromJSON(r io.Reader) (id, secret string, err error)

      ClientIDAndSecretFromJSON parses JSON-encoded API access information in 'r' and returns the extracted ClientID and ClientSecret. This JSON-encoded data is typically available as a download from the Google API Access console for your application (https://code.google.com/apis/console).

      func ClientIDFromJSON

      func ClientIDFromJSON(r io.Reader) (id string, err error)

        ClientIDFromJSON parses JSON-encoded API access information in 'r' and returns the extracted ClientID. This JSON-encoded data is typically available as a download from the Google API Access console for your application (https://code.google.com/apis/console).

        func ClientName

        func ClientName(clientID string, clients []AccessTokenClient) (string, error)

          ClientName checks if the provided clientID is present in one of the provided 'clients' and if so returns the corresponding client name. It returns an error otherwise.

          func NewHandler

          func NewHandler(ctx *context.T, args HandlerArgs) http.Handler

            NewHandler returns an http.Handler that expects to be rooted at args.Addr and can be used to authenticate with args.OAuthProvider, mint a new identity and bless it with the OAuthProvider email address.

            Types

            type AccessTokenClient

            type AccessTokenClient struct {
            	// Descriptive name of the client.
            	Name string
            	// OAuth Client ID.
            	ClientID string
            }

              AccessTokenClient represents a client of an OAuthProvider.

              type AuthURLApproval

              type AuthURLApproval bool

                Option to OAuthProvider.AuthURL controlling whether previously provided user consent can be re-used.

                const (
                	ExplicitApproval AuthURLApproval = false // Require explicit user consent.
                	ReuseApproval    AuthURLApproval = true  // Reuse a previous user consent if possible.
                )

                type BlessingMacaroon

                type BlessingMacaroon struct {
                	Creation  time.Time
                	Caveats   []security.Caveat
                	Name      string
                	PublicKey []byte // Marshaled public key of the principal tool.
                }

                  BlessingMacaroon contains the data that is encoded into the macaroon for creating blessings.

                  type HandlerArgs

                  type HandlerArgs struct {
                  	// The principal to use.
                  	Principal security.Principal
                  	// The Key that is used for creating and verifying macaroons.
                  	// This needs to be common between the handler and the MacaroonBlesser service.
                  	MacaroonKey []byte
                  	// URL at which the hander is installed.
                  	// e.g. http://host:port/google/
                  	Addr string
                  	// BlessingLogReder is needed for reading audit logs.
                  	BlessingLogReader auditor.BlessingLogReader
                  	// The RevocationManager is used to revoke blessings granted with a revocation caveat.
                  	// If nil, then revocation caveats cannot be added to blessings and an expiration caveat
                  	// will be used instead.
                  	RevocationManager revocation.RevocationManager
                  	// The object name of the discharger service.
                  	DischargerLocation string
                  	// MacaroonBlessingService is a function that returns the object names to which macaroons
                  	// created by this HTTP handler can be exchanged for a blessing.
                  	MacaroonBlessingService func() []string
                  	// OAuthProvider is used to authenticate and get a blessee email.
                  	OAuthProvider OAuthProvider
                  	// CaveatSelector is used to obtain caveats from the user when seeking a blessing.
                  	CaveatSelector caveats.CaveatSelector
                  	// AssetsPrefix is the host where web assets for rendering the list blessings template are stored.
                  	AssetsPrefix string
                  	// DischargeServers is the list of published disharges services.
                  	DischargeServers []string
                  }

                  type OAuthProvider

                  type OAuthProvider interface {
                  	// AuthURL is the URL the user must visit in order to authenticate with the OAuthProvider.
                  	// After authentication, the user will be re-directed to redirectURL with the provided state.
                  	AuthURL(redirectURL string, state string, approval AuthURLApproval) (url string)
                  	// ExchangeAuthCodeForEmail exchanges the provided authCode for the email of the
                  	// authenticated user on behalf of the token has been issued.
                  	ExchangeAuthCodeForEmail(authCode string, url string) (email string, err error)
                  	// GetEmailAndClientID returns the email and clientID associated with the token.
                  	GetEmailAndClientID(accessToken string) (email string, clientID string, err error)
                  }

                    OAuthProvider authenticates users to the identity server via the OAuth2 Web Server flow.

                    func NewGoogleOAuth

                    func NewGoogleOAuth(ctx *context.T, configFile string) (OAuthProvider, error)

                    func NewMockOAuth

                    func NewMockOAuth(mockEmail, mockClientID string) OAuthProvider