Documentation
¶
Overview ¶
Package webauthn implements server-side support for the Web Authentication specification.
Refer to https://www.w3.org/TR/webauthn-2/ for details.
Index ¶
- Constants
- func CredentialAssertionResponseToProto(car *CredentialAssertionResponse) *wantypes.CredentialAssertionResponse
- func CredentialAssertionToProto(assertion *CredentialAssertion) *wantypes.CredentialAssertion
- func CredentialCreationResponseToProto(ccr *CredentialCreationResponse) *wantypes.CredentialCreationResponse
- func CredentialCreationToProto(cc *CredentialCreation) *wantypes.CredentialCreation
- func U2FKeyToCBOR(pubKey *ecdsa.PublicKey) ([]byte, error)
- type AuthenticationExtensionsClientOutputs
- type AuthenticatorAssertionResponse
- type AuthenticatorAttestationResponse
- type AuthenticatorResponse
- type Credential
- type CredentialAssertion
- type CredentialAssertionResponse
- type CredentialCreation
- type CredentialCreationResponse
- type LoginFlow
- type LoginIdentity
- type PasswordlessFlow
- type PasswordlessIdentity
- type PublicKeyCredential
- type RegisterResponse
- type RegistrationFlow
- type RegistrationIdentity
Constants ¶
const AppIDExtension = "appid"
AppIDExtension is the key for the appid extension. https://www.w3.org/TR/webauthn-2/#sctn-appid-extension.
Variables ¶
This section is empty.
Functions ¶
func CredentialAssertionResponseToProto ¶
func CredentialAssertionResponseToProto(car *CredentialAssertionResponse) *wantypes.CredentialAssertionResponse
CredentialAssertionResponseToProto converts a CredentialAssertionResponse to its proto counterpart.
func CredentialAssertionToProto ¶
func CredentialAssertionToProto(assertion *CredentialAssertion) *wantypes.CredentialAssertion
CredentialAssertionToProto converts a CredentialAssertion to its proto counterpart.
func CredentialCreationResponseToProto ¶
func CredentialCreationResponseToProto(ccr *CredentialCreationResponse) *wantypes.CredentialCreationResponse
CredentialCreationResponseToProto converts a CredentialCreationResponse to its proto counterpart.
func CredentialCreationToProto ¶
func CredentialCreationToProto(cc *CredentialCreation) *wantypes.CredentialCreation
CredentialCreationToProto converts a CredentialCreation to its proto counterpart.
Types ¶
type AuthenticationExtensionsClientOutputs ¶
type AuthenticationExtensionsClientOutputs struct {
AppID bool `json:"appid,omitempty"`
}
type AuthenticatorAssertionResponse ¶
type AuthenticatorAssertionResponse struct {
AuthenticatorResponse
AuthenticatorData protocol.URLEncodedBase64 `json:"authenticatorData"`
Signature protocol.URLEncodedBase64 `json:"signature"`
UserHandle protocol.URLEncodedBase64 `json:"userHandle,omitempty"`
}
type AuthenticatorAttestationResponse ¶
type AuthenticatorAttestationResponse struct {
AuthenticatorResponse
AttestationObject protocol.URLEncodedBase64 `json:"attestationObject"`
}
type AuthenticatorResponse ¶
type AuthenticatorResponse protocol.AuthenticatorResponse
type Credential ¶
type Credential protocol.Credential
type CredentialAssertion ¶
type CredentialAssertion protocol.CredentialAssertion
CredentialAssertion is the payload sent to authenticators to initiate login.
func CredentialAssertionFromProto ¶
func CredentialAssertionFromProto(assertion *wantypes.CredentialAssertion) *CredentialAssertion
CredentialAssertionFromProto converts a CredentialAssertion proto to its lib counterpart.
func (*CredentialAssertion) Validate ¶
func (ca *CredentialAssertion) Validate() error
Validate performs client-side validation of CredentialAssertion. It makes sure that data are valid and can be sent to authenticator. This is general purpose validation and authenticator should add its own on top of it, if necessary.
type CredentialAssertionResponse ¶
type CredentialAssertionResponse struct {
PublicKeyCredential
AssertionResponse AuthenticatorAssertionResponse `json:"response"`
}
CredentialAssertionResponse is the reply from authenticators to complete login.
func CredentialAssertionResponseFromProto ¶
func CredentialAssertionResponseFromProto(car *wantypes.CredentialAssertionResponse) *CredentialAssertionResponse
CredentialAssertionResponseFromProto converts a CredentialAssertionResponse proto to its lib counterpart.
type CredentialCreation ¶
type CredentialCreation protocol.CredentialCreation
CredentialCreation is the payload sent to authenticators to initiate registration.
func CredentialCreationFromProto ¶
func CredentialCreationFromProto(cc *wantypes.CredentialCreation) *CredentialCreation
CredentialCreationFromProto converts a CredentialCreation proto to its lib counterpart.
func (*CredentialCreation) RequireResidentKey ¶
func (cc *CredentialCreation) RequireResidentKey() (bool, error)
RequireResidentKey returns information whether resident key is required or not. It checks ResidentKey and fallbacks to RequireResidentKey.
func (*CredentialCreation) Validate ¶
func (cc *CredentialCreation) Validate() error
Validate performs client-side validation of CredentialCreation. It makes sure that data are valid and can be sent to authenticator. This is general purpose validation and authenticator should add its own on top of it, if necessary.
type CredentialCreationResponse ¶
type CredentialCreationResponse struct {
PublicKeyCredential
AttestationResponse AuthenticatorAttestationResponse `json:"response"`
}
CredentialCreationResponse is the reply from authenticators to complete registration.
func CredentialCreationResponseFromProto ¶
func CredentialCreationResponseFromProto(ccr *wantypes.CredentialCreationResponse) *CredentialCreationResponse
CredentialCreationResponseFromProto converts a CredentialCreationResponse proto to its lib counterpart.
type LoginFlow ¶
type LoginFlow struct {
U2F *types.U2F
Webauthn *types.Webauthn
// Identity is typically an implementation of the Identity service, ie, an
// object with access to user, device and MFA storage.
Identity LoginIdentity
}
LoginFlow represents the WebAuthn login procedure (aka authentication).
The login flow consists of:
- Client requests a CredentialAssertion (containing, among other info, a challenge to be signed)
- Server runs Begin(), generates a credential assertion.
- Client validates the assertion, performs a user presence test (usually by asking the user to touch a secure token), and replies with CredentialAssertionResponse (containing the signed challenge)
- Server runs Finish()
- If all server-side checks are successful, then login/authentication is complete.
func (*LoginFlow) Begin ¶
Begin is the first step of the LoginFlow. The CredentialAssertion created is relayed back to the client, who in turn performs a user presence check and signs the challenge contained within the assertion. As a side effect Begin may assign (and record in storage) a WebAuthn ID for the user.
func (*LoginFlow) Finish ¶
func (f *LoginFlow) Finish(ctx context.Context, user string, resp *CredentialAssertionResponse) (*types.MFADevice, error)
Finish is the second and last step of the LoginFlow. It returns the MFADevice used to solve the challenge. If login is successful, Finish has the side effect of updating the counter and last used timestamp of the returned device.
type LoginIdentity ¶
type LoginIdentity interface {
GetWebauthnLocalAuth(ctx context.Context, user string) (*types.WebauthnLocalAuth, error)
GetMFADevices(ctx context.Context, user string, withSecrets bool) ([]*types.MFADevice, error)
UpsertMFADevice(ctx context.Context, user string, d *types.MFADevice) error
UpsertWebauthnSessionData(ctx context.Context, user, sessionID string, sd *wantypes.SessionData) error
GetWebauthnSessionData(ctx context.Context, user, sessionID string) (*wantypes.SessionData, error)
DeleteWebauthnSessionData(ctx context.Context, user, sessionID string) error
}
LoginIdentity represents the subset of Identity methods used by LoginFlow. It exists to better scope LoginFlow's use of Identity and to facilitate testing.
func WithDevices ¶
func WithDevices(identity LoginIdentity, devs []*types.MFADevice) LoginIdentity
WithDevices returns a LoginIdentity backed by a fixed set of devices. The supplied devices are returned in all GetMFADevices calls.
type PasswordlessFlow ¶
type PasswordlessFlow struct {
Webauthn *types.Webauthn
Identity PasswordlessIdentity
}
PasswordlessFlow provides passwordless authentication.
func (*PasswordlessFlow) Begin ¶
func (f *PasswordlessFlow) Begin(ctx context.Context) (*CredentialAssertion, error)
Begin is the first step of the passwordless login flow. It works similarly to LoginFlow.Begin, but it doesn't require a Teleport username nor implies a previous password-validation step.
func (*PasswordlessFlow) Finish ¶
func (f *PasswordlessFlow) Finish(ctx context.Context, resp *CredentialAssertionResponse) (*types.MFADevice, string, error)
Finish is the last step of the passwordless login flow. It works similarly to LoginFlow.Finish, but the user identity is established via the response UserHandle, instead of an explicit Teleport username.
type PasswordlessIdentity ¶
type PasswordlessIdentity interface {
GetMFADevices(ctx context.Context, user string, withSecrets bool) ([]*types.MFADevice, error)
UpsertMFADevice(ctx context.Context, user string, d *types.MFADevice) error
UpsertGlobalWebauthnSessionData(ctx context.Context, scope, id string, sd *wantypes.SessionData) error
GetGlobalWebauthnSessionData(ctx context.Context, scope, id string) (*wantypes.SessionData, error)
DeleteGlobalWebauthnSessionData(ctx context.Context, scope, id string) error
GetTeleportUserByWebauthnID(ctx context.Context, webID []byte) (string, error)
}
PasswordlessIdentity represents the subset of Identity methods used by PasswordlessFlow.
type PublicKeyCredential ¶
type PublicKeyCredential struct {
Credential
RawID protocol.URLEncodedBase64 `json:"rawId"`
Extensions *AuthenticationExtensionsClientOutputs `json:"extensions,omitempty"`
}
type RegisterResponse ¶
type RegisterResponse struct {
// User is the device owner.
User string
// DeviceName is the name for the new device.
DeviceName string
// CreationResponse is the response from the new device.
CreationResponse *CredentialCreationResponse
// Passwordless is true if this is expected to be a passwordless registration.
// Callers may make certain concessions when processing passwordless
// registration (such as skipping password validation), this flag reflects that.
// The data stored in the Begin SessionData must match the passwordless flag,
// otherwise the registration is denied.
Passwordless bool
}
RegisterResponse represents fields needed to finish registering a new webautn device.
type RegistrationFlow ¶
type RegistrationFlow struct {
Webauthn *types.Webauthn
Identity RegistrationIdentity
}
RegistrationFlow represents the WebAuthn registration ceremony.
Registration consists of:
- Client requests a CredentialCreation (containing a challenge and various settings that may constrain allowed authenticators).
- Server runs Begin(), generates a credential creation.
- Client validates the credential creation, performs a user presence test (usually by asking the user to touch a secure token), and replies with a CredentialCreationResponse (containing the signed challenge and information about the credential and authenticator)
- Server runs Finish()
- If all server-side checks are successful, then registration is complete and the authenticator may now be used to login.
func (*RegistrationFlow) Begin ¶
func (f *RegistrationFlow) Begin(ctx context.Context, user string, passwordless bool) (*CredentialCreation, error)
Begin is the first step of the registration ceremony. The CredentialCreation created is relayed back to the client, who in turn performs a user presence check and signs the challenge contained within it. If passwordless is set, then registration asks the authenticator for a resident key. As a side effect Begin may assign (and record in storage) a WebAuthn ID for the user.
func (*RegistrationFlow) Finish ¶
func (f *RegistrationFlow) Finish(ctx context.Context, req RegisterResponse) (*types.MFADevice, error)
Finish is the second and last step of the registration ceremony. If successful, it returns the created MFADevice. Finish has the side effect or writing the device to storage (using its Identity interface).
type RegistrationIdentity ¶
type RegistrationIdentity interface {
UpsertWebauthnLocalAuth(ctx context.Context, user string, wla *types.WebauthnLocalAuth) error
GetWebauthnLocalAuth(ctx context.Context, user string) (*types.WebauthnLocalAuth, error)
GetTeleportUserByWebauthnID(ctx context.Context, webID []byte) (string, error)
GetMFADevices(ctx context.Context, user string, withSecrets bool) ([]*types.MFADevice, error)
UpsertMFADevice(ctx context.Context, user string, d *types.MFADevice) error
UpsertWebauthnSessionData(ctx context.Context, user, sessionID string, sd *wantypes.SessionData) error
GetWebauthnSessionData(ctx context.Context, user, sessionID string) (*wantypes.SessionData, error)
DeleteWebauthnSessionData(ctx context.Context, user, sessionID string) error
}
RegistrationIdentity represents the subset of Identity methods used by RegistrationFlow.
func WithInMemorySessionData ¶
func WithInMemorySessionData(identity RegistrationIdentity) RegistrationIdentity
WithInMemorySessionData returns a RegistrationIdentity implementation that keeps SessionData in memory.
Source Files
Directories