Getting started
This page guides you through downloading, including, and initializing the FIDO2 Web SDK in your web application.
Prerequisites
Before you begin:
- Access to the IDCloud FIDO2 Server — see the FIDO authentication APIs for server-side requirements.
- A Relying Party backend application capable of proxying requests to and from the FIDO2 Server.
- A web server serving your application over HTTPS (or
http://localhostfor development). - A modern browser with WebAuthn, IndexedDB, and Web Crypto API support — see Browser compatibility.
Step 1: Download the bundle
Download the SDK bundle file idc-fido2-web-js-lib-bundle.js from the official distribution page (link to be provided). Host it on your own CDN or web server for production deployments.
Self-hosting the bundle gives you:
- Full control over availability and version pinning
- Reduced external dependencies
- Better performance and rollback capabilities
Step 2: Include the bundle in your HTML
Include the SDK bundle before any application scripts that use it.
<!DOCTYPE html>
<html>
<head>
<title>My FIDO2 Application</title>
</head>
<body>
<!-- Your application content -->
<!-- Include FIDO2 Web SDK bundle -->
<script src="https://your-cdn.com/idc-fido2-web-js-lib-bundle.js"></script>
<!-- Your application scripts (must appear after the SDK) -->
<script src="your-app.js"></script>
</body>
</html>
If you use the defer attribute, ensure your application script also uses defer and appears after the SDK script tag:
<script src="https://your-cdn.com/idc-fido2-web-js-lib-bundle.js" defer></script>
<script defer>
window.addEventListener('load', async () => {
if (!window.com$thalesgroup$gemalto$fido2$web) {
console.error('SDK not loaded');
return;
}
const initSdk = window.com$thalesgroup$gemalto$fido2$web.initSdk;
await initSdk();
});
</script>
Step 3: Verify the SDK loaded
After including the bundle, verify it is available under the global namespace:
if (!window.com$thalesgroup$gemalto$fido2$web) {
throw new Error('FIDO2 Web SDK not loaded. Check the script src URL and network errors.');
}
console.log('SDK functions:', Object.keys(window.com$thalesgroup$gemalto$fido2$web));
// Expected: ["initSdk", "getDeviceBoundKeyId", "webauthnCreateCred", "webauthnGetCred", "registerDeviceBoundCredential"]
Step 4: Initialize the SDK
Call initSdk() on page load, before any other SDK operations:
const initSdk = window.com$thalesgroup$gemalto$fido2$web.initSdk;
window.addEventListener('load', async () => {
try {
await initSdk();
console.log('FIDO2 Web SDK initialized successfully');
} catch (error) {
console.error('SDK initialization failed:', error.message);
// Disable FIDO2 features or show an appropriate message to the user
}
});
Initialization performs the following actions:
- Determines the Relying Party ID (
rpId) fromlocation.hostname - Creates an HMAC-SHA256 seed for Device Bound Key operations
- Stores the seed securely in IndexedDB (skipped if already present)
Note
initSdk() is safe to call multiple times. Subsequent calls have no effect if the SDK is already initialized.
Warning
When the browser is in incognito or private browsing mode, IndexedDB data is cleared at the end of the session. This means the HMAC seed is regenerated on each new incognito session, resulting in different Device Bound Key identifiers for the same user across sessions.
Global namespace
All SDK functions are available under the global namespace:
window.com$thalesgroup$gemalto$fido2$web
Public functions:
| Function | Description |
|---|---|
initSdk() |
Initialize Device Bound Key support |
getDeviceBoundKeyId(userIdBase64Url) |
Derive a device-bound key identifier |
webauthnCreateCred({options, abortSignal}) |
Create a credential (registration/attestation) |
webauthnGetCred({mediationRequirement, options, abortSignal, userIdB64Url}) |
Authenticate with an existing credential (assertion) |
registerDeviceBoundCredential({assertionReq, attestationReq, onFallbackConfirmation}) |
Register a Device Bound credential using the auto-binding pattern |
HTTPS requirement
WebAuthn requires a secure context. The following origins are accepted:
https://example.com— standard HTTPShttp://localhost— development onlyhttp://127.0.0.1— development only
HTTP origins other than localhost are not accepted by the browser WebAuthn API.
Common patterns
Initialize once, reuse throughout the page
let sdkInitialized = false;
async function ensureSdkReady() {
if (!sdkInitialized) {
const initSdk = window.com$thalesgroup$gemalto$fido2$web.initSdk;
await initSdk();
sdkInitialized = true;
}
}
async function registerUser() {
await ensureSdkReady();
// Proceed with registration
}
async function authenticateUser() {
await ensureSdkReady();
// Proceed with authentication
}
Load the bundle dynamically
Use dynamic loading when you cannot add a <script> tag to HTML directly:
function loadScript(src) {
return new Promise((resolve, reject) => {
const script = document.createElement('script');
script.src = src;
script.onload = resolve;
script.onerror = () => reject(new Error('Failed to load ' + src));
document.head.appendChild(script);
});
}
(async () => {
await loadScript('https://your-cdn.com/idc-fido2-web-js-lib-bundle.js');
const initSdk = window.com$thalesgroup$gemalto$fido2$web.initSdk;
await initSdk();
console.log('SDK loaded and initialized');
})();
Next steps
- API reference: Complete function documentation with parameters, return types, and examples
- Integration guide: End-to-end integration examples including backend implementation
- Error handling: Error categories and handling strategies
