• Contact Sales
  • Resellers
  • Support
Yubico Header Text LogoYubico Header Text Logo
Why Yubicoexpand_more
Why Yubico
  • Enterprises
  • SMBs
  • Individuals
  • Developers
  • Careers
  • Partner programs
  • Affiliate program
  • Contact Sales
  • Events
  • Press room
  • Yubico Blog
  • Yubico Executive Connect
  • About us
  • The team
  • Investors
  • Innovation history
  • Secure it Forward
Man holding YubiKey
Easy-to-use, secure authentication

With YubiKey there’s no tradeoff between great security and usability

Why YubiKey
  • developers
  • WebAuthn
  • Yubico Developer Program
Google headquarters
Proven at scale at Google

Google defends against account takeovers and reduces IT costs

Google Case Study
  • developers
  • WebAuthn
  • Yubico Developer Program
Hand holding YubiKey behind Apple iPhone
Protecting vulnerable organizations

Secure it Forward: One YubiKey donated for every 20 sold

Learn about Secure it Forward
  • developers
  • WebAuthn
  • Yubico Developer Program
Productsexpand_more
All products
  • YubiKey 5 Series
  • YubiKey 5 FIPS Series
  • YubiKey Bio Series
  • Security Key Series
  • YubiKey 5 CSPN Series
  • YubiHSM 2 & YubiHSM 2 FIPS
  • YubiEnterprise Subscription
  • YubiEnterprise Delivery
  • Yubico Authenticator
  • Computer login tools
  • Software Development Toolkits
  • YubiCloud
  • Using YubiKey is easy
  • Find the right YubiKey
  • Works with YubiKey
  • Compare YubiKeys
Woman holding YubiKey 5ci
One key for hundreds of apps and services

YubiKey works out-of-the-box and has no client software or battery

Yubico protects you
  • developers
  • WebAuthn
  • Yubico Developer Program
See YubiKeys as a Service
YubiEnterprise Subscription delivers scale and savings

Gain a future-proofed solution and faster MFA rollouts

See YubiKeys as a Service
  • developers
  • WebAuthn
  • Yubico Developer Program
Solutionsexpand_more
Solutions overview
  • Zero Trust
  • Executive Order OMB M-22-09
  • Phishing-resistant MFA
  • Passwordless
  • Compliance
  • Cyber Insurance
  • Critical infrastructure
  • Secure supply chain
  • Protect call centers
  • Hybrid & remote workers
  • Secure privileged users
  • Mobile restricted environments
  • Shared workstations
  • Microsoft ecosystem
  • Salesforce workspace
  • IAM solutions
  • AWS environment
  • HYPR experience
  • Okta identity solutions
Hand holding YubiKey behind Apple iPhone
The Bridge to Passwordless

Begin the journey to make your organization passwordless

Get the white paper
  • developers
  • WebAuthn
  • Yubico Developer Program
Lock on a laptop
Accelerate your Zero Trust Strategy

7 best strong authentication practices to jumpstart your Zero Trust program

Get the white paper
  • developers
  • WebAuthn
  • Yubico Developer Program
Government building
Federal cybersecurity requirements

See guidance for CIOs and leaders to prepare for the modern cyber threat era

Get the white paper
  • developers
  • WebAuthn
  • Yubico Developer Program
Industriesexpand_more
Industries overview
  • High tech
  • Federal government
  • Federal systems integrators
  • State & local government
  • Education
  • Financial services
  • Elections & campaigns
  • Retail & hospitality
  • Telecommunications
  • Healthcare
  • Pharmaceuticals
  • Cryptocurrency
  • Energy & natural resources
  • Manufacturing
man working a manufacturing line
Manufacturing and supply chain security

Authentication best practices for manufacturing using highest-assurance security

Get the white paper
  • developers
  • WebAuthn
  • Yubico Developer Program
Person looking at a computer with a government building showing
Phishing-resistant MFA: Fact vs. Fiction

Meet requirements for phishing-resistant MFA in OMB M-22-09 guidelines

Get the white paper
  • developers
  • WebAuthn
  • Yubico Developer Program
Remote workers at a wind farm
Secure energy and natural resources from cyber threats

Best practices for phishing-resistant MFA to safeguard your critical infrastructure

Get the white paper
  • developers
  • WebAuthn
  • Yubico Developer Program
Resourcesexpand_more
All resources
  • Yubico Blog
  • Cybersecurity glossary
  • Authentication standards
  • Resource library
  • Developer program
  • Product briefs
  • Solution briefs
  • Case studies
  • Get a pilot started
  • White papers and reports
  • Webinars
