auth

README

Authentication Flow Design

Objective

The primary goal for authentication was to implement a secure, standard-based OAuth 2.0 flow suitable for a desktop CLI application.

Selected Flow: Authorization Code Flow for Desktop Apps

After extensive testing and research, the application uses Google's standard Authorization Code Flow for installed applications.

The Role of the Client Secret

A key aspect of this implementation is the use of a client_secret that is embedded in the compiled binary. This approach can seem counter-intuitive based on general OAuth 2.0 best practices, which advise against storing secrets in public clients.

However, Google's specific implementation for "Desktop app" credentials differs from the general standard. For this client type, Google provides a client_secret and requires it to be sent during the token exchange. This secret is not treated as a highly confidential value in the same way a web server's secret is. Instead, it acts as a stable identifier for the application.

This design choice was made based on the following:

1. Persistent Errors with PKCE: Attempts to use the PKCE (Proof Key for Code Exchange) flow without a client secret consistently failed with a client_secret is missing error from Google's servers. This occurred even when using a credential explicitly created as a "Desktop app" type.
2. Community Confirmation: Research indicates that this is expected behavior for Google's platform. The client_secret for an installed application is required and is intended to be distributed with the application.

Security Acknowledgment

While embedding a value named client_secret in a client application is non-standard for other platforms, it is the required and documented method for Google's OAuth 2.0 flow for desktop applications. The security of the flow is maintained by the use of user-specific authorization codes and refresh tokens, which are stored securely on the user's machine.

Sources

The decision to proceed with this design was informed by community discussions and documentation that clarify Google's specific requirements for desktop applications.

• Google's OAuth 2.0 for installed apps and Client Secret not being a secret
• Safely distribute OAuth 2.0 client_secret in desktop applications in Python
• Google Cloud OAuth 2.0 missing client secret
• "error_description": "client_secret is missing." - Google Groups
• Is a Client Secret Required for Google OAuth 2.0 using the PKCE authorization flow?

Documentation

Index

• Constants
• Variables
• func GetClient(ctx context.Context, user string) (*http.Client, error)
• func ListAccounts() ([]string, error)
• func LoginViaWebFlow(ctx context.Context) (string, error)
• func Logout(user string) error
• type TokenCache

Constants

const (
	TokenFile = "gtasks-token.json"
)

Variables

var ErrCredentialsNotFound = errors.New("credentials not found. Please run 'gtasks login'")

ErrCredentialsNotFound is returned when the user's credentials are not found.

Functions

func GetClient

func GetClient(ctx context.Context, user string) (*http.Client, error)

GetClient returns an authenticated HTTP client for the given user.

func ListAccounts

func ListAccounts() ([]string, error)

ListAccounts lists all the accounts in the token cache.

func LoginViaWebFlow

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

LoginViaWebFlow orchestrates the web-based authentication process.

func Logout

func Logout(user string) error

Logout removes the token for the given user from the cache.

Types

type TokenCache

type TokenCache struct {
	Tokens map[string]*oauth2.Token `json:"tokens"`
}

TokenCache represents the structure of the credentials file.