Documentation
¶
Overview ¶
Package authorizationcode provides OAuth2 authorization code flow authentication for gRPC connections. It implements the authorization code grant type as defined in RFC 6749, Section 4.1, and REQUIRES PKCE (RFC 7636) with the S256 challenge method to protect the authorization code exchange.
This flow is designed for interactive user authentication where a browser login is required. It starts a local callback server to receive the authorization code and exchanges it for tokens.
See: https://datatracker.ietf.org/doc/html/rfc6749#section-4.1 See: https://datatracker.ietf.org/doc/html/rfc7636
Index ¶
- type Provider
- type ProviderOption
- func WithAudience(audience string) ProviderOption
- func WithCallbackURL(callbackURL string) ProviderOption
- func WithOpenBrowser(openBrowser bool) ProviderOption
- func WithScopes(scopes ...string) ProviderOption
- func WithTimeout(timeout time.Duration) ProviderOption
- func WithTransportCredentials(credentials credentials.TransportCredentials) ProviderOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
func NewDiscoveryProvider ¶
func NewDiscoveryProvider(ctx context.Context, authorizationServerURL, clientID string, options ...ProviderOption) (*Provider, error)
NewDiscoveryProvider creates a provider using OAuth2 Authorization Server Metadata discovery to automatically locate the authorization and token endpoints. This implements the discovery mechanism defined in RFC 8414, querying the .well-known/oauth-authorization-server endpoint.
PKCE with the S256 challenge method is REQUIRED; an error is returned if the server does not advertise support for S256.
Parameters:
- ctx: Context for metadata discovery and the token exchange
- authorizationServerURL: The base URL of the authorization server (e.g., "https://auth.example.com")
- clientID: The OAuth2 client identifier issued by the authorization server
- options: Optional configuration parameters (scopes, transport credentials, callback URL, timeout, etc.)
Returns an error if discovery fails or if the server does not support S256 PKCE challenges.
func NewProvider ¶
func NewProvider(ctx context.Context, authURL, tokenURL, clientID string, options ...ProviderOption) (*Provider, error)
NewProvider creates a provider that performs the OAuth2 authorization code flow with PKCE (S256). It starts a local callback server to receive the authorization code and exchanges it for tokens.
PKCE with the S256 challenge method is REQUIRED for this flow.
Parameters:
- ctx: Context for the overall flow; can be configured with a timeout via WithTimeout
- authURL: The OAuth2 authorization endpoint URL
- tokenURL: The OAuth2 token endpoint URL
- clientID: The OAuth2 client identifier issued by the authorization server
- options: Optional configuration parameters (scopes, transport credentials, callback URL, etc.)
Returns an error if any required parameter is empty or if the callback server cannot be started.
See: https://datatracker.ietf.org/doc/html/rfc6749#section-4.1
func (Provider) PerRPCCredentials ¶
func (p Provider) PerRPCCredentials() credentials.PerRPCCredentials
PerRPCCredentials returns the per-RPC credentials that attach OAuth2 tokens to each gRPC call. The credentials implement RFC 6750 Bearer Token usage, adding the access token to the Authorization header of each RPC using the format: "Authorization: Bearer <token>".
func (Provider) TokenSource ¶
func (p Provider) TokenSource() oauth2.TokenSource
TokenSource returns the OAuth2 token source for obtaining access tokens. The token source automatically handles token refresh and caching.
func (Provider) TransportCredentials ¶
func (p Provider) TransportCredentials() credentials.TransportCredentials
TransportCredentials returns the transport credentials for establishing gRPC connections.
type ProviderOption ¶
type ProviderOption func(*authorizationCodeProviderConfig)
ProviderOption configures the authorization code Provider using the functional options pattern. Options allow customization of scopes, audience, transport credentials, callback URL, browser behavior, and overall flow timeout.
func WithAudience ¶
func WithAudience(audience string) ProviderOption
WithAudience configures the Provider to request access tokens with the given audience. The audience identifies the intended recipient of the issued access token (typically the resource server / API that will consume the token, e.g. the Canton ledger API).
When configured, it is appended to the authorization request as an "audience" query parameter. This is an Auth0-specific extension: Auth0 uses the "audience" parameter to select which API (and therefore which value of the JWT's "aud" claim, defined in RFC 7519 Section 4.1.3) the issued access token should target.
NOTE: The "audience" parameter is NOT part of the OAuth2 specification, and most other authorization servers do not honor it:
- Okta binds the audience to the Authorization Server itself (one fixed value per AS) and explicitly does not support dynamic audience switching via a request parameter, nor RFC 8707 resource indicators. To use a different audience on Okta, point authURL/tokenURL at a different Authorization Server.
- Keycloak determines the audience server-side via audience mappers on client scopes.
This option therefore only has an effect with Auth0 (or an authorization server that explicitly emulates Auth0's behavior).
As of 2025, Auth0 also offers a tenant-level "Resource Parameter Compatibility Profile" (Dashboard → Settings → Advanced) which, when enabled, makes Auth0 honor the standardized RFC 8707 "resource" request parameter as an alternative way to set the token's audience for the authorization code flow (and PAR/JAR/CIBA/refresh token grants). When both "resource" and "audience" are sent, Auth0 still gives "audience" precedence.
If no audience is configured (the default), no "audience" parameter is sent and the authorization server determines the audience based on its own policy / client configuration.
Example:
WithAudience("https://ledger.example.com")
func WithCallbackURL ¶
func WithCallbackURL(callbackURL string) ProviderOption
WithCallbackURL configures the local redirect URI used by the authorization server. The callback URL must be reachable by the browser and is expected to be a localhost URL.
func WithOpenBrowser ¶
func WithOpenBrowser(openBrowser bool) ProviderOption
WithOpenBrowser controls whether the default browser is opened automatically. When disabled, the authorization URL is printed for manual copy/paste.
func WithScopes ¶
func WithScopes(scopes ...string) ProviderOption
WithScopes configures the Provider to request access tokens with the given scopes. Scopes define the level of access requested from the authorization server. The default scope is "daml_ledger_api" for Canton ledger API access.
Example:
WithScopes("daml_ledger_api", "read:users")
func WithTimeout ¶
func WithTimeout(timeout time.Duration) ProviderOption
WithTimeout configures a timeout for the overall authorization flow, including callback receipt.
func WithTransportCredentials ¶
func WithTransportCredentials(credentials credentials.TransportCredentials) ProviderOption
WithTransportCredentials configures the Provider to use the given transport credentials for gRPC connections. This allows customization of TLS settings, including certificate verification and minimum TLS version. The default transport credentials use TLS 1.2 or higher.
Example:
WithTransportCredentials(credentials.NewTLS(&tls.Config{InsecureSkipVerify: true}))
Source Files