WebAuthn (Web only)
WebAuthn (Web only)
You can allow your users to sign up and log in to your web app with a FIDO2 device (YubiKey) or with biometrics (Touch ID).
WebAuthn is only supported on desktop, and will be supported on mobile devices soon.
Use a YubiKey or your finger to log in
π Try the demo
π View the demo's code
#Installation
WebAuthn works as an extension to Magic SDK. To add WebAuthn to your Magic integration, follow these steps to install the WebAuthn Extension:
- In your project, run
npm install magic-sdk @magic-ext/webauthn
- Create your Magic SDK instance with the OAuth extension:
import { Magic } from 'magic-sdk';
import { WebAuthnExtension } from '@magic-ext/webauthn';
const magic = new Magic('YOUR_API_KEY', {
extensions: [new WebAuthnExtension()],
});
#Methods
#RegisterNewUser
#Arguments
registerNewUser({username, nickname? = ββ})
Parameter | Type | Definition |
username | String | The username to register with. |
nickname? | String | The nickname of the WebAuthn device user wants to set. |
#Returns
PromiEvent<string | null>
: The promise resolves upon authentication request success and rejects with a specific error code if the request fails. The resolved value is a Decentralized ID token with a default 15-minute lifespan.
#Example
import { Magic } from 'magic-sdk';
import { WebAuthnExtension } from '@magic-ext/webauthn';
const magic = new Magic('YOUR API KEY', {
extensions: [new WebAuthnExtension()],
});
// register a user by their username
try {
const token = await magic.webauthn.registerNewUser({ username: 'username' });
} catch (e) {
// Handle errors if required!
}
// log in a user by their username and set webauthn device nickname.
try {
const token = await magic.webauthn.registerNewUser({ username: 'username', nickname: 'nickname' });
} catch (e) {
// Handle errors if required!
}
#Error
import { Magic, SDKErrorCode } from 'magic-sdk';
import { WebAuthnExtension } from '@magic-ext/webauthn';
const magic = new Magic('YOUR API KEY', {
extensions: [new WebAuthnExtension()],
});
try {
await magic.webauthn.registerNewUser({ username: 'username' });
} catch (err) {
if (err instanceof SDKErrorCode) {
switch (err.code) {
case SDKErrorCode.WebAuthnNotSupported:
case SDKErrorCode.WebAuthnCreateCredentialError:
// Handle errors accordingly :)
break;
}
}
}
#Login
#Arguments
login({username})
Parameter | Type | Definition |
username | String | The username to log in with. |
#Returns
PromiEvent<string | null>
: The promise resolves upon authentication request success and rejects with a specific error code if the request fails. The resolved value is a Decentralized ID token with a default 15-minute lifespan.
#Example
import { Magic } from 'magic-sdk';
import { WebAuthnExtension } from '@magic-ext/webauthn';
const magic = new Magic('YOUR API KEY', {
extensions: [new WebAuthnExtension()],
});
// login a user by their username
try {
const token = await magic.webauthn.login({ username: 'username' });
} catch (e) {
// Handle errors if required!
}
#Error
import { Magic, SDKErrorCode } from 'magic-sdk';
import { WebAuthnExtension } from '@magic-ext/webauthn';
const magic = new Magic('YOUR API KEY', {
extensions: [new WebAuthnExtension()],
});
try {
await magic.webauthn.login({ username: 'username' });
} catch (err) {
if (err instanceof SDKErrorCode) {
switch (err.code) {
case SDKErrorCode.WebAuthnNotSupported:
case SDKErrorCode.WebAuthnCreateCredentialError:
// Handle errors accordingly :)
break;
}
}
}
#GetMetadata
#Arguments
None
#Returns
PromiEvent<{ devicesInfo, username }>
: an object containing the WebAuthn devices information and username of the authenticated user.
Value | Type | Definition |
devicesInfo | Array | List of devices info contains device id, device nickname, transport, user agent |
username | String | Username of the authenticated user. |
#Example
import { Magic, SDKErrorCode } from 'magic-sdk';
import { WebAuthnExtension } from '@magic-ext/webauthn';
const magic = new Magic('YOUR API KEY', {
extensions: [new WebAuthnExtension()],
});
// Initiates the flow to get wenauthn metadata for current account.
try {
const metadata = await magic.webauthn.getMetadata();
/* webauthn metadata
{
"devicesInfo": [
{
"id": "EjI_EFJhB6cdCj6rHPRHUcFCn6NnywALuWjQyPe0_dI=",
"nickname": "",
"transport": "internal",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36"
}
],
"username": "username"
}
*/
} catch (e) {
// Handle errors if required!
}
#RegisterNewDevice
#Arguments
registerNewDevice(nickname? = ββ)
Parameter | Type | Definition |
nickname | String | The nickname of the WebAuthn device user wants to set. |
#Returns
PromiEvent<boolean>
: The promise resolves with a true boolean value if register webauthn device is successful and rejects with a specific error code if the request fails.
#Example
import { Magic, SDKErrorCode } from 'magic-sdk';
import { WebAuthnExtension } from '@magic-ext/webauthn';
const magic = new Magic('YOUR API KEY', {
extensions: [new WebAuthnExtension()],
});
// Initiates the flow to a new WebAuthn Device for current account.
try {
await magic.webauthn.registerNewDevice('new device nickname');
} catch (e) {
// Handle errors if required!
}
#Error
import { Magic, SDKErrorCode } from 'magic-sdk';
import { WebAuthnExtension } from '@magic-ext/webauthn';
const magic = new Magic('YOUR API KEY', {
extensions: [new WebAuthnExtension()],
});
try {
await magic.webauthn.registerNewDevice('new device nickname');
} catch (err) {
if (err instanceof SDKErrorCode) {
switch (err.code) {
case SDKErrorCode.WebAuthnNotSupported:
case SDKErrorCode.WebAuthnCreateCredentialError:
// Handle errors accordingly :)
break;
}
}
}
#UpdateInfo
#Arguments
updateInfo({id: βwebauthn info idβ,nickname: βubk})
Parameter | Type | Definition |
nickname | String | The nickname of the WebAuthn device user wants to set. |
id | String | The WebAuthn Id returned from getMetaData function's devicesInfo field. |
#Returns
PromiEvent<boolean>
: The promise resolves with a true boolean value if update webauthn device nickname is successful and rejects with a specific error code if the request fails.
#Example
import { Magic, SDKErrorCode } from 'magic-sdk';
import { WebAuthnExtension } from '@magic-ext/webauthn';
const magic = new Magic('YOUR API KEY', {
extensions: [new WebAuthnExtension()],
});
// Initiates the flow to update WebAuthn Device's nickname.
try {
await magic.webauthn.updateInfo({ id, nickname });
} catch (e) {
// Handle errors if required!
}
#UnregisterWebAuthnDevice
#Arguments
unregisterWebAuthnDevice(id: 'webauthn info id')
Parameter | Type | Definition |
id | String | The WebAuthn Id returned from getMetaData function's devicesInfo field. |
#Returns
PromiEvent<boolean>
: The promise resolves with a true boolean value if unregister webauthn device is successful and rejects with a specific error code if the request fails.
#Example
import { Magic, SDKErrorCode } from 'magic-sdk';
import { WebAuthnExtension } from '@magic-ext/webauthn';
const magic = new Magic('YOUR API KEY', {
extensions: [new WebAuthnExtension()],
});
// Initiates the flow to unregister WebAuthn Device.
try {
/* Assuming user is logged in */
await magic.webauthn.unregisterDevice(id);
} catch (e) {
// Handle errors if required!
}