webauthn

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Nov 15, 2021 License: Apache-2.0 Imports: 10 Imported by: 1

Documentation

Overview

Package webauthn provides core definitions supporting passwordless authentication through the Hanko Authentication API using FIDO2/WebAuthn.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AuthenticationFinalizationRequest 

type AuthenticationFinalizationRequest struct {
	protocol.CredentialAssertionResponse
}

AuthenticationFinalizationRequest contains the representation of a PublicKeyCredential obtained through assertion generation via the browsers' navigator.credentials.get().

See also: https://www.w3.org/TR/webauthn-2/#publickeycredential

func ParseAuthenticationFinalizationRequest 

func ParseAuthenticationFinalizationRequest(reader io.Reader) (request *AuthenticationFinalizationRequest, err error)

ParseAuthenticationFinalizationRequest decodes the content of the specified io.Reader into a AuthenticationFinalizationRequest.

type AuthenticationFinalizationResponse 

type AuthenticationFinalizationResponse struct {
	Credential Credential `json:"credential"`
}

AuthenticationFinalizationResponse is the response when the authentication was successful.

type AuthenticationInitializationRequest 

type AuthenticationInitializationRequest struct {
	User    hankoClient.User                           `json:"user"`
	Options AuthenticationInitializationRequestOptions `json:"options"`
}

AuthenticationInitializationRequest is used to initialize an authentication operation.

func NewAuthenticationInitializationRequest 

func NewAuthenticationInitializationRequest() (request *AuthenticationInitializationRequest)

NewAuthenticationInitializationRequest creates a new AuthenticationInitializationRequest.

func (*AuthenticationInitializationRequest) WithAuthenticatorAttachment 

func (request *AuthenticationInitializationRequest) WithAuthenticatorAttachment(authenticatorAttachment AuthenticatorAttachment) *AuthenticationInitializationRequest

WithAuthenticatorAttachment allows you to set the AuthenticatorAttachment modality for the authentication initialization.

func (*AuthenticationInitializationRequest) WithUser 

func (request *AuthenticationInitializationRequest) WithUser(user AuthenticationInitializationUser) *AuthenticationInitializationRequest

WithUser allows you to set an AuthenticationInitializationUser which is necessary to authenticate with non-resident keys.

func (*AuthenticationInitializationRequest) WithUserVerification 

func (request *AuthenticationInitializationRequest) WithUserVerification(userVerificationRequirement UserVerificationRequirement) *AuthenticationInitializationRequest

WithUserVerification allows you to set your UserVerification requirements for the authentication. If not set, the value default to "preferred" (VerificationPreferred) during authentication.

type AuthenticationInitializationRequestOptions 

type AuthenticationInitializationRequestOptions struct {
	UserVerification        UserVerificationRequirement `json:"userVerification"`
	AuthenticatorAttachment AuthenticatorAttachment     `json:"authenticatorAttachment"`
}

AuthenticationInitializationRequestOptions allows you to set additional authenticator attributes for the authentication initialization.

type AuthenticationInitializationResponse 

type AuthenticationInitializationResponse struct {
	protocol.CredentialAssertion
}

AuthenticationInitializationResponse contains the representation of CredentialRequestOptions generated by the Hanko Authentication API that must be passed to browser's WebAuthn API via navigator.credentials.get() in order to authenticate with a credential/create an assertion.

See also: https://www.w3.org/TR/webauthn-2/#sctn-credentialrequestoptions-extension

type AuthenticationInitializationUser 

type AuthenticationInitializationUser struct {
	hankoClient.User
}

AuthenticationInitializationUser is the user representation used for an authentication initialization.

func NewAuthenticationInitializationUser 

func NewAuthenticationInitializationUser(id string) AuthenticationInitializationUser

NewAuthenticationInitializationUser creates a new AuthenticationInitializationUser.

type Authenticator 

type Authenticator struct {
	// The "Authenticator Attestation Globally Unique ID" is a 128-bit identifier indicating the type
	// (e.g. make and model) of the authenticator.
	Aaguid string `json:"aaguid,omitempty"`

	// A description of the authenticator.
	Name string `json:"name,omitempty"`

	// The AuthenticatorAttachment modality of the authenticator.
	Attachment string `json:"attachment,omitempty"`
}

Authenticator holds information about the authenticator associated with a registered credential.

type AuthenticatorAttachment 

type AuthenticatorAttachment string

WebAuthn relying parties use this to express a preferred authenticator attachment modality when calling navigator.credentials.create() to create a credential.

See also: https://www.w3.org/TR/webauthn/#enum-attachment 

