Back to godoc.org

Package auth

v0.0.0-...-1557bcf
Latest Go to latest

The latest major version is .

Published: Aug 13, 2020 | License: Apache-2.0 | Module: github.com/luci/luci-go

Overview

Package auth implements authentication and authorization framework for HTTP servers.

Index

Constants

const (
	// InternalServicesGroup is a name of a group with service accounts of LUCI
	// microservices of the current LUCI deployment (and only them!).
	//
	// Accounts in this group are allowed to use X-Luci-Project header to specify
	// that RPCs are done in a context of some particular project. For such
	// requests CurrentIdentity() == 'project:<X-Luci-Project value>'.
	//
	// This group should contain only **fully trusted** services, deployed and
	// managed by the LUCI deployment administrators. Adding "random" services
	// here is a security risk, since they will be able to impersonate any LUCI
	// project.
	InternalServicesGroup = "auth-luci-services"
)
const (
	// MaxDelegationTokenTTL is maximum allowed token lifetime that can be
	// requested via MintDelegationToken.
	MaxDelegationTokenTTL = 3 * time.Hour
)
const (
	// MaxScopedTokenTTL is maximum allowed token lifetime that can be
	// requested via MintScopedToken.
	MaxScopedTokenTTL = 15 * time.Minute
)
const XLUCIProjectHeader = "X-Luci-Project"

XLUCIProjectHeader is a header with the current project for internal LUCI RPCs done via AsProject authority.

Variables

var (

	// ErrNotConfigured is returned by Authenticate and other functions if the
	// context wasn't previously initialized via 'Initialize'.
	ErrNotConfigured = errors.New("auth: the library is not properly configured", grpcutil.InternalTag)

	// ErrBadClientID is returned by Authenticate if caller is using
	// non-whitelisted OAuth2 client. More info is in the log.
	ErrBadClientID = errors.New("auth: OAuth client_id is not whitelisted", grpcutil.PermissionDeniedTag)

	// ErrBadAudience is returned by Authenticate if token's audience is unknown.
	ErrBadAudience = errors.New("auth: bad token audience", grpcutil.PermissionDeniedTag)

	// ErrBadRemoteAddr is returned by Authenticate if request's remote_addr can't
	// be parsed.
	ErrBadRemoteAddr = errors.New("auth: bad remote addr", grpcutil.InternalTag)

	// ErrIPNotWhitelisted is returned when an account is restricted by an IP
	// whitelist and request's remote_addr is not in it.
	ErrIPNotWhitelisted = errors.New("auth: IP is not whitelisted", grpcutil.PermissionDeniedTag)

	// ErrProjectHeaderForbidden is returned by Authenticate if an unknown caller
	// tries to use X-Luci-Project header. Only a whitelisted set of callers
	// are allowed to use this header, see InternalServicesGroup.
	ErrProjectHeaderForbidden = errors.New("auth: the caller is not allowed to use X-Luci-Project", grpcutil.PermissionDeniedTag)

	// ErrNoUsersAPI is returned by LoginURL and LogoutURL if none of
	// the authentication methods support UsersAPI.
	ErrNoUsersAPI = errors.New("auth: methods do not support login or logout URL")

	// ErrNoForwardableCreds is returned by GetRPCTransport when attempting to
	// forward credentials (via AsCredentialsForwarder) that are not forwardable.
	ErrNoForwardableCreds = errors.New("auth: no forwardable credentials in the context")
)
var (
	// ErrTokenServiceNotConfigured is returned by MintDelegationToken if the
	// token service URL is not configured. This usually means the corresponding
	// auth service is not paired with a token server.
	ErrTokenServiceNotConfigured = fmt.Errorf("auth: token service URL is not configured")

	// ErrBrokenTokenService is returned by MintDelegationToken if the RPC to the
	// token service succeeded, but response doesn't make sense. This should not
	// generally happen.
	ErrBrokenTokenService = fmt.Errorf("auth: unrecognized response from the token service")

	// ErrAnonymousDelegation is returned by MintDelegationToken if it is used in
	// a context of handling of an anonymous call.
	//
	// There's no identity to delegate in this case.
	ErrAnonymousDelegation = fmt.Errorf("auth: can't get delegation token for anonymous user")

	// ErrBadTargetHost is returned by MintDelegationToken if it receives invalid
	// TargetHost parameter.
	ErrBadTargetHost = fmt.Errorf("auth: invalid TargetHost (doesn't look like a hostname:port pair)")

	// ErrBadTokenTTL is returned by MintDelegationToken and MintProjectToken if requested
	// token lifetime is outside of the allowed range.
	ErrBadTokenTTL = fmt.Errorf("auth: requested token TTL is invalid")

	// ErrBadDelegationTag is returned by MintDelegationToken if some of the
	// passed tags are malformed.
	ErrBadDelegationTag = fmt.Errorf("auth: provided delegation tags are invalid")
)
var (
	// ErrBadOAuthToken is returned by GoogleOAuth2Method if the access token it
	// checks either totally invalid, expired or has a wrong list of scopes.
	ErrBadOAuthToken = errors.New("oauth: bad access token", grpcutil.UnauthenticatedTag)

	// ErrBadAuthorizationHeader is returned by GoogleOAuth2Method if it doesn't
	// recognize the format of Authorization header.
	ErrBadAuthorizationHeader = errors.New("oauth: bad Authorization header", grpcutil.UnauthenticatedTag)
)
var CloudOAuthScopes = []string{
	"https://www.googleapis.com/auth/cloud-platform",
	"https://www.googleapis.com/auth/userinfo.email",
}

