Comply with FDA Device Security Requirements

Jamie Orlando — Mon, 15 Apr 2024 00:00:00 +0000

Introduction</h2>
On September 27, 2023, the Food and Drug Administration (FDA) finalized it's cybersecurity guidance for medical devices titled, Cybersecurity in Medical Devices: Quality System Considerations and Content of Premarket Submissions (link</a>). Medical devices under review for FDA clearance use the published guidance as a framework to demonstrate that effective policies and processes will be in place to maintain security throughout the devices product lifecycle. The following table is intended to help organizations trace their own internal practices to the controls defined by the FDA.

Table of Controls</h2>
The following table maps all current FDA cybersecurity documents and the controls they require.
ID</th> Category</th> FDA Requirement</th> Regulatory Mapping</th></tr></thead>

1</td> Authentication</td> Avoid the use of implicit authentication mechanisms (ie. trusted IP addresses and handshakes that do not rely on cryptographic secrets).</td> US FDA 2023 - Premarket</td></tr>
2</td> Authentication</td> Use cryptographic authentication protocols</td> US FDA 2023 - Premarket</td></tr>
3</td> Authentication</td> Use cryptographically strong authentication, where the authentication functionality resides on the device, to authenticate personnel, messages, commands updates, and as applicable, all other communication pathways. Hardware-based security solutions should be considered and employed when possible</td> US FDA 2023 - Premarket</td></tr>
4</td> Authentication</td> Authenticate external connections at a frequency commensurate with the associated risks. For example, if a device connects to an offsite server, then the device and the server should mutually authenticate each session and limit the duration of the session, even if the connection is initiated over one or more existing trusted channels.</td> US FDA 2023 - Premarket</td></tr>
5</td> Authentication</td> Use appropriate user authentication (e.g., multi-factor authentication to permit privileged device access to system administrators, service technicians, or maintenance personnel, among others, as needed)</td> US FDA 2023 - Premarket</td></tr>
6</td> Authentication</td> Require authentication, and authorization in certain instances, before permitting software or firmware updates, including those updates affecting the operating system, applications, and anti-malware functionality</td> US FDA 2023 - Premarket</td></tr>
7</td> Authentication</td> Strengthen password protections. Do not use passwords that are hardcoded, default, easily guessed, or easily compromised (e.g., passwords that are the same for each device; unchangeable; can persist as default; difficult to change; and/or vulnerable to public disclosure)</td> US FDA 2023 - Premarket</td></tr>
8</td> Authentication</td> Implement anti-replay measures in critical communications such as potentially harmful commands. This can be accomplished with the use of several methods including the use of cryptographic nonces (an arbitrary number used only once in a cryptographic communication)</td> US FDA 2023 - Premarket</td></tr>
9</td> Authentication</td> Provide mechanisms for verifying the authenticity of information originating from the device, such as telemetry. This is especially important for data that, if spoofed or otherwise modified, could result in patient harm, such as the link between a clinician programmer or monitoring device and an implanted device like a pacemaker, defibrillator, or neurostimulator; or the link between a continuous glucose monitor system and an automated insulin pump</td> US FDA 2023 - Premarket</td></tr>
10</td> Authentication</td> Do not rely on cyclic redundancy checks (CRCs) as security controls. CRCs do not provide integrity or authentication protections in a security environment. While CRCs are an error detecting code and provide integrity protection against environmental factors (e.g., noise or EMC), they do not provide protections against an intentional or malicious actor</td> US FDA 2023 - Premarket</td></tr>
11</td> Authentication</td> Consider how the device and/or system should respond in event of authentication failure(s)</td> US FDA 2023 - Premarket</td></tr>
12</td> Authorization</td> Limit authorized access to devices through the authentication of users (e.g., user ID and password, smartcard, biometric, certificates, or other appropriate authentication method)</td> US FDA 2023 - Premarket</td></tr>
13</td> Authorization</td> Use automatic timed methods to terminate sessions within the medical device system where appropriate for the use environment</td> US FDA 2023 - Premarket</td></tr>
14</td> Authorization</td> Employ an authorization model that incorporates the principle of least privileges by differentiating privileges based on the user role (e.g., caregiver, patient, healthcare provider, system administrator) or device functions</td> US FDA 2023 - Premarket</td></tr>
15</td> Authorization</td> Design devices to “deny by default” (i.e., that which is not expressly permitted by a device is denied by default). For example, the device should generally reject all unauthorized connections (e.g., incoming TCP, USB, Bluetooth, serial connections). Ignoring requests is one form of denying authorization.</td> US FDA 2023 - Premarket</td></tr>
16</td> Cryptography</td> Select industry-standard cryptographic algorithms and protocols, and select appropriate key generation, distribution, management and protection, as well as robust nonce mechanisms.</td> US FDA 2023 - Premarket</td></tr>
17</td> Cryptography</td> Use current NIST recommended standards for cryptography (e.g., FIPS 140-3, NIST Suite B), or equivalent-strength cryptographic protection that are expected to be considered cryptographically strong throughout the service life of the device. Manufacturers should not implement cryptographic algorithms that have been deprecated or disallowed in applicable standards or best practices (e.g., NIST SP 800-131A, Transitioning the Use of Cryptographic Algorithms and Key Lengths). Implementation of algorithms with a status of “legacy use” should be discussed with FDA during a pre-submission meeting</td> US FDA 2023 - Premarket</td></tr>
18</td> Cryptography</td> Design a system architecture and implement security controls to prevent a situation where the full compromise of any single device can result in the ability to reveal keys for other devices. For example, avoid using master-keys stored on device, or key derivation algorithms based solely on device identifiers or other readily discoverable information.</td> US FDA 2023 - Premarket</td></tr>
19</td> Cryptography</td> Implement cryptographic protocols that permit negotiated parameters/versions such that the most recent, secure configurations are used, unless otherwise necessary</td> US FDA 2023 - Premarket</td></tr>
20</td> Cryptography</td> Do not allow downgrades, or version rollbacks, unless absolutely necessary for safety reasons, and log and document the event. Downgrades can allow attackers to exploit prior, less protected versions and should be avoided</td> US FDA 2023 - Premarket</td></tr>
21</td> Code, Data, and Execution Integrity</td> Hardware-based security solutions should be considered and employed when possible</td> US FDA 2023 - Premarket</td></tr>
22</td> Code, Data, and Execution Integrity</td> Authenticate firmware and software. Verify authentication tags (e.g., signatures, message authentication codes (MACs)) of software/firmware content, version numbers, and other metadata. The version numbers intended to be installed should themselves be signed or have MACs. Devices should be electronically and visibly identifiable (e.g., Unique device identifier (UDI), model number, serial number);</td> US FDA 2023 - Premarket</td></tr>
23</td> Code, Data, and Execution Integrity</td> Allow installation of cryptographically authenticated firmware and software updates, and do not allow installation where such cryptographic authentication either is absent or fails</td> US FDA 2023 - Premarket</td></tr>
24</td> Code, Data, and Execution Integrity</td> Ensure that all software and firmware on the device is protected from unauthorized access, modification, and deletion, regardless of whether the software and firmware resides within a virtual private network (VPN) or on the cloud. Maintain all software and firmware in a secure environment and perform routine security updates. Encrypt all software updates prior to transmission.</td> US FDA 2023 - Premarket</td></tr>
25</td> Code, Data, and Execution Integrity</td> Ensure that all software/firmware changes are tracked and that the appropriate personnel review and approve these changes prior to implementation. Software or firmware changes that are not approved should not be allowed to execute. A cryptographic mechanism such as digital signatures should be used to ensure software/firmware integrity (e.g., during updates or during execution) and to confirm that the software/firmware originates from a known source, is up-to-date, and has not been tampered with</td> US FDA 2023 - Premarket</td></tr>
26</td> Code, Data, and Execution Integrity</td> Provide secure coding guidance to developers (e.g., guidance from the FDA, NIST, ISO, IEEE, etc.) and encourage compliance with industry-recognized secure coding standards. Review the software design and coding process for security vulnerabilities, especially those resulting from faulty design, implementation, or integration</td> US FDA 2023 - Premarket</td></tr>
27</td> Code, Data, and Execution Integrity</td> Implement and maintain secure software development lifecycle practices throughout the entire lifecycle of the device (e.g., requirements definition, design, implementation, verification, maintenance, and retirement)</td> US FDA 2023 - Premarket</td></tr>
28</td> Code, Data, and Execution Integrity</td> Incorporate security features into the design of the device, such as data execution prevention (DEP), address space layout randomization (ASLR), and stack overflow protections. These protections are intended to mitigate the risk of common software security vulnerabilities.</td> US FDA 2023 - Premarket</td></tr>
29</td> Code, Data, and Execution Integrity</td> Use hardware features designed to support security in depth, such as trusted platform modules (TPMs), secure enclaves, and hardware root of trust</td> US FDA 2023 - Premarket</td></tr>
30</td> Code, Data, and Execution Integrity</td> Design and implement software/firmware updates to be secure by design. Ensure that updates can be verified for integrity, that they are resistant to man-in-the-middle attacks, and that updates are obtained from an authenticated source. Consider using secure boot mechanisms and encrypted channels for secure software/firmware updates</td> US FDA 2023 - Premarket</td></tr>
31</td> Code, Data, and Execution Integrity</td> Implement runtime integrity protections to detect and prevent unauthorized changes to critical files, settings, and configurations. For example, deploy integrity monitoring solutions that can detect unauthorized changes to files, registry settings, and configuration parameters, and generate alerts or take other appropriate actions (e.g., halt, notify administrator)</td> US FDA 2023 - Premarket</td></tr>
32</td> Code, Data, and Execution Integrity</td> Employ controls to protect against rollback of software/firmware updates to a less secure version. For example, use cryptographic hashes or signatures to ensure that software/firmware updates have not been tampered with and that only signed updates are accepted and applied</td> US FDA 2023 - Premarket</td></tr>
33</td> Code, Data, and Execution Integrity</td> Implement measures to mitigate the risk of supply chain compromises, including tamper-evident packaging, supply chain visibility, and vetting of suppliers</td> US FDA 2023 - Premarket</td></tr>
34</td> Code, Data, and Execution Integrity</td> Ensure that all components, including open source and third-party software, are kept up-to-date with the latest security patches and updates. Establish a process for monitoring and applying patches and updates in a timely manner</td> US FDA 2023 - Premarket</td></tr>
35</td> Code, Data, and Execution Integrity</td> Ensure that code, data, and execution integrity mechanisms function properly throughout the lifecycle of the device. Test these mechanisms during design verification, validation, and during routine maintenance</td> US FDA 2023 - Premarket</td></tr>
36</td> Code, Data, and Execution Integrity</td> Develop a response plan for addressing vulnerabilities discovered post-market and take appropriate corrective actions to mitigate risk, which may include software patches, firmware updates, or other remediation measures. Ensure that post-market vulnerability assessments and remediation efforts follow a risk-based approach</td> US FDA 2023 - Premarket</td></tr>
37</td> Confidentiality</td> Ensure that sensitive data is encrypted both in transit and at rest using industry-standard encryption algorithms (e.g., AES, RSA, ECC) and appropriate key management practices</td> US FDA 2023 - Premarket</td></tr>
38</td> Confidentiality</td> Protect the confidentiality of sensitive data (e.g., patient information, device configurations, system logs) through access controls, encryption, and other appropriate means. Limit access to sensitive data to only those users and systems that require it for legitimate purposes</td> US FDA 2023 - Premarket</td></tr>
39</td> Confidentiality</td> Implement logging mechanisms to record access to sensitive data, security-related events, and other relevant activities. Ensure that logs are protected from unauthorized access, tampering, and deletion. Periodically review and analyze logs for indications of security incidents, unauthorized access, or other anomalies</td> US FDA 2023 - Premarket</td></tr>
40</td> Confidentiality</td> Provide a mechanism to allow authorized users (e.g., system administrators, healthcare providers) to access audit logs for review and analysis. Ensure that audit logs capture key security events (e.g., logins, failed login attempts, privilege changes, configuration changes, critical system events)</td> US FDA 2023 - Premarket</td></tr>
41</td> Confidentiality</td> Limit the collection, storage, and transmission of personally identifiable information (PII) and other sensitive data to only what is necessary for the intended purpose of the device. Encrypt any stored or transmitted PII or sensitive data</td> US FDA 2023 - Premarket</td></tr>
42</td> Confidentiality</td> Implement appropriate access controls and authorization mechanisms to prevent unauthorized access to sensitive data. Enforce the principle of least privilege by granting users only the access necessary to perform their authorized functions</td> US FDA 2023 - Premarket</td></tr>
43</td> Confidentiality</td> Encrypt communication channels to prevent eavesdropping, tampering, and other unauthorized access. Use secure protocols (e.g., TLS) and strong cryptographic algorithms to protect data in transit</td> US FDA 2023 - Premarket</td></tr>
44</td> Confidentiality</td> Protect sensitive data (e.g., PHI, PII) stored in the cloud by implementing appropriate security controls (e.g., encryption, access controls, data masking)</td> US FDA 2023 - Premarket</td></tr>
45</td> Confidentiality</td> Ensure that cloud service providers (CSPs) comply with applicable security and privacy regulations (e.g., HIPAA, GDPR) and provide assurances of compliance through contractual agreements, certifications, and third-party audits</td> US FDA 2023 - Premarket</td></tr>
46</td> Integrity</td> Use digital signatures, message authentication codes (MACs), or other cryptographic mechanisms to ensure the integrity of transmitted data, including commands, configuration data, and updates</td> US FDA 2023 - Premarket</td></tr>
47</td> Integrity</td> Protect against unauthorized modification of critical configuration settings, parameters, and other data that could affect the safety, effectiveness, or performance of the device. This includes preventing unauthorized changes to software, firmware, and hardware configurations</td> US FDA 2023 - Premarket</td></tr>
48</td> Integrity</td> Validate input data to ensure that it is well-formed, valid, and within acceptable ranges. Implement input validation controls to prevent buffer overflows, SQL injection, cross-site scripting (XSS), and other common attack vectors</td> US FDA 2023 - Premarket</td></tr>
49</td> Integrity</td> Employ integrity checks and checksums to detect unauthorized changes to firmware, software, and critical data. Perform regular integrity checks during operation and upon startup to ensure that the device has not been tampered with or compromised</td> US FDA 2023 - Premarket</td></tr>
50</td> Integrity</td> Implement controls to ensure the integrity of critical processes, including those related to device operation, data handling, and system configuration. These controls should prevent unauthorized access, tampering, and other forms of interference</td> US FDA 2023 - Premarket</td></tr>
51</td> Integrity</td> Use secure boot mechanisms to ensure that only trusted and authenticated firmware/software is loaded and executed on the device. Validate the integrity of firmware/software during the boot process and refuse to boot if the integrity checks fail</td> US FDA 2023 - Premarket</td></tr>
52</td> Integrity</td> Use hardware features such as secure boot, secure enclave, and hardware root of trust to protect against unauthorized modifications to firmware and critical system components</td> US FDA 2023 - Premarket</td></tr>
53</td> Integrity</td> Employ runtime integrity protections to detect and prevent unauthorized changes to critical files, settings, and configurations. Implement integrity monitoring solutions that can detect and respond to unauthorized changes in real-time</td> US FDA 2023 - Premarket</td></tr>
54</td> Integrity</td> Use cryptographic mechanisms to ensure the integrity of data stored in non-volatile memory (e.g., flash memory, EEPROM). Implement protections to prevent unauthorized modifications to stored data, including encryption, digital signatures, and access controls</td> US FDA 2023 - Premarket</td></tr>
55</td> Non-repudiation</td> Implement mechanisms to ensure the integrity and authenticity of data generated by the device, such as timestamps, digital signatures, and cryptographic hashes. These mechanisms should be used to provide non-repudiation, ensuring that the origin and integrity of data can be verified and attributed to specific sources</td> US FDA 2023 - Premarket</td></tr>
56</td> Non-repudiation</td> Ensure that audit logs and other records of device activity are tamper-evident and resistant to modification. Use cryptographic techniques to protect the integrity of logs and to provide evidence of tampering or unauthorized access</td> US FDA 2023 - Premarket</td></tr>
57</td> Non-repudiation</td> Implement controls to prevent the deletion, alteration, or tampering of audit logs and other records of device activity. Log entries should be time-stamped, and changes to logs should be logged and reviewed</td> US FDA 2023 - Premarket</td></tr>
58</td> Non-repudiation</td> Ensure that audit logs capture key security events (e.g., logins, failed login attempts, privilege changes, configuration changes, critical system events). Implement mechanisms to detect and respond to suspicious or anomalous behavior</td> US FDA 2023 - Premarket</td></tr>
59</td> Non-repudiation</td> Provide a mechanism for authorized users (e.g., system administrators, healthcare providers) to review and analyze audit logs. Implement access controls to restrict access to audit logs to authorized personnel</td> US FDA 2023 - Premarket</td></tr>
60</td> Non-repudiation</td> Use cryptographic techniques to provide non-repudiation for device commands and actions. Digital signatures and other cryptographic mechanisms should be used to ensure that commands and actions can be attributed to specific users or entities</td> US FDA 2023 - Premarket</td></tr>
61</td> Resilience</td> Implement resilience measures to ensure continued device functionality in the event of component failures, network interruptions, or other adverse conditions. This may include redundancy, failover mechanisms, and graceful degradation of non-essential services</td> US FDA 2023 - Premarket</td></tr>
62</td> Resilience</td> Design devices to recover gracefully from unexpected faults, errors, and exceptions. Implement error handling and recovery mechanisms to mitigate the impact of software bugs, hardware failures, and other faults</td> US FDA 2023 - Premarket</td></tr>
63</td> Resilience</td> Ensure that critical device functions (e.g., therapeutic delivery, patient monitoring) continue to operate correctly in the event of software or firmware failures. Implement safety-critical software in accordance with relevant standards (e.g., IEC 62304, ISO 14971) and perform thorough testing to validate safety and reliability</td> US FDA 2023 - Premarket</td></tr>
64</td> Resilience</td> Implement robust error detection and correction mechanisms to prevent or mitigate data corruption, transmission errors, and other forms of data loss or degradation. Use error checking and correction (ECC) codes, checksums, and other techniques to detect and correct errors in data transmission and storage</td> US FDA 2023 - Premarket</td></tr>
65</td> Resilience</td> Use redundant and diverse communication pathways (e.g., wired, wireless, cellular) to ensure continued connectivity in the event of network failures or disruptions. Implement failover mechanisms to automatically switch to alternate communication channels if primary channels become unavailable</td> US FDA 2023 - Premarket</td></tr>
66</td> Resilience</td> Employ backup and recovery mechanisms to protect against data loss and corruption. Regularly backup critical data and configurations, and test backup and recovery procedures to ensure their effectiveness. Store backups in a secure location, separate from the primary data storage, to prevent loss due to disasters or other catastrophic events</td> US FDA 2023 - Premarket</td></tr>
67</td> Resilience</td> Implement mechanisms to detect and respond to abnormal system behavior, such as resource exhaustion, memory leaks, and process crashes. Use monitoring tools and diagnostic capabilities to identify and troubleshoot issues before they impact device functionality</td> US FDA 2023 - Premarket</td></tr>
68</td> Resilience</td> Design devices to be modular and easily upgradeable to accommodate future enhancements and changes. Implement hot-swappable components and interfaces to minimize downtime during maintenance and upgrades</td> US FDA 2023 - Premarket</td></tr>
69</td> Resilience</td> Conduct thorough risk assessments and hazard analyses to identify potential failure modes, their impact on device performance, and mitigation strategies. Use failure mode and effects analysis (FMEA) and other risk management techniques to prioritize risks and develop resilience measures</td> US FDA 2023 - Premarket</td></tr>
70</td> Resilience</td> Establish a robust incident response plan to address security breaches, device failures, and other adverse events. Define roles and responsibilities, escalation procedures, and communication protocols for responding to incidents in a timely and effective manner</td> US FDA 2023 - Premarket</td></tr>
71</td> Transparency and Traceability</td> Provide transparent and accurate information about device security features, capabilities, and limitations to users, healthcare providers, regulators, and other stakeholders. Include security-related information in user manuals, labeling, and other documentation provided with the device</td> US FDA 2023 - Premarket</td></tr>
72</td> Transparency and Traceability</td> Maintain records of security-related activities, including security testing, vulnerability assessments, and remediation efforts. Keep documentation of security controls, configurations, and security incidents for auditing and regulatory purposes</td> US FDA 2023 - Premarket</td></tr>
73</td> Transparency and Traceability</td> Engage in proactive communication with customers and stakeholders regarding security vulnerabilities, patches, updates, and other security-related information. Establish channels for reporting security incidents, vulnerabilities, and concerns, and respond to reports in a timely and transparent manner</td> US FDA 2023 - Premarket</td></tr>
74</td> Transparency and Traceability</td> Provide clear and concise security advisories and alerts to inform users and administrators about security vulnerabilities, patches, updates, and other relevant information. Make security advisories readily accessible through multiple channels (e.g., websites, email notifications, social media)</td> US FDA 2023 - Premarket</td></tr>
75</td> Transparency and Traceability</td> Maintain a comprehensive inventory of all software and hardware components used in the device, including third-party libraries and dependencies. Keep records of version numbers, patch levels, and other relevant information to facilitate vulnerability management and risk assessment</td> US FDA 2023 - Premarket</td></tr>
76</td> Transparency and Traceability</td> Collaborate with regulators, industry groups, and other stakeholders to share information and best practices for medical device security. Participate in working groups, standards development organizations, and other forums to contribute to the advancement of medical device cybersecurity</td> US FDA 2023 - Premarket</td></tr>
77</td> Transparency and Traceability</td> Maintain accurate and up-to-date documentation for the device, including design specifications, security architecture, threat models, risk assessments, and security testing reports. Make documentation available to authorized users, regulators, and other stakeholders upon request</td> US FDA 2023 - Premarket</td></tr>
78</td> Transparency and Traceability</td> Provide mechanisms for reporting security vulnerabilities and concerns to the manufacturer, regulatory authorities, and other relevant organizations. Establish clear channels for receiving and triaging reports, and respond to reports in a timely and responsible manner</td> US FDA 2023 - Premarket</td></tr>
79</td> Transparency and Traceability</td> Implement procedures for reviewing and assessing third-party products and services used in the development and operation of the device. Evaluate the security posture of third-party vendors and conduct due diligence to ensure that they meet security requirements and standards</td> US FDA 2023 - Premarket</td></tr>
80</td> Transparency and Traceability</td> Conduct regular security assessments and audits to evaluate the effectiveness of security controls, identify vulnerabilities, and validate compliance with security requirements and standards. Use the results of assessments to improve security posture and mitigate risks</td> US FDA 2023 - Premarket</td></tr>
81</td> Usability</td> Design devices to be intuitive and easy to use, with clear and consistent user interfaces. Incorporate human factors engineering principles to optimize usability and minimize user errors</td> US FDA 2023 - Premarket</td></tr>
82</td> Usability</td> Provide user training and education to ensure that users understand how to operate the device safely and securely. Develop user manuals, training materials, and other educational resources to support users in learning and using the device effectively</td> US FDA 2023 - Premarket</td></tr>
83</td> Usability</td> Implement access controls and authorization mechanisms that balance security requirements with usability. Ensure that users can access the functions and information they need to perform their tasks without unnecessary barriers or impediments</td> US FDA 2023 - Premarket</td></tr>
84</td> Usability</td> Use clear and informative error messages to communicate with users in the event of errors, warnings, or other system events. Provide guidance on how to resolve issues and take appropriate actions</td> US FDA 2023 - Premarket</td></tr>
85</td> Usability</td> Incorporate feedback mechanisms to gather input from users and stakeholders about device usability, performance, and security. Use feedback to identify areas for improvement and inform future iterations of the device</td> US FDA 2023 - Premarket</td></tr> </tbody></table>