const (
	// Indicates that the authenticator should be a platform authenticator
	Platform AuthenticatorAttachment = "platform"

	// Indicates that the authenticator should be a roaming authenticator
	CrossPlatform AuthenticatorAttachment = "cross-platform"
)

type AuthenticatorSelection 

type AuthenticatorSelection struct {
	AuthenticatorAttachment AuthenticatorAttachment     `json:"authenticatorAttachment,omitempty"`
	RequireResidentKey      bool                        `json:"requireResidentKey,omitempty"`
	UserVerification        UserVerificationRequirement `json:"userVerification,omitempty"`
}

AuthenticatorSelection specifies the requirements regarding authenticator attributes for credential creation.

func NewAuthenticatorSelection 

func NewAuthenticatorSelection() *AuthenticatorSelection

NewAuthenticatorSelection creates a new AuthenticatorSelection used to initialize a credential registration.

func (*AuthenticatorSelection) WithAuthenticatorAttachment 

func (authenticatorSelection *AuthenticatorSelection) WithAuthenticatorAttachment(authenticatorAttachment AuthenticatorAttachment) *AuthenticatorSelection

WithAuthenticatorAttachment allows you to set your preferred authenticator attachment modality.

func (*AuthenticatorSelection) WithRequireResidentKey 

func (authenticatorSelection *AuthenticatorSelection) WithRequireResidentKey(requireResidentKey bool) *AuthenticatorSelection

WithRequireResidentKey allows you to specify whether a credential should be registered as a resident credential.

If set to true, the user must use an authenticator device that supports resident keys. If not set, the value will default to "false" and the credential will not be registered as a resident credential.

func (*AuthenticatorSelection) WithUserVerification 

func (authenticatorSelection *AuthenticatorSelection) WithUserVerification(userVerificationRequirement UserVerificationRequirement) *AuthenticatorSelection

WithUserVerification allows you to set your UserVerificationRequirement for the credential registration. If not set, the value will default to "preferred" (VerificationPreferred) during registration.

type Client 

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

Client wraps a basic client.Client and provides methods for registration, authentication and webauthn credential management (i.e. credential retrieval, update, and deletion).

func NewClient 

func NewClient(baseUrl string, secret string) *Client

NewClient creates a new webauthn.Client. Provide the baseUrl of the Hanko Authentication API server and your API secret in order to make authenticated requests to the API.

You can obtain API keys and the API's baseUrl through the Hanko Console (https://console.hanko.io). To create API keys (an API Key ID, API secret pair) in the console, log in, select your relying party and go to "General Settings" -> "ApiKeys" -> "Add new". Make sure you provide an API secret when constructing the Client via NewClient() accordingly.

Note: It is recommended to use HMAC authorization. See the Client.WithHmac option for more details.

func (*Client) DeleteCredential 

func (c *Client) DeleteCredential(credentialId string) (err *hankoClient.ApiError)

DeleteCredential deletes the Credential with the specified credentialId.

func (*Client) FinalizeAuthentication 

func (c *Client) FinalizeAuthentication(requestBody *AuthenticationFinalizationRequest) (response *AuthenticationFinalizationResponse, err *hankoClient.ApiError)

FinalizeAuthentication finalizes the authentication request initiated by the InitializeAuthentication method. Provide a AuthenticationFinalizationRequest which represents the result of calling the browser's WebAuthn API's navigator.credentials.get() function.

func (*Client) FinalizeRegistration 

func (c *Client) FinalizeRegistration(requestBody *RegistrationFinalizationRequest) (response *RegistrationFinalizationResponse, err *hankoClient.ApiError)

FinalizeRegistration finalizes the registration request initiated by the InitializeRegistration method. Provide a RegistrationFinalizationRequest which represents the result of calling the browser's WebAuthn API's navigator.credentials.create() function.

func (*Client) FinalizeTransaction 

func (c *Client) FinalizeTransaction(requestBody *TransactionFinalizationRequest) (response *TransactionFinalizationResponse, err *hankoClient.ApiError)

FinalizeTransaction finalizes the transaction request initiated by the InitializeTransaction method. Provide a TransactionFinalizationRequest which represents the result of calling of the browser's WebAuthn API's navigator.credentials.get() function.

func (*Client) GetCredential 

func (c *Client) GetCredential(credentialId string) (response *Credential, err *hankoClient.ApiError)

GetCredential returns the Credential with the specified credentialId.

func (*Client) InitializeAuthentication 

func (c *Client) InitializeAuthentication(requestBody *AuthenticationInitializationRequest) (response *AuthenticationInitializationResponse, err *hankoClient.ApiError)