Laptop with a YubiKey inserted
BeyondTrust: secured with a subscription

A leader in Privileged Access Management simplifies YubiKey deployment

How they optimized ROI
  • developers
  • WebAuthn
  • Yubico Developer Program
S&P Global Market Intelligence report: old habits die hard

Only 46% of respondents protect their applications with MFA. How about you?

Read the report
  • developers
  • WebAuthn
  • Yubico Developer Program
Considering Passkeys for your Enterprise?

Learn how to avoid the common pitfalls of synced passkeys

Get the Ebook
  • developers
  • WebAuthn
  • Yubico Developer Program
Supportexpand_more
Support home
  • Find the right YubiKey
  • Set up your YubiKey
  • Downloads
  • Product documentation
  • Support articles
  • Support Services
  • Professional Services
  • YubiEnterprise Subscription
  • Works with YubiKey Program
  • Buying and shipping information
  • Security advisories
  • Help center
YubiKeys in lots of form factors
How to set up your YubiKey

Follow our guided tutorials to start protecting your favorite services

Set up your YubiKey
  • developers
  • WebAuthn
  • Yubico Developer Program
YubiKey on a keychain plugged into a laptop
Find the best YubiKey for your needs

Take the guided quiz and see which YubiKey best fits your or your businesses needs

Take the quiz
  • developers
  • WebAuthn
  • Yubico Developer Program
Worker with a calculator and laptop with a spreadsheet
Accelerate your YubiKey deployment

Technical and operational guidance for your YubiKey implementation and rollout

Professional Services
  • developers
  • WebAuthn
  • Yubico Developer Program
