@simplewebauthn/server
Advanced tools
Changelog
v11.0.0 - The one that auto-registers
Say hello to support for automatic passkey registration, support for valid conditional UI <input>
elements stashed away in web components, and to the new WebAuthnCredential
type that modernizes
some logic within.
There are some breaking changes in this release! Please see Breaking Changes below for refactor guidance.
useAutoRegister
argument has been added to startRegistration()
to
support attempts to automatically register passkeys for users who just completed non-passkey auth.
verifyRegistrationResponse()
has gained a new requireUserPresence
option that can be set to
false
when verifying responses from startRegistration({ useAutoRegister: true, ... })
(#623)verifyBrowserAutofillInput
argument has been added to
startAuthentication()
to disable throwing an error when a correctly configured <input>
element
cannot be found (but perhaps a valid one is present in a web component shadow's DOM)
(#621)AuthenticatorDevice
type has been renamed to WebAuthnCredential
and
has had its properties renamed. The return value out of verifyRegistrationResponse()
and
corresponding inputs into verifyAuthenticationResponse()
have been updated accordingly. See
Breaking Changes below for refactor guidance
(#625)verifyRegistrationResponse()
now verifies that the authenticator data AAGUID
matches the leaf cert's id-fido-gen-ce-aaguid
extension AAGUID when it is present
(#609)uvm
and dpk
have been removed
(#611)startRegistration()
and startAuthentication()
have been replaced by a single objectProperty names in the object match the names of the previously-positional arguments. To update existing implementations, wrap existing options in an object with corresponding properties:
Before:
startRegistration(options);
startAuthentication(options, true);
After:
startRegistration({ optionsJSON: options });
startAuthentication({ optionsJSON: options, useBrowserAutofill: true });
AuthenticatorDevice
type has been renamed to WebAuthnCredential
AuthenticatorDevice.credentialID
and AuthenticatorDevice.credentialPublicKey
have been shortened
to WebAuthnCredential.id
and WebAuthnCredential.publicKey
respectively.
verifyRegistrationResponse()
has been updated accordingly to return a new credential
value of
type WebAuthnCredential
. Update code that stores credentialID
, credentialPublicKey
, and
counter
out of verifyRegistrationResponse()
to store credential.id
, credential.publicKey
,
and credential.counter
instead:
Before:
const { registrationInfo } = await verifyRegistrationResponse({...});
storeInDatabase(
registrationInfo.credentialID,
registrationInfo.credentialPublicKey,
registrationInfo.counter,
body.response.transports,
);
After:
const { registrationInfo } = await verifyRegistrationResponse({...});
storeInDatabase(
registrationInfo.credential.id,
registrationInfo.credential.publicKey,
registrationInfo.credential.counter,
registrationInfo.credential.transports,
);
Update calls to verifyAuthenticationResponse()
to match the new credential
argument that
replaces the authenticator
argument:
Before:
import { AuthenticatorDevice } from '@simplewebauthn/types';
const authenticator: AuthenticatorDevice = {
credentialID: ...,
credentialPublicKey: ...,
counter: 0,
transports: [...],
};
const verification = await verifyAuthenticationResponse({
// ...
authenticator,
});
After:
import { WebAuthnCredential } from '@simplewebauthn/types';
const credential: WebAuthnCredential = {
id: ...,
publicKey: ...,
counter: 0,
transports: [...],
};
const verification = await verifyAuthenticationResponse({
// ...
credential,
});
Changelog
v10.0.0 - The one that goes up to 20
Thanks for everything, Node 16 and Node 18, but it's time to move on! The headlining change of this release is the targeting of Node LTS v20+ as the minimum Node runtime. Additional developer-centric quality-of-life changes have also been made in the name of streamlining use of SimpleWebAuthn on both the back end and front end.
This release is packed with updates, so buckle up! Refactor advice for breaking changes is, as always, offered below.
user.displayName
now defaults to an empty string if a value is not specified for
userDisplayName
when calling generateRegistrationOptions()
(#538)browserSupportsWebAuthnAutofill()
helper will no longer break in environments
in which PublicKeyCredential
is not present
(#557, with thanks to @clarafitzgerald)generateRegistrationOptions()
now expects Base64URLString
for excluded credential IDsgenerateAuthenticationOptions()
now expects Base64URLString
for allowed credential IDscredentialID
returned from response verification methods is now a Base64URLString
AuthenticatorDevice.credentialID
is now a Base64URLString
isoBase64URL.isBase64url()
is now called isoBase64URL.isBase64URL()
generateRegistrationOptions()
now accepts an optional Uint8Array
instead of a string
for
userID
isoBase64URL.toString()
and isoBase64URL.fromString()
have been renamedgenerateRegistrationOptions()
will now generate random user IDsuser.id
is now treated like a base64url string in startRegistration()
userHandle
is now treated like a base64url string in startAuthentication()
rpID
is now a required argument when calling generateAuthenticationOptions()
(#555)generateRegistrationOptions()
now expects Base64URLString
for excluded credential IDsThe isoBase64URL
helper can be used to massage Uint8Array
credential IDs into base64url strings:
Before
const opts = await generateRegistrationOptions({
// ...
excludeCredentials: devices.map((dev) => ({
id: dev.credentialID, // type: Uint8Array
type: 'public-key',
transports: dev.transports,
})),
});
After
import { isoBase64URL } from '@simplewebauthn/server/helpers';
const opts = await generateRegistrationOptions({
// ...
excludeCredentials: devices.map((dev) => ({
id: isoBase64URL.fromBuffer(dev.credentialID), // type: string
transports: dev.transports,
})),
});
The type
argument is no longer needed either.
generateAuthenticationOptions()
now expects Base64URLString
for allowed credential IDsSimilarly, the isoBase64URL
helper can also be used during auth to massage Uint8Array
credential
IDs into base64url strings:
Before
const opts = await generateAuthenticationOptions({
// ...
allowCredentials: devices.map((dev) => ({
id: dev.credentialID, // type: Uint8Array
type: 'public-key',
transports: dev.transports,
})),
});
After
import { isoBase64URL } from '@simplewebauthn/server/helpers';
const opts = await generateAuthenticationOptions({
// ...
allowCredentials: devices.map((dev) => ({
id: isoBase64URL.fromBuffer(dev.credentialID), // type: Base64URLString (a.k.a string)
transports: dev.transports,
})),
});
The type
argument is no longer needed either.
credentialID
returned from response verification methods is now a Base64URLString
It is no longer necessary to manually stringify credentialID
out of response verification methods:
Before
import { isoBase64URL } from '@simplewebauthn/server/helpers';
// Registration
const { verified, registrationInfo } = await verifyRegistrationResponse({ ... });
if (verified && registrationInfo) {
const { credentialID } = registrationInfo;
await storeInDatabase({ credIDString: isoBase64URL.fromBuffer(credentialID), ... });
}
// Authentication
const { verified, authenticationInfo } = await verifyAuthenticationResponse({ ... });
if (verified && authenticationInfo) {
const { newCounter, credentialID } = authenticationInfo;
dbAuthenticator.counter = authenticationInfo.newCounter;
await updateCounterInDatabase({
credIDString: isoBase64URL.fromBuffer(credentialID),
newCounter,
});
}
After
// Registration
const { verified, registrationInfo } = await verifyRegistrationResponse({ ... });
if (verified && registrationInfo) {
const { credentialID } = registrationInfo;
await storeInDatabase({ credIDString: credentialID, ... });
}
// Authentication
const { verified, authenticationInfo } = await verifyAuthenticationResponse({ ... });
if (verified && authenticationInfo) {
const { newCounter, credentialID } = authenticationInfo;
dbAuthenticator.counter = authenticationInfo.newCounter;
await updateCounterInDatabase({ credIDString: credentialID, newCounter });
}
Changelog
v9.0.0 - The one in which 11 characters were saved
@simplewebauthn/typescript-types
package has been renamed to
@simplewebauthn/types
(#508)@simplwebauthn/typescript-types
will need to be replaced with the new package
name @simplewebauthn/types
:Before:
import { ... } from '@simplwebauthn/typescript-types';
After:
$> npm uninstall @simplewebauthn/typescript-types
$> npm install -D @simplewebauthn/types
import { ... } from '@simplwebauthn/types';
Changelog
v8.3.7
WebAuthnError
class can now be imported from @simplewebauthn/browser
for
simpler error detection and handling when calling startRegistration()
and
startAuthentication()
(#505, with
thanks to @zoontek)COSEPublicKeyEC2
, COSEPublicKeyOKP
, and COSEPublicKeyRSA
types can now be
imported from @simplwebauthn/server/helpers
to help type possible return values from
decodeCredentialPublicKey()
(#504, with
thanks to @mmv08)generateRegistrationOptions()
will now be
treated as UTF-8 strings to align with the existing behavior of generateAuthenticationOptions()
(#507)