InitializeAuthentication initializes an authentication with a registered credential using an AuthenticationInitializationRequest. On successful initialization, the Hanko Authentication API returns a AuthenticationInitializationResponse. Send the response to your client application in order to pass it to the browser's WebAuthn API's navigator.credentials.get() function.

func (*Client) InitializeRegistration 

func (c *Client) InitializeRegistration(requestBody *RegistrationInitializationRequest) (response *RegistrationInitializationResponse, err *hankoClient.ApiError)

InitializeRegistration initializes the registration of a new credential using a RegistrationInitializationRequest. On successful initialization, the Hanko Authentication API returns a RegistrationInitializationResponse. Send the response to your client application in order to pass it to the browser's WebAuthn API's navigator.credentials.create() function.

func (*Client) InitializeTransaction 

func (c *Client) InitializeTransaction(requestBody *TransactionInitializationRequest) (response *TransactionInitializationResponse, err *hankoClient.ApiError)

InitializeTransaction initiates a transaction. A transaction operation is analogous to the authentication operation, with the main difference being that a transaction context must be provided in the form of a string. This value will become part of the challenge an authenticator signs over during the operation.

Initialize a transaction using a TransactionInitializationRequest. On successful initialization, the Hanko Authentication API returns a TransactionInitializationResponse. Send the response to your client application in order to pass it to the browser's WebAuthn API's navigator.credentials.get() function.

func (*Client) ListCredentials 

func (c *Client) ListCredentials(credentialQuery *CredentialQuery) (response *[]Credential, err *hankoClient.ApiError)

ListCredentials returns a list of Credential. Filter by userId and paginate results using a CredentialQuery. The value for PageSize defaults to 10 and the value for Page to 1.

func (*Client) UpdateCredential 

func (c *Client) UpdateCredential(credentialId string, requestBody *CredentialUpdateRequest) (response *Credential, err *hankoClient.ApiError)

UpdateCredential updates the Credential with the specified credentialId. Provide a CredentialUpdateRequest with the updated data. Currently, you can only update the name of a Credential.

func (*Client) WithHmac 

func (c *Client) WithHmac(hmacApiKeyId string) *Client

WithHmac sets the hmacApiKeyId. If set, the Client will use HMAC authorization when making a request to the Hanko Authentication API. This means an HMAC token will be calculated and used in the HTTP authorization header of each request.

