oauth

README

OAUTH

This is a simple OAUTH Login Middleware is provided. Tokens are stored in encrypted cookies in the callers browser. Functionality uses the golang oauth2 library.

Configuration Flow

• ConfigCookies (optional)
  • Configures the name and path for cookies
    • Defaults:
      • Path: /
      • State Cookie: rutarState
        • Cookie used for storing the encrypted state value used for the OAUTH transaction. This is used for comparison on the redirect from the OAUTH provider.
      • Token Cookie: rutarToken
        • Cookie used for storing the encrypted OAUTH token.
• ConfigStateTimeout (optional)
  • Sets the timeout for the state used in OAUTH
    • Default
      • 300 seconds (5 minutes)
• ConfigKeyPhrase (REQUIRED)
  • Configures key phrase used to decrypt and encrypted the stored token.
  • The KeyPhrase can be generated with openssl rand -hex 32
• ConfigOAUTH (REQUIRED)
  • Configures the OAUTH provider
    • ProviderURL is the URL for the OAUTH2 Provider
      • Example: https://accounts.google.com
    • ClientID is the OAUTH2 client ID provided by the OAUTH provider
    • ClientSecret is the OAUTH2 client secret provided by the OAUTH provider
    • RedirectURL is the URL to redirect users to after the OAUTH2 login flow
    • Scopes are the OAUTH2 scopes that will be requested during the OAUTH2 flow

OAUTH Flow

• handler_oauth_start starts the OAUTH flow.
  • eg: This can be used as your /login handler
  • Retrieved with NewOAUTHStartHandler
• handler_oauth_callback handles the callback from an OAUTH service.
  • eg: This can be used as your /callback or /oauth/ handler
  • Retrieved with NewOAUTHCallbackHandler
• ExchangeCookie handles logins with encrypted token data stored in a cookie
  • Validates the stored token before returning an AuthHolder
• ExchangeLoginHeader handles logins with encrypted token data stored in an Authorization Header.
  • Validates the stored token before returning an AuthHolder
• Returned AuthHolders can be used to return a client that is used to communicate with endpoints requiring OAUTH2 authentication / authorization. They also provide functionality to encrypt the refreshed OAUTH2 token so it can be returned to the caller for later use.

Documentation

Index

• func ConfigCookies(path string, stateName string, tokenName string)
• func ConfigKeyPhrase(keyPhrase string) error
• func ConfigOAUTH(providerURL string, clientID string, clientSecret string, redirectURL string, ...) error
• func ConfigStateTimeout(timeout int)
• func NewOAUTHCallbackHandler(l log.Logger) http.Handler
• func NewOAUTHStartHandler(l log.Logger) http.Handler
• type AuthHolder
  • func ExchangeLoginCookie(w http.ResponseWriter, r *http.Request, l log.Logger) (AuthHolder, bool)
  • func ExchangeLoginHeader(w http.ResponseWriter, r *http.Request, l log.Logger) (AuthHolder, bool)

Functions

func ConfigCookies

func ConfigCookies(path string, stateName string, tokenName string)

ConfigCookies handles configurations of cookies

Note:

• path refers the path set in the cookie
• stateName is the name of the cookie that will hold the encrypted state during the beginning of an OAUTH Login
• tokenName is the name of the cookie that will hold the encrypted OAUTH token after a successful OAUTH login

func ConfigKeyPhrase

func ConfigKeyPhrase(keyPhrase string) error

ConfigKeyPhrase validates the provided key phrase and then stores it for usage.

This key phrase is used for encrypting and decrypting the OAUTH2 token that is stored client side.

Generate the KeyPhrase with `openssl rand -hex 32`

func ConfigOAUTH

func ConfigOAUTH(providerURL string, clientID string, clientSecret string, redirectURL string, scopes []string) error

ConfigOAUTH configures the OAUTH2 handlers

providerURL is the URL for the OAUTH2 Provider * Example: https://accounts.google.com clientID is the OAUTH2 client ID provided by the OAUTH provider clientSecret is the OAUTH2 client secret provided by the OAUTH provider sRedirectURL is the URL to redirect users to after the OAUTH2 login flow scopes are the OAUTH2 scopes that will be requested during the OAUTH2 flow

func ConfigStateTimeout

func ConfigStateTimeout(timeout int)

ConfigStateTimeout sets the timeout to be used for honoring state token expiration

The default is 300 seconds (5 minutes) if no timeout is provided

func NewOAUTHCallbackHandler

func NewOAUTHCallbackHandler(l log.Logger) http.Handler

NewOAUTHCallbackHandler returns a handler that handles an OAUTH callback from the provider.

func NewOAUTHStartHandler

func NewOAUTHStartHandler(l log.Logger) http.Handler

NewOAUTHStartHandler returns a handler that starts an OAUTH Authentication loop.

Types

type AuthHolder

type AuthHolder interface {
	// Client returns an HTTP client that uses the OAUTH2 token for communication
	Client(log.Logger) *http.Client
	// Encrypt returns the stored OAUTH2 token in encrypted form
	//
	// If any errors are experienced during token retrieval or encryption,
	// returns codes for the HTTP response writer are automatically set.
	//
	// # This should be called as the last step before writing a final response
	//
	// Returns:
	//
	//	encrypted token: Encrypted form of the OAUTH2 token
	//	success: If the function was successful
	//
	// Note:
	//
	//	On an unsuccessful run, the HTTP status code and returned JSON are automatically written to the HTTP response
	//	writer.
	Encrypt(http.ResponseWriter, log.Logger) (string, bool)
}

AuthHolder holds a validated OAUTH2 token for usage outside the OAUTH2 middleware

func ExchangeLoginCookie

func ExchangeLoginCookie(w http.ResponseWriter, r *http.Request, l log.Logger) (AuthHolder, bool)

ExchangeLoginCookie retrieves encrypted authentication data from a stored cookie and exchanges it for an OAUTH2 token, validates the token, and returns it in an AuthHolder

Returns:

AuthHolder: The AuthHolder interface containing an OAUTH2.Source for token retrieval
success: If the function was successful

Note:

On an unsuccessful run, the HTTP status code and returned JSON are automatically written to the HTTP response
writer.

func ExchangeLoginHeader

func ExchangeLoginHeader(w http.ResponseWriter, r *http.Request, l log.Logger) (AuthHolder, bool)

ExchangeLoginHeader retrieves encrypted authentication data from the Authorization header, exchanges it for an OAUTH2 token, validates the token, and returns it in an AuthHolder

Returns:

AuthHolder: The AuthHolder interface containing an OAUTH2.Source for token retrieval
success: If the function was successful

Note:

On an unsuccessful run, the HTTP status code and returned JSON are automatically written to the HTTP response
writer.