Implement SSO With Keycloak

Jamie Orlando — Thu, 15 Feb 2024 00:00:00 +0000

Introduction</h2>
Authentication is hard. The selection pressure from Cheeto finger basement hackers, sophisticated criminal organizations, and everyone in-between has led to the development of new ideas and standards in web security in recent years. Among these developments are two similarly named standards, OATH</a> and OAUTH</a>. OATH is an open standard for Authentication (AuthN), while OAUTH is a standard for Authorization (AuthZ). AuthN is the process of proving a principal is who they say they are and AuthZ is the process of checking if a principal is allowed to perform the operation they are asking to perform. AuthN and AuthZ, together with Accounting (the appropriate logging of AuthN and AuthZ actions), make up the 3 dimensions of the AAA</a> security model.
The focus of this post is to demonstrate how to use the open source Keycloak SSO</a> to implement OATH compliant authentication (AuthN) login flows for a SaaS application using the OpenID Connect (OIDC) protocol. This architecture simplifies identity claims for developers by allowing them to offload AuthN to a hardened service and focus on consuming and validating JWT bearer tokens from the trusted identity service. Additionally, it simplifies operational burden on application users by allowing them to use one identity and credential across many related services. Lastly, for fun, we will configure the realm to only support login with passkeys!
Passkeys?</h2>
Passkeys are a modern attempt to replace passwords using an app specific cryptographic key pair that is managed for the user by a platform authenticator. Platform authenticators are passkey API aware password managers that help users automatically set strong, unique credentials for every application while also validating the web app through a process called origin verification. These mutliple touch points allow us to consider passkeys as MFA compliant credentials for compliance standards such as SOC 2, HISTRUST, and ISO 2700x.
Install Keycloak</h2>
The Keycloak Documentation</a> describes the Keycloak installation process for many different platforms. I generally run services in container based environments, so I follow the docker/podman instructions. Ultimately, the underlying platform does not matter, as the important configurations are done within a Keycloak realm.
podman run --name keycloak -p 8080:8080 --replace \ -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \ quay.io/keycloak/keycloak:24.0.1 \ start-dev </code></pre> Create a Realm</h2> Realms are the main subdivision of user pools in Keycloak. Often, a realm will be dedicated per client company in a multi-tenant hosting scenario or per logical app in an app factory scenario. This example uses the realm name, sso.example.com</code>. Most user facing apps want some flavor of the following settings applied. You will also want to ensure that both user and admin events are being saved. For this example, I want to configure an SMTP connection to simulate a real workflow without passwords. 
Configure Authenticators for the Realm</h2> Keycloak is designed to support a handful of different authentication types. Tradtitional architectures are built on top of passwords and OTP MFA devices. In this example, we will disable passwords and OTP authenticators, and only allow login with Passkeys (WebAuthn Passwordless). Configure passkey flow for the Realm</h2> Keycloak authentication flows give administrators flexibilitiy in providing different authentication mechanisms to end users. We will copy the default browser flow which contains the vanilla username and password form and we replace it with a passkey login. Name it the passkey-browser flow or something else that makes sense to you. The order of these authenticators defines the login process workflow. We leave the cookie authenticator, as that allows users to maintain sessions to keycloak. We remove the Kerberos login because we don't like Windows systems flinging credentials around. We allow the Identity Provider Redirect to allow login from upstream providers like Google, Okta, or another Keycloak instance. The next row starts to define the actual form. By default, the browser form supports login with a username, password, and MFA if configured. We delete everthing in that section and add a new step to add a WebAuthn Passwordless Authenticator. The eventual flow should look similar to the following. When you are done, you need to bind the authenticator to the browser login flow. Create a Test User</h2> Now that we have a realm configured, we should create a user to test with. This user should be registered to an email address you control. Navigate to the new user, go to the Credentials tab, and then click to start a Credential Reset. Set the reset action to Webauthn Register Passwordless and send the email. When the email arrives, click the magic link to register the user's passkey. Keycloak will show a dialog instructing the user to register their passkey, Click to register the passkey. Your devices platform authenticator will pop up. This example is on Fedora, so we use the 1password browser extension for passkey support. Set a name for the newly registered passkey. A window will confirm that the account was successfully updated! Test the Passkey</h2> Test the passkey by finding the login link under the SSO clients menu and opening it in a new browser. Keycloak will present the login page with a Sign in with Passkey button. Your platform authenticator should pop up offering to use the registered passkey. We are then successfully authenticated into Keycloak. We can reconfirm the user only has a passkey configured as a credential. Create an OIDC client</h2> Now we want to integrate Keyclaok with our web app. Navigate to clients and create a client for the example web application. set a client name and other information. Disable the Direct access grant flow and ensure the client is public. Set valid redirect_uris. My example webapp will run at http://loclhost:8000/keycloak-example-login.html</code> so I set the valid redirect links to be relative to that. Deploy the web app</h2> My webapp code in HTML looks like the following. <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Login with Keycloak</title> </head> <body> <h1>Login with Keycloak</h1> <button onclick="login()">Login with Keycloak</button> <div id="emailDisplay" style="display: none;"> <p>Email: <span id="email"></span></p> </div> <script src="https://cdn.jsdelivr.net/npm/keycloak-js@24.0.2/dist/keycloak.min.js"></script> <script> function login() { // Define Keycloak configuration URL const keycloakConfigUrl = "http://localhost:8080/realms/sso.example.com/.well-known/openid-configuration"; // Fetch Keycloak configuration fetch(keycloakConfigUrl) .then((response) => { if (!response.ok) { throw new Error("Network response was not ok"); } return response.json(); }) .then((config) => { // Construct login URL with email scope const loginUrl = config.authorization_endpoint + "?client_id=example-web-app" + "&redirect_uri=http://localhost:8000/keycloak-example-login.html" + "&response_type=code" + // Request authorization code "&scope=openid"; // Include openid scope // Redirect to Keycloak login page window.location.href = loginUrl; }) .catch((error) => { console.error("Error fetching Keycloak configuration:", error); }); } function displayEmail(email) { document.getElementById("email").innerText = email; document.getElementById("emailDisplay").style.display = "block"; } // Function to parse and display email from JWT function parseAndDisplayEmail(token) { const decodedToken = JSON.parse(atob(token.split(".")[1])); const email = decodedToken.email; displayEmail(email); } // Function to store tokens in session storage function storeTokens(tokens) { sessionStorage.setItem("access_token", tokens.access_token); sessionStorage.setItem("id_token", tokens.id_token); // Optionally store refresh token if available if (tokens.refresh_token) { sessionStorage.setItem("refresh_token", tokens.refresh_token); } } // Check if the URL contains a code parameter const urlParams = new URLSearchParams(window.location.search); if (urlParams.has("code")) { const code = urlParams.get("code"); // Once the code is received, exchange it for tokens fetch( "http://localhost:8080/realms/sso.example.com/protocol/openid-connect/token", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded", }, body: new URLSearchParams({ grant_type: "authorization_code", client_id: "example-web-app", redirect_uri: "http://localhost:8000/keycloak-example-login.html", code: code, }), } ) .then((response) => { if (!response.ok) { throw new Error("Failed to exchange code for tokens"); } return response.json(); }) .then((tokens) => { // Store tokens in session storage storeTokens(tokens); // Once the tokens are received, extract and display the email from the ID token parseAndDisplayEmail(tokens.id_token); }) .catch((error) => { console.error("Error exchanging code for tokens:", error); }); } </script> </body> </html> </code></pre> On first load, the page just shows the keycloak login button. When we click the login button, we are redirected to our Keycloak instance. We sign in with our Passkey and are redirected back to our web app. However, we are now able to display the users email from the id token. Further inspection shows that we have a valid JWT from the keycloak server to pass to our APIs. Conclusion</h2> This example demonstrates how to quickly configure a Keycloak realm to support passkey login and integrate with a simple front end web app. Leveraging this pattern allows us to quickly add standard authentication workflows to web apps that are hardened and support the strongest MFA available. Nutfield Security has deep experience implementing and improving authentication systems. Please Contact Us</a> to see how Nutfield Security can help you implement Keycloak and Passkeys for your web app today.