Documentation
¶
Overview ¶
Package sessionlogin is the session sign-in an HTTP-based connection kind authenticates with under auth_mode session_login (#2015): the keys it is configured by, their validation, and the transport that signs in, carries the session on every request, signs in again when the upstream rejects it, and signs out when the connection is released. internal/upstreamauth wires it into the connection's client; it is its own package because the shared policy reached its size budget.
Index ¶
Constants ¶
const AuthMode = "session_login"
AuthMode signs in to the upstream with a stored credential and carries the session token the sign-in returns on every call, signing in again when the upstream rejects it (#2015). It is the scheme of Tableau (personal access token to /auth/signin, X-Tableau-Auth on every call), MicroStrategy (X-MSTR-AuthToken) and Veeva Vault (sessionId as Authorization): a login endpoint that takes a vendor-shaped body and answers with a token at a vendor-chosen place, which no OAuth grant describes.
const SessionSecretPlaceholder = "{{secret}}"
SessionSecretPlaceholder is where session_login_secret is written into the sign-in body. The body itself is not secret, so an operator can read it back; the secret is stored apart from it and encrypted.
Variables ¶
var ErrSessionLogin = errors.New("session sign-in failed")
ErrSessionLogin is the error a call returns when the platform could not sign in to the upstream: the sign-in was refused, unreachable, or answered without a token where the connection says one is.
var ErrSessionRejected = errors.New("the upstream rejected a fresh session; check the connection's sign-in credential")
ErrSessionRejected is the error a call returns when the upstream rejected a session the platform had just signed in for. Signing in again would be answered the same way, so the connection's credential is what needs attention, as with an OAuth connection that needs reconnecting.
var ErrUnknownSessionValue = errors.New("the path names a session value this connection's sign-in does not capture")
ErrUnknownSessionValue is the error a call returns when its path names a {session.<name>} the connection's sign-in does not capture.
Functions ¶
func IsSessionFailure ¶
IsSessionFailure reports whether err is a session_login connection failing to sign in or having a fresh session rejected, which a connection test reports as the sign-in failing rather than the upstream being unreachable.
func IsSessionMessage ¶
IsSessionMessage reports whether an error's text, as a tool reports it to a caller, is one of the session's own: a sign-in that failed, a fresh session refused, or a session value not captured. Each is the connection's or the caller's to fix, so a tool classifying a failed call by its text reports it as the upstream's refusal rather than as an upstream that could not be reached, which a caller would retry.
func NewTransport ¶
func NewTransport(cfg Config, prefix string, next, login http.RoundTripper) http.RoundTripper
NewTransport wraps next with cfg's session. login carries the sign-in and sign-out requests. prefix names the calling kind in every error the session produces.
Types ¶
type Config ¶
type Config struct {
// LoginURL is the sign-in endpoint, resolved against the connection's
// base URL when it was written as a path.
LoginURL string
// LoginMethod is the sign-in request's method. Defaults to POST.
LoginMethod string
// LoginBody is the sign-in request's body, with
// SessionSecretPlaceholder where the secret goes.
LoginBody string
// LoginContentType is the sign-in body's media type. Defaults to
// application/json. The secret is escaped for it: JSON string, form
// value, XML text.
LoginContentType string
// Secret replaces SessionSecretPlaceholder in the body. Encrypted at
// rest.
Secret string
// LoginHeaders are sent on the sign-in request only.
LoginHeaders map[string]string
// TokenSource is where the token is in the sign-in response:
// body:<dotted json path> or header:<name>.
TokenSource string
// TokenHeader is the header the token is sent in on every call.
TokenHeader string
// TokenPrefix is written before the token in TokenHeader.
TokenPrefix string
// TTL, when positive, is how long a session is used before the
// platform signs in again without waiting to be rejected.
TTL time.Duration
// LogoutURL, when set, ends the session when the connection is
// removed, replaced or shut down.
LogoutURL string
// LogoutMethod is the sign-out request's method. Defaults to POST.
LogoutMethod string
// Capture names further values the sign-in response carries, each read
// from a source in TokenSource's form. A request writes
// {session.<name>} in its path to have the value put there.
Capture map[string]string
// ExpiredStatuses are the statuses that mean the session is no longer
// accepted. Defaults to 401.
ExpiredStatuses []int
// ExpiredMarker, when set, is text whose presence in a response body
// means the session is no longer accepted, for an upstream that
// answers an expired session with 200 or 403 and an error body.
ExpiredMarker string
}
Config is how a session_login connection signs in and carries its session.
Source Files