SubscribeStore
  • Home » Blog » Exploring clientDataJSON in WebAuthn

    Exploring clientDataJSON in WebAuthn

    Dennis Hills

    Dennis Hills

    August 11, 2020
    9 minute read
    Share on FacebookShare on XShare on LinkedInShare via Email

    Calling all developers! Today, we’re kicking off our first-ever post in our new technical blog series specifically designed for our developer community. Each month, we will be selecting a new technical topic to cover in more depth.

    To start our series, we dive into the clientDataJSON object as part of the Web Authentication or WebAuthn specification. WebAuthn is an exciting standard that has garnered a lot of interest, but it can often feel complicated to get started.

    WebAuthn defines a client/server ceremony API performing user registration and authentication. For registration, the user, via a client (web browser or mobile app), requests to register a hardware authenticator with a server. For authentication, that user, via a client app, attempts to login to a server with that previously registered authenticator. During these two ceremonies, there’s data passed back and forth between the client and the server.

    The clientDataJSON object is key to the WebAuthn API data exchange. If you are building a desktop or mobile application, the building and encoding of the clientDataJSON object needs to be done using a library or SDK.

    First, let’s go over the high-level aspects of WebAuthn and then we can dive into details about what the clientDataJSON object is, its purpose and its attributes, and finally explain encoding and decoding of this object.

    What is WebAuthn?

    Web Authentication, or WebAuthn, is a W3C-recommended specification that defines an API for enabling the creation and use of public key-based credentials, for the purpose of strongly authenticating users. See the W3C Specification for more information.

    The idea behind WebAuthn is to rid the world of password authentication (something you know) by replacing it with public key authentication (something you have).

    For password authentication, a user generates a password which is passed to the server, where it is stored in a database. During user authentication, the user-generated password is sent to the server for validation against the stored password. If the password matches, the user is authenticated and can access the service offerings or features.

    For WebAuthn public key authentication, strong hardware-backed public/private-key credentials are created and stored by an authenticator, such as a YubiKey, during registration. The private key is securely stored on the authenticator and is never shared, while the server stores the public key portion in the database.

    During user authentication, the server sends pseudo randomly generated challenges to the client for the authenticator to sign. The signature, which takes a hash of the clientDataJSON along with the authenticatorData, is signed over by the private key. This signature proves possession of the private key and assurance that the challenge, relying party (RP) ID, and origin were not tampered with, all without ever sharing the private key or requiring the user to provide a static password. Replay attacks are prevented by the pseudo-randomness of the challenge.  Phishing attacks are prevented by this signing of the challenge with the private key that is scoped to the RP ID (domain). In addition to measures to counter replay and phishing attacks, the web authentication API also prevents compromised credentials (username + password) in that a password is never passed to or stored by the RP, hence the term “passwordless”.

    What is clientDataJSON?

    At a high level, the WebAuthn specification is really just an exchange of challenges and responses performed during two types of ceremonies; registration and authentication. The clientDataJSON object, always populated by the client (browser or app), is sent in response to the RP server during registration and authentication.

    The object, populated by the client, has three required properties: a type, a challenge, and an origin. The type can be either “webauthn.create” for a registration response or “webauthn.get” for an authentication response. The challenge value is the actual challenge that was sent by the RP during the create or get ceremony. The origin contains the effective domain name of the endpoint to which the client is connecting during the WebAuthn registration or authentication.

    Now that we know about the properties, let’s find out the purpose of each property and how these are integrated to control the Web Authentication flow.

    clientDataJSON Use Cases 

    The clientDataJSON is used to determine the current state or flow of the WebAuthn ceremony. The type attribute tells the RP whether this client data is a registration or authentication response to a server challenge.

    The most important responsibility of the clientDataJSON is storing the effective domain of the connected client. In the WebAuthn API spec, the client browser or application is responsible for capturing the effective domain of the connected endpoint and storing it in the origin attribute during the registration (create) and authentication (get) ceremony. The public keypair generated by the authenticator is considered to be “origin-based”, which means the keypair can only be used to authenticate a user when the client is connected to the same domain (origin) endpoint to which it was originally connected (or matches a subset of the server domain) at the time when the keypair was generated. I’ll go into this in more detail later.

    The last responsibility of the clientDataJSON is to capture the cryptographic challenge sent by the RP during registration or authentication. The challenge is randomly generated by the RP and sent to the client during a challenge. The client captures the challenge in the challenge attribute and passes this back to the server.

    clientDataJSON Properties

    The clientDataJSON object (after decoding) has the following properties:

    Property Definition Required/Optional
    type Contains a string with one of two values:

    Required Value(s): “webauthn.create” or “webauthn.get”

    “webauthn.create” → A new credential is being created during REGISTRATION.

    “webauthn.get” → An existing credential is retrieved during AUTHENTICATION

    Required
    challenge The base64url encoded version of the cryptographic challenge sent from the relying party’s server (RP). The original challenge value is passed via the relying party (RP) through PublicKeyCredentialRequestOptions.challenge or PublicKeyCredentialCreationOptions.challenge. Required
    origin The effective domain of the requester given by the client/browser to the authenticator. Required

    Encoding and Decoding clientDataJSON Properties

    With only three main attributes, the clientDataJSON object is pretty straightforward; however, according to the W3C spec, the JSON string is converted into an ArrayBuffer before being transported back to the RP and then back to a string on the server side before validation. The ArrayBuffer is being used for efficiency and optimal performance when speaking binary to the authenticators.

    The conversion to and from an ArrayBuffer is the most confusing for developers. The good news is, for most WebAuthn solutions, developers can rely on a Web Authentication API supporting web browser as the client to handle the interaction with the external authenticator. Those browsers have already implemented the client API requirements using the FIDO2 Client to Authenticator Protocol (CTAP) specification. CTAP is an application layer protocol used for communication between a client (browser) or a platform (operating system) with an external authenticator such as the YubiKey.

    If you are building a mobile, desktop, or IoT application without the use of a browser, you will need to implement the CTAP Authenticator API using a library, or a mobile SDK for iOS or Android.

    On the server side, the RP receives the object as an ArrayBuffer and must be decoded and parsed.

    Here’s what the hashed clientDataJSON object within the client response looks like when received by the relying party during registration:

    Here’s what the hashed clientDataJSON object within the client response looks like when received by the relying party during registration:

    Here’s what the parsed clientDataJSON object looks as a JSON string:

    Here’s what the parsed clientDataJSON object looks as a JSON string:

    In the examples below, the server converts the ByteArray to a JSON object and then parses and validates the data.

    Here’s a Java example of how the Yubico Java Server demo handles the clientDataJSON:

    Here’s a Java example of how the Yubico Java Server demo handles the clientDataJSON:

    Here’s a JavaScript example from the Firefox developer guide:

    Here’s a JavaScript example from the Firefox developer guide:

    Relying Party Validation of WebAuthn clientDataJSON 

    Once the RP receives the registration or authentication response from the client and converts the ByteArray to a JSON object, it’s ready to parse and validate the three attributes. At this point, the server can validate any of the attributes in any order.

    The origin value is the most important validation. The client browser or app determined the endpoint/domain during the request for authentication to the server. The server must then validate that the “origin” string matches at least a subset of the valid domain string of the RP as part of the Relying Party Identifier (RP ID).

    Conclusion

    The clientDataJSON consists of only three required attributes but plays a critical role in the Web Authentication flow between the client and server. In this post we learned that this object is populated by the client during the registration and authentication flows in order to determine the type of ceremony (registration or authentication), the origin of the connected client, and the current challenge from the server. The data is transported as an ArrayBuffer by the client and then decoded and parsed by the server. The RP can reject any authentication attempts if the client object is not encoded properly, contains an incorrect challenge, or the client origin does not match the domain (RP identifier) associated with the JSON string.

    Building and encoding the clientDataJSON object is the client responsibility, but that work is typically handled for you by a web browser that supports Web Authentication. However, if you are building a desktop or mobile application, that work will need to be done using a library or SDK of your choice following the Web Authentication API structure as defined by the W3C spec.

    Resources

    Yubico WebAuthn Developer Guide
    W3C WebAuthn Spec
    Mozilla MDN Web Docs
    Yubico iOS SDK – WebAuthn Client
    Github WebAuthn API wrapper – WebAuthn API wrapper that translates to/from pure JSON using base64url
    Yubico WebAuthn Server (Java)

    Share this article:

    Share on FacebookShare on XShare on LinkedInShare via Email

    Recommended Posts

    • Coming soon: ‘Bring Your Own Key’ capability in YubiHSM 2 will bring the most flexible and highest assurance solution for data security and portability for multi-cloud environments

      Creating a robust data encryption strategy in a multi-cloud environment can be challenging. Considerations like availability, fail-over, control, cost and compliance are crucial. For organizations that are encrypting data on-premises and considering moving data to the cloud, a typical approach is to use an on-premises Hardware Security Module (HSM) or a cloud-based HSM. However, acquiring […]

      Read more
      • BYOK
      • YubiHSM 2
    • Resolve to be cyber resilient: Moving on from legacy MFA in energy and natural resources

      Every November, Critical Infrastructure Security and Resilience (CISR) Month focuses on educating the vital role critical infrastructure plays in the nation’s well being. Led by Cybersecurity and Infrastructure Security Agency (CISA), the conversation centers around why it’s important to strengthen critical infrastructure security and resilience.  One of the critical infrastructures, energy and natural resources, is […]

      Read more
      • CISA
      • energy and natural resources
      • PIV
      • smart card
    • Transcending passwordless authentication with HYPR and Yubico

      In today’s ever-evolving cyberthreat landscape, organizations face increasing challenges in securing their sensitive data and systems from sophisticated attacks like AI-strengthened phishing campaigns or impersonation attacks backed by spates of leaked PII . Even in today’s environments where new, ever larger, breaches make news every week, we’re continuing to see enterprises and employees across the […]

      Read more
      • HYPR
      • partner
      • passwordless
      • survey
    • Phishing-resistant MFA helps businesses reduce risk and costs in the face of a rapidly changing cyber insurance landscape

      To address and insulate themselves from the growing trend of cyber security breaches, more businesses are turning to insurance agencies for cyber insurance policies. While these policies have been around in some form since the late 1990s, the fast growing threat landscape and comparative youth of these policies means that rates and limits have fluctuated […]

      Read more
      • case study
      • cyber insurance
      • partner
Yubico Text LogoYubico Text Logo
  • RSS
  • Twitter
  • LinkedIn
  • Facebook
  • Instagram
  • YouTube
  • GitHub
  • Product finder quiz
  • Find set-up guides
  • Buy online
  • Contact sales
  • Get Yubico updates
  • Careers
  • Events
  • Press room
  • About us
  • Investors
  • Partner programs
  • Affiliate program
  • YubiKey 5 Series
  • YubiKey 5 FIPS Series
  • YubiKey Bio Series
  • Security Key Series
  • YubiKey 5 CSPN Series
  • YubiHSM 2 & YubiHSM 2 FIPS
  • Yubico Authenticator
  • Zero Trust
  • Phishing-resistant MFA
  • Passwordless
  • Cyber insurance
  • More solutions
  • Industries overview
  • Yubico blog
  • Resource library
  • Cybersecurity glossary
  • Authentication standards
  • Developer program
  • Works with YubiKey
  • Help center
  • Downloads
  • Product documentation
  • Support Services
  • Professional Services
  • Contact support
Yubico © 2023 All Rights Reserved.
  • Sitemap
  • Cookies
  • Legal
  • Privacy
  • Patents
  • Terms of use
  • Trust