CloudOAuthScopes is a list of OAuth scopes recommended to use when authenticating to Google Cloud services.

Besides the actual cloud-platform scope also includes userinfo.email scope, so that it is possible to examine the token email.

Note that it is preferable to use the exact same list of scopes in all Cloud API clients. That way when the server runs locally in a development mode, we need to go through the login flow only once. Using different scopes for different clients would require to "login" for each unique set of scopes.

func Authenticate

func Authenticate(m ...Method) router.Middleware

Authenticate returns a middleware that performs authentication.

Typically you only one one Method, but you may specify multiple Methods to be tried in order (see Authenticator).

This middleware either updates the context by injecting the authentication state into it (enabling functions like CurrentIdentity and IsMember), or aborts the request with an HTTP 401 or HTTP 500 error.

Note that it passes through anonymous requests. CurrentIdentity returns identity.AnonymousIdentity in this case. Use separate authorization layer to further restrict the access, if necessary.

func CurrentIdentity

func CurrentIdentity(c context.Context) identity.Identity

CurrentIdentity return identity of the current caller.

Shortcut for GetState(c).User().Identity(). Returns AnonymousIdentity if the context doesn't have State.

func GetDB

func GetDB(c context.Context) (authdb.DB, error)

GetDB returns most recent snapshot of authorization database using DBProvider installed in the context via 'Initialize' or 'ModifyConfig'.

If no factory is installed, returns DB that forbids everything and logs errors. It is often good enough for unit tests that do not care about authorization, and still not horribly bad if accidentally used in production.

func GetFrontendClientID

func GetFrontendClientID(c context.Context) (string, error)

GetFrontendClientID returns an OAuth 2.0 client ID to use from the frontend.

If it is not configured returns an empty string. May return an error if it could not be fetched. Such error should be treated as transient.

This client ID is served via /auth/api/v1/server/client_id endpoint (so that the frontend can grab it), and the auth library permits access tokens with this client as an audience when authenticating requests.

func GetPerRPCCredentials

func GetPerRPCCredentials(ctx context.Context, kind RPCAuthorityKind, opts ...RPCOption) (credentials.PerRPCCredentials, error)

GetPerRPCCredentials returns gRPC's PerRPCCredentials implementation.

It can be used to authenticate outbound gPRC RPC's.

func GetRPCTransport

func GetRPCTransport(ctx context.Context, kind RPCAuthorityKind, opts ...RPCOption) (http.RoundTripper, error)

GetRPCTransport returns http.RoundTripper to use for outbound HTTP RPC requests.

Usage:

tr, err := auth.GetRPCTransport(c, auth.AsSelf, auth.WithScopes("..."))
if err != nil {
  return err
}
client := &http.Client{Transport: tr}
...

func GetSigner

func GetSigner(c context.Context) signing.Signer

GetSigner returns the signing.Signer instance representing the service.

It is injected into the context as part of Config. It can be used to grab a service account the service is running as or its current public certificates.

Returns nil if the signer is not available.

func GetTokenSource

func GetTokenSource(ctx context.Context, kind RPCAuthorityKind, opts ...RPCOption) (oauth2.TokenSource, error)

GetTokenSource returns an oauth2.TokenSource bound to the supplied Context.

Supports only AsSelf, AsCredentialsForwarder and AsActor authority kinds, since they are the only ones that exclusively use only Authorization header.

While GetPerRPCCredentials is preferred, this can be used by packages that cannot or do not properly handle this gRPC option.

func HasPermission

func HasPermission(c context.Context, perm realms.Permission, realm string) (bool, error)