You can generate API Keys consisting of an API Key ID (here: hmacApiKeyId), API secret pair through the Hanko Console (https://console.hanko.io). To create API keys (an API Key ID, API secret pair) in the Console, log in, select your relying party and go to "General Settings" -> "ApiKeys" -> "Add new". Make sure you provide an API secret in when constructing the Client via NewClient() accordingly.

func (*Client) WithHttpClient 

func (c *Client) WithHttpClient(httpClient *http.Client) *Client

WithHttpClient allows you to set a custom http.Client. This can be useful, for example, if you want to configure an HTTP proxy.

func (*Client) WithLogFormatter 

func (c *Client) WithLogFormatter(formatter log.Formatter) *Client

WithLogFormatter allows you to set the specified logrus.Formatter. The default formatter is logrus.JSONFormatter.

func (*Client) WithLogLevel 

func (c *Client) WithLogLevel(level log.Level) *Client

WithLogLevel allows you to set the specified logrus.Level. The default level is logrus.InfoLevel.

func (*Client) WithLogger 

func (c *Client) WithLogger(logger *log.Logger) *Client

WithLogger allows you to set your own custom logrus.Logger.

func (*Client) WithoutLogs 

func (c *Client) WithoutLogs() *Client

WithoutLogs allows you to disable logging by setting an io.Writer that discards the logs.

type ConveyancePreference 

type ConveyancePreference string

WebAuthn relying parties may use ConveyancePreference to specify their preference regarding attestation conveyance during credential generation.

See also: https://www.w3.org/TR/webauthn/#enum-attestation-convey 

const (
	// Indicates that the relying party is not interested in authenticator attestation.
	PreferNoAttestation ConveyancePreference = "none"

	// Indicates that the relying party prefers an attestation conveyance yielding verifiable attestation
	// statements, but allows the client to decide how to obtain such attestation statements. Note: There is
	// no guarantee that the RP will obtain a verifiable attestation statement in this case. For example, in
	// the case that the authenticator employs self attestation.
	PreferIndirectAttestation ConveyancePreference = "indirect"

	// Indicates that the relying party wants to receive the attestation statement as generated by the
	// authenticator.
	PreferDirectAttestation ConveyancePreference = "direct"
)

type Credential 

type Credential struct {
	// ID of the credential.
	Id string `json:"id"`

	// Time of credential creation in date-time notation as defined by RFC 3339, section 5.6.
	CreatedAt time.Time `json:"createdAt"`

	// Last time this credential was used for authentication in date-time notation as defined by RFC 3339, section 5.6.
	LastUsed time.Time `json:"lastUsed"`

	// A human-palatable name for the credential that has a default value on credential creation but can be changed later
	// through the Update credential operation.
	Name string `json:"name"`

	// Indicates whether this credential was registered with a successful user verification process.
	UserVerification bool `json:"userVerification"`

	// Indicates whether this credential was registered as a resident credential/client-side discoverable credential.
	IsResidentKey bool `json:"isResidentKey"`

	// Representation of the authenticator used for registering the credential.
	Authenticator *Authenticator `json:"authenticator,omitempty"`

	// Representation of the user who registered the credential.
	User hankoClient.User `json:"user"`
}

Credential represents a credential.

type CredentialQuery 

type CredentialQuery struct {
	UserId   string `json:"user_id" url:"user_id"`     // The user ID to filter by.
	PageSize uint   `json:"page_size" url:"page_size"` // The page size of the returned result set.
	Page     uint   `json:"page" url:"page"`           // The desired page to return from the result set.
}

CredentialQuery is used to search for credentials.

func NewCredentialQuery 

func NewCredentialQuery() *CredentialQuery

NewCredentialQuery creates a new CredentialQuery that can be used to filter and paginate results when retrieving credentials.

func (*CredentialQuery) WithPage 

func (c *CredentialQuery) WithPage(page uint) *CredentialQuery

WithPage allows you to specify which page of the result set to return.

func (*CredentialQuery) WithPageSize 

func (c *CredentialQuery) WithPageSize(pageSize uint) *CredentialQuery

WithPageSize allows you to specify the page size of the result set.

func (*CredentialQuery) WithUserId 

func (c *CredentialQuery) WithUserId(id string) *CredentialQuery

WithUserId allows you to filter credentials by the specified user id.

type CredentialUpdateRequest 

type CredentialUpdateRequest struct {
	Name string `json:"name"`
}

CredentialUpdateRequest is used to update an existing credential.

func NewCredentialUpdateRequest 

func NewCredentialUpdateRequest() *CredentialUpdateRequest

NewCredentialUpdateRequest creates a CredentialUpdateRequest for updating the credential. Currently, it is only possible to update the credential name.

func (*CredentialUpdateRequest) WithName 

func (c *CredentialUpdateRequest) WithName(name string) *CredentialUpdateRequest

WithName allows you to specify the new name of credential to update.

type RegistrationFinalizationRequest 

type RegistrationFinalizationRequest struct {
	protocol.CredentialCreationResponse
}

RegistrationFinalizationRequest contains the representation of a PublicKeyCredential obtained through credential creation via the browsers' navigator.credentials.create().

See also: https://www.w3.org/TR/webauthn-2/#publickeycredential

func ParseRegistrationFinalizationRequest 

func ParseRegistrationFinalizationRequest(requestBody io.Reader) (request *RegistrationFinalizationRequest, err error)

ParseRegistrationFinalizationRequest decodes the content of the specified io.Reader into a RegistrationFinalizationRequest.

type RegistrationFinalizationResponse 

type RegistrationFinalizationResponse struct {
	Credential Credential `json:"credential"`
}

RegistrationFinalizationResponse is the response when the credential registration was successful.

type RegistrationInitializationRequest 

type RegistrationInitializationRequest struct {
	User    hankoClient.User                         `json:"user"`
	Options RegistrationInitializationRequestOptions `json:"options"`
}

RegistrationInitializationRequest is used to initialize a credential registration operation.

func NewRegistrationInitializationRequest 

func NewRegistrationInitializationRequest(user RegistrationInitializationUser) *RegistrationInitializationRequest

NewRegistrationInitializationRequest creates a new RegistrationInitializationRequest.

func (*RegistrationInitializationRequest) WithAuthenticatorSelection 

func (request *RegistrationInitializationRequest) WithAuthenticatorSelection(authenticatorSelection *AuthenticatorSelection) *RegistrationInitializationRequest

WithAuthenticatorSelection lets you specify the requirements regarding authenticator attributes.

func (*RegistrationInitializationRequest) WithConveyancePreference 

func (request *RegistrationInitializationRequest) WithConveyancePreference(conveyancePreference ConveyancePreference) *RegistrationInitializationRequest

WithConveyancePreference allows you to set the preferred authenticator attestation ConveyancePreference. If not set, the value will default to "none" (PreferNoAttestation) during registration.

type RegistrationInitializationRequestOptions 

type RegistrationInitializationRequestOptions struct {
	AuthenticatorSelection *AuthenticatorSelection `json:"authenticatorSelection"`
	ConveyancePreference   ConveyancePreference    `json:"attestation"`
}

RegistrationInitializationRequestOptions allows you to set additional authenticator attributes for a registration initialization request.

type RegistrationInitializationResponse 

type RegistrationInitializationResponse struct {
	protocol.CredentialCreation
}

RegistrationInitializationResponse contains the representation of CredentialCreationOptions generated by the Hanko Authentication API that must be passed to browser's WebAuthn API via navigator.credentials.create() in order to create a credential.

See also: https://www.w3.org/TR/webauthn/#sctn-credentialcreationoptions-extension

type RegistrationInitializationUser 

type RegistrationInitializationUser struct {
	hankoClient.User
}

RegistrationInitializationUser is the user representation used for credential registration initialization.

func NewRegistrationInitializationUser 

func NewRegistrationInitializationUser(id string, name string) RegistrationInitializationUser

NewRegistrationInitializationUser creates a new RegistrationInitializationUser

func (RegistrationInitializationUser) WithDisplayName 

func (user RegistrationInitializationUser) WithDisplayName(displayName string) RegistrationInitializationUser

WithDisplayName can be used to set a different displayName for the user.

It is intended that the user specifies this value. If not specified the displayName defaults to the value of the name given on construction.

type TransactionFinalizationRequest 

type TransactionFinalizationRequest struct {
	AuthenticationFinalizationRequest
}

TransactionFinalizationRequest contains the representation of a PublicKeyCredential obtained through assertion generation via the browsers' navigator.credentials.get().

See also: https://www.w3.org/TR/webauthn-2/#publickeycredential

type TransactionFinalizationResponse 

type TransactionFinalizationResponse struct {
	AuthenticationFinalizationResponse
}

TransactionFinalizationResponse is the response when the transaction was successful.

type TransactionInitializationRequest 

type TransactionInitializationRequest struct {
	User        hankoClient.User                           `json:"user"`
	Options     AuthenticationInitializationRequestOptions `json:"options"`
	Transaction string                                     `json:"transaction"`
}

TransactionInitializationRequest is used to initialize a transaction operation.

func NewTransactionInitializationRequest 

func NewTransactionInitializationRequest(user AuthenticationInitializationUser) (request *TransactionInitializationRequest)

NewTransactionInitializationRequest creates a new TransactionInitializationRequest.

func (*TransactionInitializationRequest) WithAuthenticatorAttachment 

func (request *TransactionInitializationRequest) WithAuthenticatorAttachment(authenticatorAttachment AuthenticatorAttachment) *TransactionInitializationRequest

WithAuthenticatorAttachment allows you to set your preferred authenticator attachment modality for the transaction initialization.

func (*TransactionInitializationRequest) WithTransaction 

func (request *TransactionInitializationRequest) WithTransaction(txt string) *TransactionInitializationRequest

WithTransaction specifies the transaction text to be verified by the user.

func (*TransactionInitializationRequest) WithUserVerification 

func (request *TransactionInitializationRequest) WithUserVerification(userVerificationRequirement UserVerificationRequirement) *TransactionInitializationRequest

WithUserVerification allows you to set your UserVerification requirements for the transaction. If not set, the value default to "preferred" (VerificationPreferred) during authentication.

type TransactionInitializationResponse 

type TransactionInitializationResponse struct {
	AuthenticationInitializationResponse
}

TransactionInitializationResponse contains the representation of CredentialRequestOptions generated by the Hanko Authentication API that must be passed to browser's WebAuthn API via navigator.credentials.get() in order to authenticate with a credential/create an assertion.

See also: https://www.w3.org/TR/webauthn-2/#sctn-credentialrequestoptions-extension

type UserVerificationRequirement 

type UserVerificationRequirement string

A WebAuthn relying party may require user verification for some of its operations but not for others, and may use this type to express its needs.

See also: https://www.w3.org/TR/webauthn/#enum-userVerificationRequirement 

const (
	// Indicates that user verification is required for the operation. the operation will fail if the
	// authenticator response does not have the user verification flag set.
	VerificationRequired UserVerificationRequirement = "required"

	// Indicates that the relying party prefers user verification for the operation if possible, but will
	//not fail the operation if the response does not have the user verification flag set.
	VerificationPreferred UserVerificationRequirement = "preferred"

	// Indicates that the relying party does not want user verification employed during the operation.
	VerificationDiscouraged UserVerificationRequirement = "discouraged"
)

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.