config

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Feb 10, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Copyright © 2025 Ping Identity Corporation

Copyright © 2025 Ping Identity Corporation

Package config provides configuration management for the PingOne Go Client SDK. It handles service configuration, environment variable parsing, OAuth2 credential management, and endpoint configuration for connecting to PingOne services across different regions.

Copyright © 2025 Ping Identity Corporation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultAuthorizationCodeBrowserHandler added in v0.4.0 

func DefaultAuthorizationCodeBrowserHandler(authURL string) error

DefaultAuthorizationCodeBrowserHandler is the default handler for opening the authorization URL. It attempts to open the system browser automatically and provides fallback instructions if that fails. This function implements the AuthURLHandler interface and provides a consistent UX pattern. Consumer projects can use this handler as a reference or directly in their own implementations.

func DefaultDeviceCodePromptHandler added in v0.4.0 

func DefaultDeviceCodePromptHandler(verificationURI, userCode string) error

DefaultDeviceCodePromptHandler is a simple handler that displays device code prompts. This function can be used by consumer projects as a reference implementation or directly. For better UX with complete URLs, use the closure pattern shown in DeviceAuthTokenSource. This function implements the DeviceCodePromptHandler interface pattern.

func GetDefaultAuthorizationCodeRedirectURI added in v0.4.0 

func GetDefaultAuthorizationCodeRedirectURI() string

Get default authorization code redirect URI

func GetDefaultAuthorizationCodeRedirectURIPath added in v0.4.0 

func GetDefaultAuthorizationCodeRedirectURIPath() string

Get default authorization code redirect URI path

func GetDefaultAuthorizationCodeRedirectURIPort added in v0.4.0 

func GetDefaultAuthorizationCodeRedirectURIPort() string

Get default authorization code redirect URI port

Types

type AuthResultPageData added in v0.4.0 

type AuthResultPageData struct {
	// ProjectName is displayed as the HTML page title (e.g., "PingOne MCP Server")
	ProjectName string
	// Heading is the main heading displayed on the page (e.g., "Authorization Success")
	Heading string
	// Message is the descriptive text displayed below the title
	Message string
}

AuthResultPageData contains the data used to render the authorization result page. SDK clients can provide custom values to personalize the page while using the default template.

type AuthURLHandler added in v0.4.0 

type AuthURLHandler func(url string) error

AuthURLHandler is a function type that handles opening authorization URLs. It receives the authorization URL that the user must visit. Return an error if the URL cannot be handled.

type AuthorizationCode added in v0.4.0 

type AuthorizationCode struct {
	AuthorizationCodeClientID    *string                      `envconfig:"PINGONE_AUTHORIZATION_CODE_CLIENT_ID" json:"authorizationCodeClientId,omitempty"`
	AuthorizationCodeRedirectURI AuthorizationCodeRedirectURI `envconfig:"PINGONE_AUTHORIZATION_CODE_REDIRECT_URI" json:"authorizationCodeRedirectUri,omitempty"`
	AuthorizationCodeScopes      *[]string                    `envconfig:"PINGONE_AUTHORIZATION_CODE_SCOPES" json:"authorizationCodeScopes,omitempty"`
	// OnOpenBrowser is an optional handler for custom browser opening logic.
	// If set, this handler will be called instead of automatically opening the system browser.
	// This allows consumers to implement custom flows such as headless operation or alternative UX.
	OnOpenBrowser AuthURLHandler `json:"-"`
	// CustomPageDataSuccess contains the data to display on successful authentication.
	// If nil, default values will be used. The SDK template will be rendered with these values.
	CustomPageDataSuccess *AuthResultPageData `json:"-"`
	// CustomPageDataError contains the data to display on authentication failure.
	// If nil, default values will be used. The SDK template will be rendered with these values.
	CustomPageDataError *AuthResultPageData `json:"-"`
}

func (*AuthorizationCode) AuthorizationCodeTokenSource added in v0.4.0 

func (a *AuthorizationCode) AuthorizationCodeTokenSource(ctx context.Context, endpoints endpoints.OIDCEndpoint) (oauth2.TokenSource, error)

AuthorizationCodeTokenSource returns an oauth2.TokenSource using the authorization code grant type

type AuthorizationCodeRedirectURI added in v0.4.0 

type AuthorizationCodeRedirectURI struct {
	Port string `envconfig:"PINGONE_AUTHORIZATION_CODE_REDIRECT_URI_PORT" json:"port,omitempty"`
	Path string `envconfig:"PINGONE_AUTHORIZATION_CODE_REDIRECT_URI_PATH" json:"path,omitempty"`
}

type ClientCredentials added in v0.4.0 

type ClientCredentials struct {
	ClientCredentialsClientID     *string   `envconfig:"PINGONE_CLIENT_CREDENTIALS_CLIENT_ID" json:"clientCredentialsClientId,omitempty"`
	ClientCredentialsClientSecret *string   `envconfig:"PINGONE_CLIENT_CREDENTIALS_CLIENT_SECRET" json:"clientCredentialsClientSecret,omitempty"`
	ClientCredentialsScopes       *[]string `envconfig:"PINGONE_CLIENT_CREDENTIALS_SCOPES" json:"clientCredentialsScopes,omitempty"`
}

func (*ClientCredentials) ClientCredentialsTokenSource added in v0.4.0 

func (c *ClientCredentials) ClientCredentialsTokenSource(ctx context.Context, endpoints endpoints.OIDCEndpoint) (oauth2.TokenSource, error)

type Configuration 

type Configuration struct {
	// Auth contains authentication-related configuration including client credentials and grant types.
	Auth struct {
		AccessToken       *string              `envconfig:"PINGONE_API_ACCESS_TOKEN" json:"accessToken,omitempty"`
		AccessTokenExpiry *int                 `envconfig:"PINGONE_API_ACCESS_TOKEN_EXPIRY" json:"accessTokenExpiry,omitempty"`
		AuthorizationCode *AuthorizationCode   `envconfig:"PINGONE_AUTHORIZATION_CODE" json:"authorizationCode,omitempty"`
		ClientCredentials *ClientCredentials   `envconfig:"PINGONE_CLIENT_CREDENTIALS" json:"clientCredentials,omitempty"`
		DeviceCode        *DeviceCode          `envconfig:"PINGONE_DEVICE_CODE" json:"deviceCode,omitempty"`
		GrantType         *svcOAuth2.GrantType `envconfig:"PINGONE_AUTH_GRANT_TYPE" json:"grantType,omitempty"`
		Storage           *Storage             `envconfig:"PINGONE_STORAGE_OPTIONS" json:"storageOptions,omitempty"`
	} `json:"auth"`
	// Endpoint contains endpoint configuration for API and authentication domains.
	Endpoint struct {
		EnvironmentID  *string         `envconfig:"PINGONE_ENVIRONMENT_ID" json:"environmentId,omitempty"`
		TopLevelDomain *TopLevelDomain `envconfig:"PINGONE_TOP_LEVEL_DOMAIN" json:"topLevelDomain,omitempty"`
		RootDomain     *string         `envconfig:"PINGONE_ROOT_DOMAIN" json:"rootDomain,omitempty"`
		APIDomain      *string         `envconfig:"PINGONE_API_DOMAIN" json:"apiDomain,omitempty"`
		CustomDomain   *string         `envconfig:"PINGONE_CUSTOM_DOMAIN" json:"customDomain,omitempty"`
	} `json:"endpoint"`
}

Configuration represents the complete configuration for the PingOne Go Client SDK. It contains authentication settings and endpoint configuration for connecting to PingOne services. The configuration can be populated from environment variables or set explicitly through the builder methods.

func NewConfiguration 

func NewConfiguration() *Configuration

NewConfiguration creates a new Configuration instance with default values. This configuration must be populated with authentication credentials and endpoint information before it can be used to create API clients. Use the builder methods (With...) to set the required configuration values.

func (*Configuration) APIDomain 

func (c *Configuration) APIDomain() (string, error)

APIDomain constructs the API domain for PingOne service calls. It returns a string containing the complete API domain based on the configured domain settings. The method prioritizes explicit API domain configuration over root domain and top-level domain settings. It returns an error if no valid domain configuration can be determined from the current settings.

func (*Configuration) AddBearerTokenToContext 

func (c *Configuration) AddBearerTokenToContext(parent context.Context, key any) context.Context

AddBearerTokenToContext adds the configured access token to a context. The parent parameter is the base context to extend, and key is the context key to use for storing the token value. It returns a new context with the token value if a token is configured, or the original context if no token is set.

func (*Configuration) AuthEndpoints 

func (c *Configuration) AuthEndpoints() (endpoints.OIDCEndpoint, error)

AuthEndpoints constructs the OAuth2 and OIDC endpoints for authentication. It returns an OIDCEndpoint struct containing the authorization, token, and userinfo URLs based on the configured domain settings. The method prioritizes custom domain over environment-specific domains. It returns an error if no valid endpoint configuration can be determined from the current settings.

func (*Configuration) BearerToken 

func (c *Configuration) BearerToken() *oauth2.Token

BearerToken creates an OAuth2 token from the configured access token. It returns a pointer to an OAuth2 token with the access token and "Bearer" token type. This method assumes an access token has been configured; call HasBearerToken first to verify a token is available.

func (*Configuration) Client 

func (c *Configuration) Client(ctx context.Context, httpClient *http.Client) (*http.Client, error)

Client creates an HTTP client configured for PingOne API authentication. The ctx parameter provides the context for the OAuth2 token source operations. The httpClient parameter is the base HTTP client to use for requests; if nil, a default client will be used. It returns an HTTP client that automatically handles authentication token management, or an error if token source creation fails.

func (*Configuration) GetAccessToken added in v0.4.0 

func (c *Configuration) GetAccessToken(ctx context.Context) (string, error)

func (*Configuration) GetAccessTokenExpiry added in v0.4.0 

func (c *Configuration) GetAccessTokenExpiry() int

func (*Configuration) GetConfiguration added in v0.4.0 

func (c *Configuration) GetConfiguration() *Configuration

WithAuthEnvironmentID sets the PingOne environment ID for authentication. The environmentID parameter must be a valid PingOne environment UUID string. This environment ID is used to construct the OAuth2 authentication endpoints.

func (*Configuration) GetTopLevelDomain added in v0.4.0 

func (c *Configuration) GetTopLevelDomain() string

func (*Configuration) HasBearerToken 

func (c *Configuration) HasBearerToken() bool

HasBearerToken checks if a static access token is configured. It returns true if an access token has been set and is not empty, false otherwise. This is used to determine whether to use static token authentication or OAuth2 flows.

func (*Configuration) TokenSource 

func (c *Configuration) TokenSource(ctx context.Context) (oauth2.TokenSource, error)

TokenSource creates an OAuth2 token source based on the configured authentication method. The ctx parameter provides the context for OAuth2 operations. It returns a token source that can be used to obtain access tokens, or an error if the configuration is invalid or incomplete. If a static access token is configured, it returns a static token source. Otherwise, it creates a token source appropriate for the configured grant type.

func (*Configuration) WithAPIDomain 

func (c *Configuration) WithAPIDomain(apiDomain string) *Configuration

WithAPIDomain sets a custom API domain for PingOne services. The apiDomain parameter should be a complete API domain like "api.pingone.com". When set, this overrides automatic domain construction from other domain settings.

func (*Configuration) WithAccessToken 

func (c *Configuration) WithAccessToken(accessToken string) *Configuration

WithAccessToken sets a static access token for API authentication. The accessToken parameter must be valid PingOne API access token. When set, this bypasses OAuth2 flows and uses the provided token directly.

func (*Configuration) WithAuthorizationCodeClientID added in v0.4.0 

func (c *Configuration) WithAuthorizationCodeClientID(authorizationCodeClientID string) *Configuration

func (*Configuration) WithAuthorizationCodeRedirectURI added in v0.4.0 

func (c *Configuration) WithAuthorizationCodeRedirectURI(authorizationCodeRedirectURI AuthorizationCodeRedirectURI) *Configuration

func (*Configuration) WithAuthorizationCodeScopes added in v0.4.0 

func (c *Configuration) WithAuthorizationCodeScopes(authorizationCodeScopes []string) *Configuration