HasPermission returns true if the current caller has the given permission in the realm.

A non-existing realm is replaced with the corresponding root realm (e.g. if "projectA:some/realm" doesn't exist, "projectA:@root" will be used in its place). If the project doesn't exist or is not using realms yet, all its realms (including the root realm) are considered empty. HasPermission returns false in this case.

Returns an error only if the check itself failed due to a misconfiguration or transient issues. This should usually result in an Internal error.

func Initialize

func Initialize(c context.Context, cfg *Config) context.Context

Initialize inserts authentication configuration into the context.

An initialized context is required by any other function in the package. They return ErrNotConfigured otherwise.

Calling Initialize twice causes a panic.

func InstallHandlers

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

InstallHandlers installs authentication related HTTP handlers.

All new HTTP routes live under '/auth/api/' prefix.

If you are using appengine/gaeauth/server, these handlers are already installed.

func IsInWhitelist

func IsInWhitelist(c context.Context, whitelist string) (bool, error)

IsInWhitelist returns true if the current caller is in the given IP whitelist.

Unknown whitelists are considered empty (the function returns false).

May return errors if the check can not be performed (e.g. on datastore issues).

func IsMember

func IsMember(c context.Context, groups ...string) (bool, error)

IsMember returns true if the current caller is in any of the given groups.

Unknown groups are considered empty (the function returns false).

May return errors if the check can not be performed (e.g. on datastore issues).

func LoginURL

func LoginURL(c 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.

Shortcut for GetState(c).Authenticator().LoginURL(...).

func LogoutURL

func LogoutURL(c 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.

Shortcut for GetState(c).Authenticator().LogoutURL(...).

func ModifyConfig

func ModifyConfig(c context.Context, cb func(Config) Config) context.Context

ModifyConfig makes a context with a derived configuration.

It grabs current configuration from the context (if any), passes it to the callback, and puts whatever callback returns into a derived context.

func WithState

func WithState(c context.Context, s State) context.Context

WithState injects State into the context.

Mostly useful from tests. Must not be normally used from production code, 'Authenticate' sets the state itself.

type AccessTokenProvider

type AccessTokenProvider func(c context.Context, scopes []string) (*oauth2.Token, error)

AccessTokenProvider knows how to generate OAuth2 access token for the service account belonging to the server itself.

type AnonymousTransportProvider

type AnonymousTransportProvider func(c context.Context) http.RoundTripper

AnonymousTransportProvider returns http.RoundTriper that can make unauthenticated HTTP requests.

The returned round tripper is assumed to be bound to the context and won't outlive it.

type Authenticator

type Authenticator struct {
	Methods []Method // a list of authentication methods to try
}

Authenticator performs authentication of incoming requests.

It is a stateless object configured with a list of methods to try when authenticating incoming requests. It implements Authenticate method that performs high-level authentication logic using the provided list of low-level auth methods.

Note that most likely you don't need to instantiate this object directly. Use Authenticate middleware instead. Authenticator is exposed publicly only to be used in advanced cases, when you need to fine-tune authentication behavior.

func (*Authenticator) Authenticate

func (a *Authenticator) Authenticate(ctx context.Context, r *http.Request) (_ context.Context, err error)

Authenticate authenticates the requests and adds State into the context.

Returns an error if credentials are provided, but invalid. If no credentials are provided (i.e. the request is anonymous), finishes successfully, but in that case CurrentIdentity() returns AnonymousIdentity.

The returned error may be tagged with an grpcutil error tag. Its code should be used to derive the response status code. Internal error messages (e.g. ones tagged with grpcutil.InternalTag or similar) should be logged, but not sent to clients. All other errors should be sent to clients as is.

func (*Authenticator) GetMiddleware

func (a *Authenticator) GetMiddleware() router.Middleware

GetMiddleware returns a middleware that uses this Authenticator for authentication.

It uses a.Authenticate internally and handles errors appropriately.

func (*Authenticator) LoginURL

func (a *Authenticator) 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.

Returns ErrNoUsersAPI if none of the authentication methods support login URLs.

func (*Authenticator) LogoutURL

func (a *Authenticator) 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.

Returns ErrNoUsersAPI if none of the authentication methods support login URLs.

type Config

type Config struct {
	// DBProvider is a callback that returns most recent DB instance.
	DBProvider DBProvider

	// Signer possesses the service's private key and can sign blobs with it.
	//
	// It provides the bundle with corresponding public keys and information about
	// the service account they belong too (the service's own identity).
	//
	// Used to implement '/auth/api/v1/server/(certificates|info)' routes.
	Signer signing.Signer

	// AccessTokenProvider knows how to generate OAuth2 access token for the
	// service account belonging to the server itself.
	AccessTokenProvider AccessTokenProvider

	// AnonymousTransport returns http.RoundTriper that can make unauthenticated
	// HTTP requests.
	//
	// The returned round tripper is assumed to be bound to the context and won't
	// outlive it.
	AnonymousTransport AnonymousTransportProvider

	// EndUserIP takes a request and returns IP address of a user that sent it.
	//
	// If nil, a default implementation is used. It simply returns r.RemoteAddr.
	//
	// A custom implementation may parse X-Forwarded-For header (or other headers)
	// depending on how load balancers and proxies in front the server populate
	// them.
	EndUserIP func(r *http.Request) string

	// FrontendClientID returns an OAuth 2.0 client ID to use from the frontend.
	//
	// It will be served via /auth/api/v1/server/client_id endpoint (so that the
	// frontend can grab it), and the auth library will permit access tokens with
	// this client as an audience when authenticating requests.
	//
	// May return an empty string if the client ID is not configured. All errors
	// are treated as transient.
	//
	// Should be fast. Will be called each time a token needs to be authenticated.
	FrontendClientID func(context.Context) (string, error)

	// IsDevMode is true when running the server locally during development.
	//
	// Setting this to true changes default deadlines. For instance, GAE dev
	// server is known to be very slow and deadlines tuned for production
	// environment are too limiting.
	IsDevMode bool
}

Config contains global configuration of the auth library.

This configuration adjusts the library to the particular execution environment (GAE, Flex, whatever). It contains concrete implementations of various interfaces used by the library.

It lives in the context and must be installed there by some root middleware (via ModifyConfig call).

type DBProvider

type DBProvider func(c context.Context) (authdb.DB, error)

DBProvider is a callback that returns most recent DB instance.

DB represents a snapshot of user groups used for authorization checks.

type DelegationTokenParams

type DelegationTokenParams struct {
	// TargetHost, if given, is hostname (with, possibly, ":port") of a service
	// that the token will be sent to.
	//
	// If this parameter is used, the resulting delegation token is scoped
	// only to the service at TargetHost. All other services will reject it.
	//
	// Must be set if Untargeted is false. Ignored if Untargeted is true.
	TargetHost string

	// Untargeted, if true, indicates that the caller is requesting a token that
	// is not scoped to any particular service.
	//
	// Such token can be sent to any supported LUCI service. Only whitelisted set
	// of callers have such superpower.
	//
	// If Untargeted is true, TargetHost is ignored.
	Untargeted bool

	// MinTTL defines an acceptable token lifetime.
	//
	// The returned token will be valid for at least MinTTL, but no longer than
	// MaxDelegationTokenTTL (which is 3h).
	//
	// Default is 10 min.
	MinTTL time.Duration

	// Intent is a reason why the token is created.
	//
	// Used only for logging purposes on the auth service, will be indexed. Should
	// be a short identifier-like string.
	//
	// Optional.
	Intent string

	// Tags are optional arbitrary key:value pairs embedded into the token.
	//
	// They convey circumstance of why the token is created.
	//
	// Services that accept the token may use them for additional authorization
	// decisions. Please use extremely carefully, only when you control both sides
	// of the delegation link and can guarantee that services involved understand
	// the tags.
	Tags []string
	// contains filtered or unexported fields
}

DelegationTokenParams is passed to MintDelegationToken.

type GoogleOAuth2Method

type GoogleOAuth2Method struct {
	// Scopes is a list of OAuth scopes to check when authenticating the token.
	Scopes []string
	// contains filtered or unexported fields
}

GoogleOAuth2Method implements Method via Google's OAuth2 token info endpoint.

Note that it uses the endpoint which "has no SLA and is not intended for production use". The closest alternative is /userinfo endpoint, but it doesn't return the token expiration time (so we can't cache the result of the check) nor the list of OAuth scopes the token has, nor the client ID to check against a whitelist.

The general Google's recommendation is to use access tokens only for accessing Google APIs and use OpenID Connect Identity tokens for authentication in your own services instead (they are locally verifiable JWTs).

Unfortunately, using OpenID tokens for LUCI services and OAuth2 access token for Google services significantly complicates clients, especially in non-trivial cases (like authenticating from a Swarming job): they now must support two token kinds and know which one to use when.

There's no solution currently that preserves all of correctness, performance, usability and availability:

* Using /tokeninfo (like is done currently) sacrifices availability.
* Using /userinfo sacrifices correctness (no client ID or scopes check).
* Using OpenID ID tokens scarifies usability for the clients.

func (*GoogleOAuth2Method) Authenticate

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

Authenticate implements Method.

func (*GoogleOAuth2Method) GetUserCredentials

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

GetUserCredentials implements UserCredentialsGetter.

type HasHandlers

type HasHandlers interface {
	// InstallHandlers installs necessary HTTP handlers into the router.
	InstallHandlers(r *router.Router, base router.MiddlewareChain)
}

HasHandlers may be additionally implemented by Method if it needs to install HTTP handlers.

type HasPermissionDryRun

type HasPermissionDryRun struct {
	ExpectedResult bool   // the expected result of this dry run
	TrackingBug    string // identifier of a particular migration, for logs
}

HasPermissionDryRun compares result of HasPermission to 'expected'.

Intended to be used during the migration between the old and new ACL models.

func (HasPermissionDryRun) Execute

func (dr HasPermissionDryRun) Execute(c context.Context, perm realms.Permission, realm string)

Execute calls HasPermission and compares the result to the expectations.

Logs information about the call and any errors or discrepancies found.

Accepts same arguments as HasPermission. Intentionally returns nothing.

type Method

type Method interface {
	// Authenticate extracts user information from the incoming request.
	//
	// It returns:
	//   * (*User, nil) on success.
	//   * (nil, nil) if the method is not applicable.
	//   * (nil, error) if the method is applicable, but credentials are invalid.
	//
	// The returned error may be tagged with an grpcutil error tag. Its code will
	// be used to derive the response status code. Internal error messages (e.g.
	// ones tagged with grpcutil.InternalTag or similar) are logged, but not sent
	// to clients. All other errors are sent to clients as is.
	Authenticate(context.Context, *http.Request) (*User, error)
}

Method implements a particular kind of low-level authentication mechanism.

It may also optionally implement a bunch of other interfaces:

UsersAPI: if the method supports login and logout URLs.
Warmable: if the method supports warm up.
HasHandlers: if the method needs to install HTTP handlers.

Methods are not usually used directly, but passed to Authenticator{...} that knows how to apply them.

type MintAccessTokenParams

type MintAccessTokenParams struct {
	// ServiceAccount is an email of a service account to mint a token for.
	ServiceAccount string

	// Scopes is a list of OAuth scopes the token should have.
	Scopes []string

	// MinTTL defines an acceptable token lifetime.
	//
	// The returned token will be valid for at least MinTTL, but no longer than
	// one hour.
	//
	// Default is 2 min.
	MinTTL time.Duration
}

MintAccessTokenParams is passed to MintAccessTokenForServiceAccount.

type MintIDTokenParams

type MintIDTokenParams struct {
	// ServiceAccount is an email of a service account to mint a token for.
	ServiceAccount string

	// Audience is a target audience of the token.
	Audience string

	// MinTTL defines an acceptable token lifetime.
	//
	// The returned token will be valid for at least MinTTL, but no longer than
	// one hour.
	//
	// Default is 2 min.
	MinTTL time.Duration
}

MintIDTokenParams is passed to MintIDTokenForServiceAccount.

type ProjectTokenParams

type ProjectTokenParams struct {
	// LuciProject is the name of the LUCI project for which a token will be obtained.
	LuciProject string

	// OAuthScopes resemble the requested OAuth scopes for which the token is valid.
	OAuthScopes []string

	// MinTTL defines a minimally acceptable token lifetime.
	//
	// The returned token will be valid for at least MinTTL, but no longer than
	// MaxScopedTokenTTL (which is 15min).
	//
	// Default is 2 min.
	MinTTL time.Duration
	// contains filtered or unexported fields
}

ProjectTokenParams defines the parameters to create project scoped service account OAuth2 tokens.

type RPCAuthorityKind

type RPCAuthorityKind int

RPCAuthorityKind defines under whose authority RPCs are made.

const (
	// NoAuth is used for outbound RPCs that don't have any implicit auth headers.
	NoAuth RPCAuthorityKind = iota

	// AsSelf is used for outbound RPCs sent with the authority of the current
	// service itself.
	//
	// RPC requests done in this mode will have 'Authorization' header set to
	// either an OAuth2 access token or an ID token, depending on a presence of
	// WithIDTokenAudience option.
	//
	// If WithIDTokenAudience is not given, RPCs will be authenticated with
	// an OAuth2 access token of the service's own service account. The set of
	// OAuth scopes can be customized via WithScopes option, and by default it
	// is ["https://www.googleapis.com/auth/userinfo.email"].
	//
	// If WithIDTokenAudience is given, RPCs will be authenticated with an ID
	// token that has `aud` claim set to the supplied value. WithScopes can't be
	// used in this case, providing it will cause an error.
	//
	// In LUCI services AsSelf should be used very sparingly, only for internal
	// "maintenance" RPCs that happen outside of the context of any LUCI project.
	// Using AsSelf to authorize RPCs that touch project data leads to "confused
	// deputy" problems. Prefer to use AsProject when possible.
	AsSelf

	// AsUser is used for outbound RPCs that inherit the authority of a user
	// that initiated the request that is currently being handled, regardless of
	// how exactly the user was authenticated.
	//
	// DEPRECATED.
	//
	// The implementation is based on LUCI-specific protocol that uses special
	// delegation tokens. Only LUCI backends can understand them.
	//
	// If you need to call non-LUCI services, and incoming requests are
	// authenticated via OAuth access tokens, use AsCredentialsForwarder instead.
	//
	// If the current request was initiated by an anonymous caller, the RPC will
	// have no auth headers (just like in NoAuth mode).
	//
	// Can also be used together with MintDelegationToken to make requests on
	// user behalf asynchronously. For example, to associate end-user authority
	// with some delayed task, call MintDelegationToken (in a context of a user
	// initiated request) when this task is created and store the resulting token
	// along with the task. Then, to make an RPC on behalf of the user from the
	// task use GetRPCTransport(ctx, AsUser, WithDelegationToken(token)).
	AsUser

	// AsCredentialsForwarder is used for outbound RPCs that just forward the
	// user credentials, exactly as they were received by the service.
	//
	// For authenticated calls, works only if the current request was
	// authenticated via a forwardable token, e.g. an OAuth2 access token.
	//
	// If the current request was initiated by an anonymous caller, the RPC will
	// have no auth headers (just like in NoAuth mode).
	//
	// An attempt to use GetRPCTransport(ctx, AsCredentialsForwarder) with
	// unsupported credentials results in an error.
	AsCredentialsForwarder

	// AsActor is used for outbound RPCs sent with the authority of some service
	// account that the current service has "iam.serviceAccountTokenCreator" role
	// in.
	//
	// RPC requests done in this mode will have 'Authorization' header set to
	// either an OAuth2 access token or an ID token of the service account
	// specified by WithServiceAccount option.
	//
	// What kind of token is used depends on a presence of WithIDTokenAudience
	// option and it follows the rules described in AsSelf comment.
	//
	// TODO(crbug.com/1081932): Implement WithIDTokenAudience mode.
	AsActor

	// AsProject is used for outbounds RPCs sent with the authority of some LUCI
	// project (specified via WithProject option).
	//
	// When used to call external services (anything that is not a part of the
	// current LUCI deployment), uses 'Authorization' header with either an OAuth2
	// access token or an ID token of the project-specific service account
	// (specified in the LUCI project definition in 'projects.cfg' deployment
	// configuration file).
	//
	// What kind of token is used in this case depends on a presence of
	// WithIDTokenAudience option and it follows the rules described in AsSelf
	// comment.
	//
	// When used to call LUCI services belonging the same LUCI deployment (per
	// 'internal_service_regexp' setting in 'security.cfg' deployment
	// configuration file) uses the current service's OAuth2 access token plus
	// 'X-Luci-Project' header with the project name. Such calls are authenticated
	// by the peer as coming from 'project:<name>' identity. Options WithScopes
	// and WithIDTokenAudience are ignored in this case.
	//
	// TODO(crbug.com/1081932): Implement WithIDTokenAudience mode.
	AsProject
)

type RPCOption

type RPCOption interface {
	// contains filtered or unexported methods
}

RPCOption is an option for GetRPCTransport, GetPerRPCCredentials and GetTokenSource functions.

func WithDelegationTags

func WithDelegationTags(tags ...string) RPCOption

WithDelegationTags can be used to attach tags to the delegation token used internally in AsUser mode.

DEPRECATED.

The recipient of the RPC that uses the delegation will be able to extract them, if necessary. They are also logged in the token server logs.

Each tag is a key:value string.

Note that any delegation tags are ignored if the current request was initiated by an anonymous caller, since delegation protocol is not actually used in this case.

func WithDelegationToken

func WithDelegationToken(token string) RPCOption

WithDelegationToken can be used to attach an existing delegation token to requests made in AsUser mode.

DEPRECATED.

The token can be obtained earlier via MintDelegationToken call. The transport doesn't attempt to validate it and just blindly sends it to the other side.

func WithIDTokenAudience

func WithIDTokenAudience(aud string) RPCOption

WithIDTokenAudience indicates to use ID tokens instead of OAuth2 tokens.

The token's `aud` claim will be set to the given value. It can be customized per-request by using `${host}` which will be substituted with a host name of the request URI.

Usage example:

tr, err := auth.GetRPCTransport(ctx,
  auth.AsSelf,
  auth.WithIDTokenAudience("https://${host}"),
)
if err != nil {
  return err
}
client := &http.Client{Transport: tr}
...

Not compatible with WithScopes.

func WithMonitoringClient

func WithMonitoringClient(client string) RPCOption

WithMonitoringClient allows to override 'client' field that goes into HTTP client monitoring metrics (such as 'http/response_status').

The default value of the field is "luci-go-server".

Note that the metrics also include hostname of the target service (in 'name' field), so in most cases it is fine to use the default client name. Overriding it may be useful if you want to differentiate between requests made to the same host from a bunch of different places in the code.

This option has absolutely no effect when passed to GetPerRPCCredentials() or GetTokenSource(). It applies only to GetRPCTransport().

func WithProject

func WithProject(project string) RPCOption

WithProject can be used to generate an OAuth token with an identity of that particular LUCI project.

See AsProject for more info.

func WithScopes

func WithScopes(scopes ...string) RPCOption

WithScopes can be used to customize OAuth scopes for outbound RPC requests.

Not compatible with WithIDTokenAudience.

func WithServiceAccount

func WithServiceAccount(email string) RPCOption

WithServiceAccount option must be used with AsActor authority kind to specify what service account to act as.

type Session

type Session struct {
	SessionID string    // same as `sessionID` passed to GetSession()
	UserID    string    // authentication provider specific user id
	User      User      // user profile, including identity string
	Exp       time.Time // when the session expires
}

Session is returned by SessionStore.GetSession(...).

type SessionStore

type SessionStore interface {
	// OpenSession create a new session for a user with given expiration time.
	// It returns unique session ID.
	OpenSession(c context.Context, userID string, u *User, exp time.Time) (string, error)

	// CloseSession closes a session given its ID. Does nothing if session is
	// already closed or doesn't exist. Returns only transient errors.
	CloseSession(c context.Context, sessionID string) error

	// GetSession returns existing non-expired session given its ID. Returns nil
	// if session doesn't exist, closed or expired. Returns only transient errors.
	GetSession(c context.Context, sessionID string) (*Session, error)
}

SessionStore keeps user sessions in some permanent storage. SessionStore is used by some authentication methods (e.g. openid.AuthMethod).

type State

type State interface {
	// Authenticator is an Authenticator used to authenticate the request.
	Authenticator() *Authenticator

	// DB is authdb.DB snapshot with authorization information to use when
	// processing this request.
	//
	// Use directly only when you know what your are doing. Prefer to use wrapping
	// functions (e.g. IsMember) instead.
	DB() authdb.DB

	// Method returns authentication method used for current request or nil if
	// request is anonymous.
	//
	// If non-nil, its one of the methods in Authenticator.Methods.
	Method() Method

	// User holds the identity and profile of the current caller. User.Identity
	// usually matches PeerIdentity(), but can be different if delegation is used.
	// This field is never nil. For anonymous call it contains User with identity
	// AnonymousIdentity. Do not modify it.
	User() *User

	// PeerIdentity identifies whoever is making the request. It's an identity
	// directly extracted from user credentials (ignoring delegation tokens).
	PeerIdentity() identity.Identity

	// PeerIP is IP address (IPv4 or IPv6) of whoever is making the request or
	// nil if not available.
	PeerIP() net.IP

	// UserCredentials is an end-user credentials as they were received if they
	// are allowed to be forwarded.
	UserCredentials() (*oauth2.Token, error)
}

State is stored in the context when handling an incoming request. It contains authentication related state of the current request.

func GetState

func GetState(c context.Context) State

GetState return State stored in the context by 'Authenticate' call, the background state if 'Authenticate' wasn't used or nil if the auth library wasn't configured.

The background state roughly is similar to the state of anonymous call. Various background non user-facing handlers (crons, task queues) that do not use 'Authenticate' see this state by default. Its most important role is to provide access to authdb.DB (and all functionality that depends on it) to background handlers.

type Token

type Token struct {
	Token  string    // an opaque base64-encoded token
	Expiry time.Time // when it expires
}

Token is some opaque token and its expiration time.

Returned by various MintXToken calls.

func MintAccessTokenForServiceAccount

func MintAccessTokenForServiceAccount(ctx context.Context, params MintAccessTokenParams) (_ *Token, err error)

MintAccessTokenForServiceAccount produces an access token for some service account that the current service has "iam.serviceAccountTokenCreator" role in.

Used to implement AsActor authorization kind, but can also be used directly, if needed. The token is cached internally. Same token may be returned by multiple calls, if its lifetime allows.

Recognizes transient errors and marks them, but does not automatically retry. Has internal timeout of 10 sec.

func MintDelegationToken

func MintDelegationToken(ctx context.Context, p DelegationTokenParams) (_ *Token, err error)

MintDelegationToken returns a delegation token that can be used by the current service to "pretend" to be the current caller (as returned by CurrentIdentity(...)) when sending requests to some other LUCI service.

DEPRECATED.

The delegation token is essentially a signed assertion that the current service is allowed to access some other service on behalf of the current user.

A token can be targeted to some single specific service or usable by any allowed LUCI service (aka 'untargeted'). See TargetHost and Untargeted fields in DelegationTokenParams.

The token is cached internally. Same token may be returned by multiple calls, if its lifetime allows.

func MintIDTokenForServiceAccount

func MintIDTokenForServiceAccount(ctx context.Context, params MintIDTokenParams) (_ *Token, err error)

MintIDTokenForServiceAccount produces an ID token for some service account that the current service has "iam.serviceAccountTokenCreator" role in.

Used to implement AsActor authorization kind, but can also be used directly, if needed. The token is cached internally. Same token may be returned by multiple calls, if its lifetime allows.

Recognizes transient errors and marks them, but does not automatically retry. Has internal timeout of 10 sec.

func MintProjectToken

func MintProjectToken(ctx context.Context, p ProjectTokenParams) (_ *Token, err error)

MintProjectToken returns a LUCI project-scoped OAuth2 token that can be used to access external resources on behalf of the project.

It protects against accidental cross-project resource access. A token is targeted to some single specific LUCI project. The token is cached internally. Same token may be returned by multiple calls, if its lifetime allows.

type User

type User struct {
	// Identity is identity string of the user (may be AnonymousIdentity).
	// If User is returned by Authenticate(...), Identity string is always present
	// and valid.
	Identity identity.Identity `json:"identity,omitempty"`

	// Superuser is true if the user is site-level administrator. For example, on
	// GAE this bit is set for GAE-level administrators. Optional, default false.
	Superuser bool `json:"superuser,omitempty"`

	// Email is email of the user. Optional, default "". Don't use it as a key
	// in various structures. Prefer to use Identity() instead (it is always
	// available).
	Email string `json:"email,omitempty"`

	// Name is full name of the user. Optional, default "".
	Name string `json:"name,omitempty"`

	// Picture is URL of the user avatar. Optional, default "".
	Picture string `json:"picture,omitempty"`

	// ClientID is the ID of the pre-registered OAuth2 client so its identity can
	// be verified. Used only by authentication methods based on OAuth2.
	// See https://developers.google.com/console/help/#generatingoauth2 for more.
	ClientID string `json:"client_id,omitempty"`
}

User represents identity and profile of a user.

func CurrentUser

func CurrentUser(c context.Context) *User

CurrentUser represents the current caller.

Shortcut for GetState(c).User(). Returns user with AnonymousIdentity if the context doesn't have State.

type UserCredentialsGetter

type UserCredentialsGetter interface {
	// GetUserCredentials extracts an OAuth access token from the incoming request
	// or returns an error if it isn't possible.
	//
	// May omit token's expiration time if it isn't known.
	//
	// Guaranteed to be called only after the successful authentication, so it
	// doesn't have to recheck the validity of the token.
	GetUserCredentials(context.Context, *http.Request) (*oauth2.Token, error)
}

UserCredentialsGetter may be additionally implemented by Method if it knows how to extract end-user credentials from the incoming request. Currently understands only OAuth2 tokens.

type UsersAPI

type UsersAPI interface {
	// LoginURL returns a URL that, when visited, prompts the user to sign in,
	// then redirects the user to the URL specified by dest.
	LoginURL(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.
	LogoutURL(ctx context.Context, dest string) (string, error)
}

UsersAPI may be additionally implemented by Method if it supports login and logout URLs.

type Warmable

type Warmable interface {
	// Warmup may be called to precache the data needed by the method.
	//
	// There's no guarantee when it will be called or if it will be called at all.
	// Should always do best-effort initialization. Errors are logged and ignored.
	Warmup(ctx context.Context) error
}

Warmable may be additionally implemented by Method if it supports warm up.

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier