login

package
v0.1.503 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package login implements browser-based and headless OIDC login flows for Chainguard clients, returning access and refresh tokens.

Package login implements client login functionality shared between various clients

Package login implements client login functionality shared between various clients

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	HTMLAuthSuccessful = `` /* 2674-byte string literal not displayed */

)

Functions

func BuildHeadlessURL added in v0.1.25

func BuildHeadlessURL(opts ...Option) (u string, err error)
Example

ExampleBuildHeadlessURL demonstrates that a missing headless code returns an error.

package main

import (
	"fmt"

	"chainguard.dev/sdk/auth/login"
)

func main() {
	_, err := login.BuildHeadlessURL()
	fmt.Println(err != nil)
}
Output:
true

func Login

func Login(ctx context.Context, opts ...Option) (token string, refreshToken string, err error)

Login runs the interactive browser login and returns its access and refresh tokens. Use Authenticate to learn whether the refresh token rotates.

Types

type Error added in v0.1.39

type Error struct {
	Details string
	Err     error
}

Error is a generic wrapper around client side errors this package may return. It helps callers distinguish between local and remote errors.

Example

ExampleError demonstrates the Error type returned by login operations.

package main

import (
	"fmt"

	"chainguard.dev/sdk/auth/login"
)

func main() {
	err := &login.Error{
		Details: "failed to open browser",
		Err:     fmt.Errorf("exec: not found"),
	}
	fmt.Println(err.Error())
}
Output:
login: failed to open browser: exec: not found

func (*Error) As added in v0.1.39

func (e *Error) As(target any) bool

func (*Error) Error added in v0.1.39

func (e *Error) Error() string

func (*Error) Unwrap added in v0.1.39

func (e *Error) Unwrap() error

type OpenBrowserError deprecated added in v0.1.20

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

OpenBrowserError wraps the error returned from browser.OpenURL, since this can take a few different forms depending on the OS.

Deprecated: use Error.

func (OpenBrowserError) Error added in v0.1.20

func (e OpenBrowserError) Error() string

func (OpenBrowserError) Unwrap added in v0.1.20

func (e OpenBrowserError) Unwrap() error

type Option

type Option func(opt *config)

func WithAudience

func WithAudience(aud []string) Option

func WithAuth0Connection

func WithAuth0Connection(conn string) Option

func WithClientID

func WithClientID(id string) Option

func WithCreateRefreshToken added in v0.1.9

func WithCreateRefreshToken() Option

func WithHeadlessCode added in v0.1.25

func WithHeadlessCode(code string) Option

func WithIdentity

func WithIdentity(identity string) Option

func WithIdentityProvider

func WithIdentityProvider(idp string) Option

func WithInviteCode

func WithInviteCode(inviteCode string) Option

func WithIssuer

func WithIssuer(issuer string) Option

func WithMessageWriter added in v0.1.29

func WithMessageWriter(w io.Writer) Option

func WithOrgName

func WithOrgName(org string) Option

func WithRefreshTokenRotation added in v0.1.438

func WithRefreshTokenRotation() Option

WithRefreshTokenRotation declares on the interactive login that the caller handles refresh-token rotation: it stores one refresh token per family under a lock shared by its processes, persists the successor every refresh returns, and discards a token the issuer refuses as REFRESH_TOKEN_SUPERSEDED. Set it only if the caller does all three, since a rotated family whose superseded token is presented again is revoked. A successor's expiry may be later than its parent's: a rotated family's session slides while it is used, up to its organizations' session length.

An issuer that honors the declaration reports it in Result.RefreshTokenRotation. One that does not ignores it, and the family is never rotated. The headless flow does not carry it.

func WithScope added in v0.1.39

func WithScope(scope ...string) Option

func WithScreenHint added in v0.1.55

func WithScreenHint(hint string) Option

WithScreenHint sets `screen_hint=<value>` on the /oauth redirect. The Chainguard issuer forwards it to Auth0's /authorize. Pass "signup" to default the Universal Login UI to the signup form instead of the login form when a flow is known to register a new user (e.g. catalog starter init).

func WithSkipBrowser added in v0.1.21

func WithSkipBrowser() Option

func WithSkipRegistration

func WithSkipRegistration() Option

func WithURLOpener added in v0.1.390

func WithURLOpener(fn func(url string) error) Option

WithURLOpener sets a custom function used to open the login URL during the interactive flow instead of the platform default browser. It is ignored when SkipBrowser is set. A nil fn leaves the default browser behavior in place.

type Result added in v0.1.438

type Result struct {
	// Token is the Chainguard access token.
	Token string

	// RefreshToken is empty unless the login asked for one
	// (WithCreateRefreshToken) and the issuer issued it.
	RefreshToken string

	// RefreshTokenRotation reports that the issuer confirmed RefreshToken
	// heads a rotation-capable family. It is never true unless the login
	// declared rotation (WithRefreshTokenRotation). A false value after a
	// declaration means the family is never rotated, as from an issuer that
	// predates the declaration.
	RefreshTokenRotation bool
}

Result is what an interactive login returns.

func Authenticate added in v0.1.438

func Authenticate(ctx context.Context, opts ...Option) (*Result, error)

Authenticate runs the interactive browser login, as Login does, and reports whether the issuer confirmed the refresh token rotates.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址