devicecode

Documentation

Overview

Package devicecode provides an interactive Safeguard login using the OAuth device authorization grant: the appliance issues a short user code and a verification URL, the user visits the URL on any device and enters the code, and the SDK polls until authorization completes. It suits headless or input-constrained hosts (a shell over SSH, a TV, a CLI on a machine with no browser) where the browser add-on's loopback redirect cannot be used.

It is an optional add-on with a one-way import of the root package. The resulting session is not refreshable, matching SafeguardDotNet and PySafeguard; to obtain a new token, call Connect again.

Index

• Variables
• func Connect(ctx context.Context, host string, prompt PromptFunc, opts ...Option) (*safeguard.Client, error)
• type Option
  • func WithConnectionOptions(opts ...safeguard.Option) Option
  • func WithPollInterval(d time.Duration) Option
• type Prompt
• type PromptFunc

Variables

var ErrDenied = auth.ErrDeviceCodeDenied

ErrDenied indicates the user denied the device-code authorization request. Compare with errors.Is.

var ErrExpired = auth.ErrDeviceCodeExpired

ErrExpired indicates the user did not complete the device-code login before it expired. Compare with errors.Is.

var ErrNoPrompt = errors.New("devicecode: a prompt function is required to display the user code")

ErrNoPrompt indicates Connect was called without a prompt to display the user code. Compare with errors.Is.

Functions

func Connect

func Connect(ctx context.Context, host string, prompt PromptFunc, opts ...Option) (*safeguard.Client, error)

Connect authenticates to the Safeguard appliance at host using the device authorization grant and returns a ready client. It starts a device authorization, calls prompt once so the user can be shown the user code and verification URL, then polls until the user completes authentication, the code expires (ErrExpired), the user denies the request (ErrDenied), or the context is canceled.

Types

type Option

type Option func(*config)

Option configures a device-code login.

func WithConnectionOptions

func WithConnectionOptions(opts ...safeguard.Option) Option

WithConnectionOptions forwards standard connection options (TLS trust, API version, timeouts, logger) to the underlying safeguard.Connect call.

func WithPollInterval

func WithPollInterval(d time.Duration) Option

WithPollInterval overrides how long to wait between polls of the token endpoint. The default follows the appliance's guidance (and backs off when the appliance asks the client to slow down). Setting a value below the appliance's minimum may cause it to return slow_down responses.

type Prompt

type Prompt struct {
	// UserCode is the short code the user enters at the verification URI.
	UserCode string
	// VerificationURI is the URL the user visits to enter the user code.
	VerificationURI string
	// VerificationURIComplete is the verification URL with the user code already
	// embedded, suitable for a link or QR code. It may be empty.
	VerificationURIComplete string
	// ExpiresIn is how long the user has to complete authentication.
	ExpiresIn time.Duration
}

Prompt carries the details a user needs to complete a device-code login. A PromptFunc presents these to the user: the user visits VerificationURI and enters UserCode, or opens VerificationURIComplete which has the code embedded.

type PromptFunc

type PromptFunc func(ctx context.Context, p Prompt) error

PromptFunc presents a Prompt to the user. It is called once, before polling begins. Returning an error aborts the login.