Documentation

Overview

    Package authcli implements authentication related flags parsing and CLI subcommands.

    It can be used from CLI tools that want customize authentication configuration from the command line.

    Minimal example of using flags parsing:

    authFlags := authcli.Flags{}
    defaults := ... // prepare default auth.Options
    authFlags.Register(flag.CommandLine, defaults)
    flag.Parse()
    opts, err := authFlags.Options()
    if err != nil {
      // handle error
    }
    authenticator := auth.NewAuthenticator(ctx, auth.SilentLogin, opts)
    httpClient, err := authenticator.Client()
    if err != nil {
      // handle error
    }
    

    This assumes that either a service account credentials are used (passed via -service-account-json), or the user has previously ran "login" subcommand and their refresh token is already cached. In any case, there will be no interaction with the user (this is what auth.SilentLogin means): if there are no cached token, authenticator.Client will return auth.ErrLoginRequired.

    Interaction with the user happens only in "login" subcommand. This subcommand (as well as a bunch of other related commands) can be added to any subcommands.Application.

    While it will work with any subcommand.Application, it uses luci-go/common/cli.GetContext() to grab a context for logging, so callers should prefer using cli.Application for hosting auth subcommands and making the context. This ensures consistent logging style between all subcommands of a CLI application:

    import (
      ...
      "go.chromium.org/luci/client/authcli"
      "go.chromium.org/luci/common/cli"
    )
    
    func GetApplication(defaultAuthOpts auth.Options) *cli.Application {
      return &cli.Application{
        Name:  "app_name",
    
        Context: func(ctx context.Context) context.Context {
          ... configure logging, etc. ...
          return ctx
        },
    
        Commands: []*subcommands.Command{
          authcli.SubcommandInfo(defaultAuthOpts, "auth-info", false),
          authcli.SubcommandLogin(defaultAuthOpts, "auth-login", false),
          authcli.SubcommandLogout(defaultAuthOpts, "auth-logout", false),
          ...
        },
      }
    }
    
    func main() {
      defaultAuthOpts := ...
      app := GetApplication(defaultAuthOpts)
      os.Exit(subcommands.Run(app, nil))
    }
    

    Index

    Constants

    View Source
    const (
    	ExitCodeSuccess = iota
    	ExitCodeNoValidToken
    	ExitCodeInvalidInput
    	ExitCodeInternalError
    	ExitCodeBadLogin
    )

      Process exit codes for subcommands.

      Variables

      This section is empty.

      Functions

      func SubcommandContext

      func SubcommandContext(opts auth.Options, name string) *subcommands.Command

        SubcommandContext returns subcommand.Command that can be used to setup new LUCI authentication context for a process tree.

        This is an advanced command and shouldn't be usually embedded into binaries. It is primarily used by 'luci-auth' program. It exists to simplify development and debugging of programs that rely on LUCI authentication context.

        func SubcommandContextWithParams

        func SubcommandContextWithParams(params CommandParams) *subcommands.Command

          SubcommandContextWithParams returns subcommand.Command that can be used to setup new LUCI authentication context for a process tree.

          func SubcommandInfo

          func SubcommandInfo(opts auth.Options, name string, advanced bool) *subcommands.Command

            SubcommandInfo returns subcommand.Command that can be used to print current cached credentials.

            func SubcommandInfoWithParams

            func SubcommandInfoWithParams(params CommandParams) *subcommands.Command

              SubcommandInfoWithParams returns subcommand.Command that can be used to print current cached credentials.

              func SubcommandLogin

              func SubcommandLogin(opts auth.Options, name string, advanced bool) *subcommands.Command

                SubcommandLogin returns subcommands.Command that can be used to perform interactive login.

                func SubcommandLoginWithParams

                func SubcommandLoginWithParams(params CommandParams) *subcommands.Command

                  SubcommandLoginWithParams returns subcommands.Command that can be used to perform interactive login.

                  func SubcommandLogout

                  func SubcommandLogout(opts auth.Options, name string, advanced bool) *subcommands.Command

                    SubcommandLogout returns subcommands.Command that can be used to purge cached credentials.

                    func SubcommandLogoutWithParams

                    func SubcommandLogoutWithParams(params CommandParams) *subcommands.Command

                      SubcommandLogoutWithParams returns subcommands.Command that can be used to purge cached credentials.

                      func SubcommandToken

                      func SubcommandToken(opts auth.Options, name string) *subcommands.Command

                        SubcommandToken returns subcommand.Command that can be used to print current access token.

                        func SubcommandTokenWithParams

                        func SubcommandTokenWithParams(params CommandParams) *subcommands.Command

                          SubcommandTokenWithParams returns subcommand.Command that can be used to print current access token.

                          Types

                          type CommandParams

                          type CommandParams struct {
                          	Name     string // name of the subcommand
                          	Advanced bool   // treat this as an 'advanced' subcommand
                          
                          	AuthOptions auth.Options // default auth options
                          
                          	// UseScopeFlags specifies whether scope-related flags must be registered.
                          	//
                          	// This is primarily used by `luci-auth` executable.
                          	//
                          	// UseScopeFlags is *not needed* for command line tools that call a fixed
                          	// number of backends. Just add all necessary scopes to AuthOptions.Scopes,
                          	// no need to expose a flag.
                          	UseScopeFlags bool
                          
                          	// UseIDTokenFlags specifies whether to register flags related to ID tokens.
                          	//
                          	// This is primarily used by `luci-auth` executable.
                          	UseIDTokenFlags bool
                          }

                            CommandParams specifies various parameters for a subcommand.

                            type Flags

                            type Flags struct {
                            	// contains filtered or unexported fields
                            }

                              Flags defines command line flags related to authentication.

                              func (*Flags) Options

                              func (fl *Flags) Options() (auth.Options, error)

                                Options returns auth.Options populated based on parsed command line flags.

                                func (*Flags) Register

                                func (fl *Flags) Register(f *flag.FlagSet, defaults auth.Options)

                                  Register adds auth related flags to a FlagSet.