urlutil

Documentation

Overview

Package urlutil provides utility functions for working with go urls.

Index

• Constants
• Variables
• func BuildTimeParameters(params url.Values, expiry time.Duration)
• func CallbackURL(authenticatePrivateKey *hpke.PrivateKey, proxyPublicKey *hpke.PublicKey, ...) (string, error)
• func DeepCopy(u *url.URL) (*url.URL, error)
• func GetAbsoluteURL(r *http.Request) *url.URL
• func GetCallbackURL(r *http.Request, encodedSessionJWT string) (*url.URL, error)
• func GetCallbackURLForRedirectURI(r *http.Request, encodedSessionJWT, rawRedirectURI string) (*url.URL, error)
• func GetDomainsForURL(u *url.URL) []string
• func GetExternalRequest(internalURL, externalURL *url.URL, r *http.Request) *http.Request
• func GetServerNamesForURL(u *url.URL) []string
• func IsHostedAuthenticateDomain(domain string) bool
• func IsLoopback(u *url.URL) bool
• func IsRedirectAllowed(redirectURL *url.URL, whitelistDomains []string) bool
• func Join(elements ...string) string
• func MatchesServerName(u url.URL, serverName string) bool
• func MustParseAndValidateURL(rawURL string) url.URL
• func ParseAndValidateURL(rawurl string) (*url.URL, error)
• func RedirectURL(r *http.Request) (string, bool)
• func SignInURL(senderPrivateKey *hpke.PrivateKey, authenticatePublicKey *hpke.PublicKey, ...) (string, error)
• func SignOutURL(r *http.Request, authenticateURL *url.URL, key []byte) string
• func StripPort(hostport string) string
• func ValidateTimeParameters(params url.Values) error
• func ValidateURL(u *url.URL) error
• func WebAuthnURL(_ *http.Request, authenticateURL *url.URL, key []byte, values url.Values) string
• type SignedURL
  • func NewSignedURL(key []byte, uri *url.URL) *SignedURL
  • func (su *SignedURL) Sign() *url.URL
  • func (su *SignedURL) String() string
  • func (su *SignedURL) Validate() error

Constants

const (
	WebAuthnURLPath    = "/.pomerium/webauthn"
	DeviceEnrolledPath = "/.pomerium/device-enrolled"
)

Device paths

const (
	QueryCallbackURI        = "pomerium_callback_uri"
	QueryDeviceCredentialID = "pomerium_device_credential_id"
	QueryDeviceType         = "pomerium_device_type"
	QueryEnrollmentToken    = "pomerium_enrollment_token" //nolint
	QueryExpiry             = "pomerium_expiry"
	QueryIdentityProfile    = "pomerium_identity_profile"
	QueryIdentityProviderID = "pomerium_idp_id"
	QueryIsProgrammatic     = "pomerium_programmatic"
	QueryIssued             = "pomerium_issued"
	QueryPomeriumJWT        = "pomerium_jwt"
	QueryRedirectURI        = "pomerium_redirect_uri"
	QuerySession            = "pomerium_session"
	QuerySessionEncrypted   = "pomerium_session_encrypted"
	QuerySessionState       = "pomerium_session_state"
	QueryVersion            = "pomerium_version"
	QueryRequestUUID        = "pomerium_request_uuid"
)

Common query parameters used to set and send data between Pomerium services over HTTP calls and redirects. They are typically used in conjunction with a HMAC to ensure authenticity.

const (
	QueryHmacExpiry    = "pomerium_expiry"
	QueryHmacIssued    = "pomerium_issued"
	QueryHmacSignature = "pomerium_signature"
)

URL signature based query params used for verifying the authenticity of a URL.

const DefaultDeviceType = "any"

DefaultDeviceType is the default device type when none is specified.

const (
	// DefaultLeeway defines the default leeway for matching NotBefore/Expiry claims.
	DefaultLeeway = 1.0 * time.Minute
)

const HPKEPublicKeyPath = "/.well-known/pomerium/hpke-public-key"

HPKEPublicKeyPath is the well-known path to the HPKE public key

Variables

var (
	// ErrExpired indicates that token is used after expiry time indicated in exp claim.
	ErrExpired = errors.New("internal/urlutil: validation failed, url hmac is expired")

	// ErrIssuedInTheFuture indicates that the issued field is in the future.
	ErrIssuedInTheFuture = errors.New("internal/urlutil: validation field, url hmac issued in the future")

	// ErrNumericDateMalformed indicates a malformed unix timestamp was found while parsing.
	ErrNumericDateMalformed = errors.New("internal/urlutil: malformed unix timestamp field")
)

var ErrMissingRedirectURI = errors.New("missing " + QueryRedirectURI)

ErrMissingRedirectURI indicates the pomerium_redirect_uri was missing from the query string.

var HostedAuthenticateDomains = []string{
	"authenticate.pomerium.app",
	"authenticate.staging.pomerium.app",
}

HostedAuthenticateDomains is a list of all known domains associated with the hosted authenticate service.

Functions

func BuildTimeParameters

func BuildTimeParameters(params url.Values, expiry time.Duration)

BuildTimeParameters adds the issued and expiry timestamps to the query parameters.

func CallbackURL

func CallbackURL(
	authenticatePrivateKey *hpke.PrivateKey,
	proxyPublicKey *hpke.PublicKey,
	requestParams url.Values,
	profile *identity.Profile,
	encryptURLValues hpke.EncryptURLValuesFunc,
) (string, error)

CallbackURL builds the callback URL using an HPKE encrypted query string.

func DeepCopy

func DeepCopy(u *url.URL) (*url.URL, error)

DeepCopy creates a deep copy of a *url.URL

func GetAbsoluteURL

func GetAbsoluteURL(r *http.Request) *url.URL

GetAbsoluteURL returns the current handler's absolute url. https://stackoverflow.com/a/23152483

func GetCallbackURL

func GetCallbackURL(r *http.Request, encodedSessionJWT string) (*url.URL, error)

GetCallbackURL gets the proxy's callback URL from a request and a base64url encoded + encrypted session state JWT.

func GetCallbackURLForRedirectURI

func GetCallbackURLForRedirectURI(r *http.Request, encodedSessionJWT, rawRedirectURI string) (*url.URL, error)

GetCallbackURLForRedirectURI gets the proxy's callback URL from a request and a base64url encoded + encrypted session state JWT.

func GetDomainsForURL

func GetDomainsForURL(u *url.URL) []string

GetDomainsForURL returns the available domains for given url.

For standard HTTP (80)/HTTPS (443) ports, it returns `example.com` and `example.com:<port>`. Otherwise, return the URL.Host value.

func GetExternalRequest

func GetExternalRequest(internalURL, externalURL *url.URL, r *http.Request) *http.Request

GetExternalRequest modifies a request so that it appears to be for an external URL instead of an internal URL.

func GetServerNamesForURL

func GetServerNamesForURL(u *url.URL) []string

GetServerNamesForURL returns the TLS server names for the given URL. The server name is the URL hostname.

func IsHostedAuthenticateDomain

func IsHostedAuthenticateDomain(domain string) bool

IsHostedAuthenticateDomain indicates whether the given domain is associated with the hosted authenticate service.

func IsLoopback

func IsLoopback(u *url.URL) bool

IsLoopback returns true if the given URL corresponds with a loopback address.

func IsRedirectAllowed

func IsRedirectAllowed(redirectURL *url.URL, whitelistDomains []string) bool

IsRedirectAllowed returns true if the redirect URL is whitelisted.

func Join

func Join(elements ...string) string

Join joins elements of a URL with '/'.

func MatchesServerName

func MatchesServerName(u url.URL, serverName string) bool

MatchesServerName returnes true if the url's host matches the given server name.

func MustParseAndValidateURL

func MustParseAndValidateURL(rawURL string) url.URL

MustParseAndValidateURL parses the URL via ParseAndValidateURL but panics if there is an error. (useful for testing)

func ParseAndValidateURL

func ParseAndValidateURL(rawurl string) (*url.URL, error)

ParseAndValidateURL wraps standard library's default url.Parse because it's much more lenient about what type of urls it accepts than pomerium.

func RedirectURL

func RedirectURL(r *http.Request) (string, bool)

RedirectURL returns the redirect URL from the query string or a cookie.

func SignInURL

func SignInURL(
	senderPrivateKey *hpke.PrivateKey,
	authenticatePublicKey *hpke.PublicKey,
	authenticateURL *url.URL,
	redirectURL *url.URL,
	idpID string,
) (string, error)

SignInURL builds the sign in URL using an HPKE encrypted query string.

func SignOutURL

func SignOutURL(r *http.Request, authenticateURL *url.URL, key []byte) string

SignOutURL returns the /.pomerium/sign_out URL.

func StripPort

func StripPort(hostport string) string

StripPort returns a host, without any port number.

If Host is an IPv6 literal with a port number, Hostname returns the IPv6 literal without the square brackets. IPv6 literals may include a zone identifier.

func ValidateTimeParameters

func ValidateTimeParameters(params url.Values) error

ValidateTimeParameters validates that the issued and expiry timestamps in the query parameters are valid.

func ValidateURL

func ValidateURL(u *url.URL) error

ValidateURL wraps standard library's default url.Parse because it's much more lenient about what type of urls it accepts than pomerium.

func WebAuthnURL

func WebAuthnURL(_ *http.Request, authenticateURL *url.URL, key []byte, values url.Values) string

WebAuthnURL returns the /.pomerium/webauthn URL.

Types

type SignedURL

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

SignedURL is a shared-key HMAC wrapped URL.

func NewSignedURL

func NewSignedURL(key []byte, uri *url.URL) *SignedURL

NewSignedURL creates a new copy of a URL that can be signed with a shared key.

N.B. It is the user's responsibility to make sure the key is 256 bits and the url is not nil.

func (*SignedURL) Sign

func (su *SignedURL) Sign() *url.URL

Sign creates a shared-key HMAC signed URL.

func (*SignedURL) String

func (su *SignedURL) String() string

String implements the stringer interface and returns a signed URL string.

func (*SignedURL) Validate

func (su *SignedURL) Validate() error

Validate checks to see if a signed URL is valid.