auth

Documentation

Overview

Package auth provides OAuth 2.0 authentication for Atlassian Cloud APIs.

This package handles:

• OAuth 2.0 authorization code flow with browser-based consent
• Secure token storage (file-based with restricted permissions)
• Token expiration tracking

Tokens are stored per-host in ~/.config/atlassian/tokens/, allowing users to authenticate with multiple Atlassian instances simultaneously.

Index

• Constants
• Variables
• func DefaultScopes() []string
• func DeleteClientCredentials() error
• func DeleteToken(hostname string) error
• func ListStoredHosts() ([]string, error)
• func OpenBrowser(url string) error
• func StartCallbackServer(codeChan chan<- string, errChan chan<- error, expectedState string) (*http.Server, int, error)
• func StoreClientCredentials(creds ClientCredentials) error
• func StoreToken(hostname string, tokens *TokenSet) error
• type ClientCredentials
  • func GetClientCredentials() (creds ClientCredentials, ok bool)
• type CredentialSource
  • func ResolveClientCredentials(configID, configSecret string) (clientID, clientSecret string, source CredentialSource)
• type OAuthConfig
• type OAuthFlow
  • func NewOAuthFlow(config *OAuthConfig) (*OAuthFlow, error)
  • func (f *OAuthFlow) AuthorizationURL() string
  • func (f *OAuthFlow) ExchangeCode(ctx context.Context, code string) (*TokenSet, error)
  • func (f *OAuthFlow) RefreshTokens(ctx context.Context, refreshToken string) (*TokenSet, error)
  • func (f *OAuthFlow) State() string
• type RefreshConfig
• type TokenSet
  • func GetToken(hostname string) (*TokenSet, error)
  • func RefreshAccessToken(ctx context.Context, hostname string, cfg *RefreshConfig) (*TokenSet, error)
  • func (t *TokenSet) IsExpired() bool

Constants

const (
	// AtlassianAuthURL is the authorization endpoint for Atlassian OAuth.
	AtlassianAuthURL = "https://auth.atlassian.com/authorize"
	// AtlassianAPIURL is the base URL for Atlassian API requests.
	AtlassianAPIURL = "https://api.atlassian.com"
)

const DefaultCallbackPort = 8085

DefaultCallbackPort is the port used for the OAuth callback server.

const (
	// KeyringService was the service name used for keyring storage (deprecated).
	// Now tokens are stored in files due to keyring size limitations.
	KeyringService = "atlassian-cli"
)

Variables

var AtlassianTokenURL = "https://auth.atlassian.com/oauth/token"

AtlassianTokenURL is the token endpoint for the OAuth code/refresh exchange. It is a var, not a const, so a test can point the exchange at a local server.

Functions

func DefaultScopes

func DefaultScopes() []string

DefaultScopes returns the default OAuth scopes. Includes both classic and granular scopes as the CLI uses both v1 and v2 APIs: - Confluence v2 API for most operations (pages, spaces, search) - Confluence v1 API for some operations (archive, move) - Jira v3 API with classic scopes - Jira Agile v1 API with granular scopes

func DeleteClientCredentials

func DeleteClientCredentials() error

DeleteClientCredentials removes the OAuth app credentials from the OS keychain. A missing entry is not an error.

func DeleteToken

func DeleteToken(hostname string) error

DeleteToken removes tokens from file storage. Returns nil if no tokens exist for the hostname.

func ListStoredHosts

func ListStoredHosts() ([]string, error)

ListStoredHosts returns a list of hostnames that have stored tokens.

func OpenBrowser

func OpenBrowser(url string) error

OpenBrowser opens the specified URL in the default browser.

func StartCallbackServer

func StartCallbackServer(codeChan chan<- string, errChan chan<- error, expectedState string) (*http.Server, int, error)

StartCallbackServer starts a local HTTP server to receive the OAuth callback. It listens on the default callback port (8085) which must match the OAuth app configuration. Returns the server, the port it's listening on, and any error.

func StoreClientCredentials

func StoreClientCredentials(creds ClientCredentials) error

StoreClientCredentials saves the OAuth app credentials in the OS keychain as a single entry. Both fields are required.

func StoreToken