func (*Configuration) WithClientCredentialsClientID added in v0.4.0 

func (c *Configuration) WithClientCredentialsClientID(clientID string) *Configuration

func (*Configuration) WithClientCredentialsClientSecret added in v0.4.0 

func (c *Configuration) WithClientCredentialsClientSecret(clientSecret string) *Configuration

func (*Configuration) WithClientCredentialsScopes added in v0.4.0 

func (c *Configuration) WithClientCredentialsScopes(clientCredentialsScopes []string) *Configuration

func (*Configuration) WithClientID 

func (c *Configuration) WithClientID(clientID string) *Configuration

WithClientID sets the OAuth2 client ID for authentication. The clientID parameter must be a valid client ID from a PingOne application. This is required when using client credentials grant type authentication.

func (*Configuration) WithClientSecret 

func (c *Configuration) WithClientSecret(clientSecret string) *Configuration

WithClientSecret sets the OAuth2 client secret for authentication. The clientSecret parameter must be the secret associated with the configured client ID. This is required when using client credentials grant type with client secret authentication.

func (*Configuration) WithCustomDomain 

func (c *Configuration) WithCustomDomain(customDomain string) *Configuration

WithCustomDomain sets a custom domain for PingOne authentication services. The customDomain parameter should be a complete custom domain configured in PingOne. When set, this takes precedence over all other domain configuration methods.

func (*Configuration) WithDeviceCodeClientID added in v0.4.0 

func (c *Configuration) WithDeviceCodeClientID(deviceCodeClientID string) *Configuration

func (*Configuration) WithDeviceCodeScopes added in v0.4.0 

func (c *Configuration) WithDeviceCodeScopes(deviceCodeScopes []string) *Configuration

func (*Configuration) WithEnvironmentID added in v0.4.0 

func (c *Configuration) WithEnvironmentID(environmentID string) *Configuration

func (*Configuration) WithGrantType 

func (c *Configuration) WithGrantType(grantType svcOAuth2.GrantType) *Configuration

WithGrantType sets the OAuth2 grant type for authentication. The grantType parameter specifies which OAuth2 flow to use for token acquisition. Currently supported grant types are defined in the oauth2 package.

func (*Configuration) WithRootDomain 

func (c *Configuration) WithRootDomain(rootDomain string) *Configuration

WithRootDomain sets the root domain for PingOne services. The rootDomain parameter should be a complete domain like "pingone.com" or "pingone.eu". This takes precedence over top-level domain configuration when constructing endpoints.

func (*Configuration) WithStorageName added in v0.4.0 

func (c *Configuration) WithStorageName(name string) *Configuration

func (*Configuration) WithStorageOptionalSuffix added in v0.5.1 

func (c *Configuration) WithStorageOptionalSuffix(suffix string) *Configuration

WithStorageOptionalSuffix sets an optional suffix for the token key. This allows SDK consumers to unify key names across keychain and file storage without changing default SDK behavior for other clients.

func (*Configuration) WithStorageType added in v0.4.0 

func (c *Configuration) WithStorageType(storageType StorageType) *Configuration

func (*Configuration) WithTopLevelDomain 

func (c *Configuration) WithTopLevelDomain(tld TopLevelDomain) *Configuration

WithTopLevelDomain sets the top-level domain for PingOne services. The tld parameter should be a domain suffix like "com", "eu", or "asia". This is used to construct service endpoints for different PingOne regions.

func (*Configuration) WithUseKeychain deprecated added in v0.4.0 

func (c *Configuration) WithUseKeychain(useKeychain bool) *Configuration

Deprecated: Use WithStorageType instead.

type DeviceCode added in v0.4.0 

type DeviceCode struct {
	DeviceCodeClientID *string   `envconfig:"PINGONE_DEVICE_CODE_CLIENT_ID" json:"deviceCodeClientId,omitempty"`
	DeviceCodeScopes   *[]string `envconfig:"PINGONE_DEVICE_CODE_SCOPES" json:"deviceCodeScopes,omitempty"`
	// OnDisplayPrompt is an optional handler for custom device code prompt display.
	// If set, this handler will be called instead of the default console output.
	// This allows consumers to implement custom UX such as QR codes, notifications, or headless flows.
	OnDisplayPrompt DeviceCodePromptHandler `json:"-"`
}

func (*DeviceCode) DeviceAuthTokenSource added in v0.4.0 

func (d *DeviceCode) DeviceAuthTokenSource(ctx context.Context, endpoints oauth2.Endpoint) (oauth2.TokenSource, error)

DeviceAuthTokenSource returns an oauth2.TokenSource using the device code grant type. This function implements the OAuth2 Device Authorization Grant (RFC 8628) with PKCE (RFC 7636) for enhanced security.

The device code flow is designed for devices with limited input capabilities (e.g., smart TVs, CLI tools, IoT devices). The user completes authentication on a separate device with better input/display capabilities.

PKCE (Proof Key for Code Exchange) is automatically enabled for this flow to prevent authorization code interception attacks, following OAuth2 security best practices.

The function requires a valid client ID to be configured. The device code flow does not require a client secret, making it suitable for public clients.

Security features:

  • PKCE with S256 challenge method (SHA256 hashing)
  • Device code is single-use and time-limited
  • User must authenticate on a trusted device
  • Automatic polling with server-controlled intervals

Returns an oauth2.TokenSource that can be used for authenticated API calls, or an error if the device authorization fails.

type DeviceCodePromptHandler added in v0.4.0 

type DeviceCodePromptHandler func(verificationURI, userCode string) error

DeviceCodePromptHandler is a function type that handles displaying device code prompts to users. It receives the verification URI and user code that must be displayed to the user. Return an error if the prompt cannot be displayed.

type OIDCScope added in v0.4.0 

type OIDCScope string

OIDCScope represents an OIDC scope value. Extend this enum with additional scopes as needed. 

const (
	// OIDCScopeOpenID is the base OIDC scope required for OpenID Connect.
	OIDCScopeOpenID OIDCScope = "openid"
)

func (OIDCScope) IsValid added in v0.4.0 

func (s OIDCScope) IsValid() bool

IsValid checks if the OIDCScope is valid

func (OIDCScope) String added in v0.4.0 

func (s OIDCScope) String() string

String returns the string representation of the OIDCScope

type Storage added in v0.4.0 

type Storage struct {
	KeychainName string      `envconfig:"PINGONE_STORAGE_NAME" json:"name,omitempty"`
	Type         StorageType `envconfig:"PINGONE_STORAGE_TYPE" json:"type,omitempty"`
	// OptionalSuffix allows SDK consumers to append a suffix to the generated
	// token key for disambiguation across contexts (e.g., provider/grant/profile).
	// If empty, no suffix is appended and the base token key is used.
	OptionalSuffix string `envconfig:"PINGONE_STORAGE_OPTIONAL_SUFFIX" json:"optionalSuffix,omitempty"`
}

type StorageType added in v0.4.0 

type StorageType string

StorageType represents the type of storage backend for tokens 

const (
	// StorageTypeFileSystem uses the local file system for token storage
	StorageTypeFileSystem StorageType = "file_system"

	// StorageTypeSecureLocal uses a secure local storage (e.g., OS keychain)
	StorageTypeSecureLocal StorageType = "secure_local"

	// StorageTypeSecureRemote uses a secure remote storage service
	StorageTypeSecureRemote StorageType = "secure_remote"

	// StorageTypeNone defines no token storage
	StorageTypeNone StorageType = "none"
)

func (StorageType) IsValid added in v0.4.0 

func (s StorageType) IsValid() bool

IsValid checks if the StorageType is valid

func (StorageType) String added in v0.4.0 

func (s StorageType) String() string

String returns the string representation of the StorageType

type TopLevelDomain added in v0.4.0 

type TopLevelDomain string
const (
	TopLevelDomainAPAC TopLevelDomain = "asia"
	TopLevelDomainAU   TopLevelDomain = "com.au"
	TopLevelDomainCA   TopLevelDomain = "ca"
	TopLevelDomainEU   TopLevelDomain = "eu"
	TopLevelDomainNA   TopLevelDomain = "com"
	TopLevelDomainSG   TopLevelDomain = "sg"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.