Documentation

Overview

    Package server implements authentication for inbound HTTP requests on GAE. It provides adapters for GAE Users and OAuth2 APIs to make them usable by server/auth package.

    It also provides GAE-specific implementation of some other interface used by server/auth package, such as SessionStore.

    By default, gaeauth must have its handlers installed into the "default" AppEngine module, and must be running on an instance with read/write datastore access.

    Deprecated: this package depends on deprecated GAE first-gen APIs.

    Index

    Constants

    View Source
    const EmailScope = "https://www.googleapis.com/auth/userinfo.email"

      EmailScope is a scope used to identifies user's email. Present in most tokens by default. Can be used as a base scope for authentication.

      Variables

      View Source
      var CookieAuth auth.Method

        CookieAuth is default cookie-based auth method to use on GAE.

        By default on the dev server it is based on dev server cookies (implemented by UsersAPIAuthMethod), in prod it is based on OpenID (implemented by *deprecated.CookieAuthMethod).

        Works only if appropriate handlers have been installed into the router. See InstallHandlers.

        It is allowed to assign to CookieAuth (e.g. to install a tweaked auth method) before InstallHandlers is called. In particular, use SwitchToEncryptedCookies to update to a better (but incompatible) method.

        Deprecated: this method depends on Users API not available outside of the GAE first-gen runtime and uses deprecated CookieAuthMethod. Use go.chromium.org/luci/server/encryptedcookies instead. To facilitate the migration you can switch to the encrypted cookies while still running on the GAE first-gen runtime by calling SwitchToEncryptedCookies() early during the server initialization.

        Functions

        func FetchFrontendClientID

        func FetchFrontendClientID(ctx context.Context) (string, error)

          FetchFrontendClientID fetches the frontend client ID from the settings store.

          func GetAuthDB

          func GetAuthDB(ctx context.Context, prev authdb.DB) (authdb.DB, error)

            GetAuthDB fetches AuthDB snapshot from the datastore and returns authdb.DB interface wrapping it.

            It may reuse existing one (`prev`), if no changes were made. If `prev` is nil, always fetches a new copy from the datastore.

            If auth_service URL is not configured, returns special kind of authdb.DB that implements some default authorization rules (allow everything on dev server, forbid everything and emit errors on real GAE).

            func InstallHandlers

            func InstallHandlers(r *router.Router, base router.MiddlewareChain)

              InstallHandlers installs HTTP handlers for various default routes related to authentication system.

              Must be installed in server HTTP router for authentication to work.

              func SwitchToEncryptedCookies

              func SwitchToEncryptedCookies()

                SwitchToEncryptedCookies opts-in CookieAuth to use a better implementation.

                The "better implementation" is not backward compatible with the previous one, i.e. all existing user sessions are ignored. Calling this function is an acknowledgment that it is OK to relogin all users when making the switch.

                Must be called before InstallHandlers.

                Types

                type InboundAppIDAuthMethod

                type InboundAppIDAuthMethod struct{}

                  InboundAppIDAuthMethod implements auth.Method by checking special HTTP header (X-Appengine-Inbound-Appid), that is set iff one GAE app talks to another.

                  Deprecated: switch to using service accounts for authenticating calls between services instead.

                  func (InboundAppIDAuthMethod) Authenticate

                    Authenticate extracts peer's identity from the incoming request.

                    type OAuth2Method

                    type OAuth2Method struct {
                    	// Scopes is a list of OAuth scopes to check when authenticating the token.
                    	Scopes []string
                    }

                      OAuth2Method implements auth.Method on top of GAE OAuth2 API. It doesn't implement auth.UsersAPI.

                      Deprecated: use GoogleOAuth2Method from go.chromium.org/luci/server/auth instead.

                      func (*OAuth2Method) Authenticate

                      func (m *OAuth2Method) Authenticate(ctx context.Context, r *http.Request) (*auth.User, auth.Session, error)

                        Authenticate extracts peer's identity from the incoming request.

                        func (*OAuth2Method) GetUserCredentials

                        func (m *OAuth2Method) GetUserCredentials(ctx context.Context, r *http.Request) (*oauth2.Token, error)

                          GetUserCredentials implements auth.UserCredentialsGetter.

                          type SessionStore

                          type SessionStore struct {
                          	Prefix string // used as prefix for datastore keys
                          }

                            SessionStore stores auth sessions in the datastore (always in the default namespace). It implements deprecated.SessionStore.

                            Deprecated: it is used only by the deprecated CookiesAuth and should not be used directly anywhere else.

                            func (*SessionStore) CloseSession

                            func (s *SessionStore) CloseSession(ctx context.Context, sessionID string) error

                              CloseSession closes a session given its ID. Does nothing if session is already closed or doesn't exist. Returns only transient errors.

                              func (*SessionStore) GetSession

                              func (s *SessionStore) GetSession(ctx context.Context, sessionID string) (*deprecated.Session, error)

                                GetSession returns existing non-expired session given its ID. Returns nil if session doesn't exist, closed or expired. Returns only transient errors.

                                func (*SessionStore) OpenSession

                                func (s *SessionStore) OpenSession(ctx context.Context, userID string, u *auth.User, exp time.Time) (string, error)

                                  OpenSession create a new session for a user with given expiration time. It returns unique session ID.

                                  type UsersAPIAuthMethod

                                  type UsersAPIAuthMethod struct{}

                                    UsersAPIAuthMethod implements auth.Method and auth.UsersAPI interfaces on top of GAE Users API (that uses HTTP cookies internally to track user sessions).

                                    Deprecated: this method depends on Users API not available outside of the GAE first-gen runtime. Use go.chromium.org/luci/server/encryptedcookies instead.

                                    func (UsersAPIAuthMethod) Authenticate

                                    func (m UsersAPIAuthMethod) Authenticate(ctx context.Context, r *http.Request) (*auth.User, auth.Session, error)

                                      Authenticate extracts peer's identity from the incoming request.

                                      func (UsersAPIAuthMethod) LoginURL

                                      func (m UsersAPIAuthMethod) LoginURL(ctx context.Context, dest string) (string, error)

                                        LoginURL returns a URL that, when visited, prompts the user to sign in, then redirects the user to the URL specified by dest.

                                        func (UsersAPIAuthMethod) LogoutURL

                                        func (m UsersAPIAuthMethod) LogoutURL(ctx context.Context, dest string) (string, error)

                                          LogoutURL returns a URL that, when visited, signs the user out, then redirects the user to the URL specified by dest.

                                          Directories

                                          Path Synopsis
                                          Package gaesigner implements signing.Signer interface using GAE App Identity API.
                                          Package gaesigner implements signing.Signer interface using GAE App Identity API.
                                          internal
                                          authdbimpl
                                          Package authdbimpl implements datastore-based storage and update of AuthDB snapshots used for authorization decisions by server/auth/*.
                                          Package authdbimpl implements datastore-based storage and update of AuthDB snapshots used for authorization decisions by server/auth/*.