func StoreToken(hostname string, tokens *TokenSet) error

StoreToken stores tokens in a secure file. Tokens are stored in ~/.config/atlassian/tokens/<hostname>.json with 0600 permissions.

Types

type ClientCredentials

type ClientCredentials struct {
	ClientID     string `json:"client_id"`
	ClientSecret string `json:"client_secret"`
}

ClientCredentials holds OAuth 2.0 application credentials (client ID and secret), as opposed to per-user access/refresh tokens.

func GetClientCredentials

func GetClientCredentials() (creds ClientCredentials, ok bool)

GetClientCredentials reads the OAuth app credentials from the OS keychain. It returns ok=false when no complete credential pair is available. A missing entry and an unavailable backend (e.g. a headless machine with no Secret Service) are both reported as ok=false rather than an error, because the keychain is one optional layer in the credential resolver — callers fall through to other sources when it yields nothing.

type CredentialSource

type CredentialSource string

CredentialSource identifies which layer supplied the OAuth client credentials.

const (
	SourceEnv      CredentialSource = "environment variables"
	SourceKeychain CredentialSource = "OS keychain"
	SourceConfig   CredentialSource = "config file"
	SourceNone     CredentialSource = ""
)

func ResolveClientCredentials

func ResolveClientCredentials(configID, configSecret string) (clientID, clientSecret string, source CredentialSource)

ResolveClientCredentials returns the OAuth app credentials to use, taking the highest-precedence layer that supplies BOTH halves: environment variables, then OS keychain, then the config-file values passed in. client_id and client_secret are a coupled pair (same app), so a layer contributes only when complete — the two halves are never mixed across layers.

type OAuthConfig

type OAuthConfig struct {
	ClientID     string
	ClientSecret string
	RedirectURI  string
	Scopes       []string
}

OAuthConfig holds OAuth configuration.

type OAuthFlow

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

OAuthFlow manages the OAuth 2.0 authorization code flow.

func NewOAuthFlow

func NewOAuthFlow(config *OAuthConfig) (*OAuthFlow, error)

NewOAuthFlow creates a new OAuth flow.

func (*OAuthFlow) AuthorizationURL

func (f *OAuthFlow) AuthorizationURL() string

AuthorizationURL returns the URL to redirect the user to for authorization.

func (*OAuthFlow) ExchangeCode

func (f *OAuthFlow) ExchangeCode(ctx context.Context, code string) (*TokenSet, error)

ExchangeCode exchanges an authorization code for tokens.

func (*OAuthFlow) RefreshTokens

func (f *OAuthFlow) RefreshTokens(ctx context.Context, refreshToken string) (*TokenSet, error)

RefreshTokens exchanges a refresh token for new tokens.

func (*OAuthFlow) State

func (f *OAuthFlow) State() string

State returns the state parameter used in the authorization request.

type RefreshConfig

type RefreshConfig struct {
	ClientID     string
	ClientSecret string
}

RefreshConfig holds the configuration needed to refresh tokens.

type TokenSet

type TokenSet struct {
	AccessToken  string    `json:"access_token"`
	RefreshToken string    `json:"refresh_token"`
	TokenType    string    `json:"token_type"`
	ExpiresAt    time.Time `json:"expires_at"`
	Scopes       []string  `json:"scopes,omitempty"`
}

TokenSet represents OAuth 2.0 tokens for an Atlassian host. These tokens are obtained via the OAuth authorization code flow and stored securely in the system keyring.

func GetToken

func GetToken(hostname string) (*TokenSet, error)

GetToken retrieves tokens from file storage. Returns nil, nil if no tokens exist for the hostname.

func RefreshAccessToken

func RefreshAccessToken(ctx context.Context, hostname string, cfg *RefreshConfig) (*TokenSet, error)

RefreshAccessToken refreshes the access token for a given hostname using its stored refresh token. It retrieves the current tokens, exchanges the refresh token for new tokens, and stores the result. Returns the new TokenSet or an error if refresh fails.

func (*TokenSet) IsExpired

func (t *TokenSet) IsExpired() bool

IsExpired returns true if the access token has expired or is about to expire. Tokens are considered expired 5 minutes before their actual expiry time to provide a buffer for token refresh operations.