Notes Implementing creation and use of Touch ID (platform authenticator) as FIDO2 credential - GluuFederation/fido2 GitHub Wiki

Adding Touch ID as a 2FA device to Gluu

  1. Touch ID - is a platform Authenticator (because it is built-in to the platform)

  2. Touch ID on a web app uses a standard called Web Auhtentication (WebAuthn) which defines a "promise-based" javascript API for the creation (registration ceremony) and use (authentication ceremony) of authentication credentials based on public key cryptography.

the W3C WebAuthn Working Group was formed: to produce a new specification that can be implemented by all browsers (for desktops and mobiles) and that remains interoperable.

The draft specification says:

This specification defines an API enabling the creation and use of strong, attested, scoped, public key-based credentials by web applications, for the purpose of strongly authenticating users.

  1. Apple's only blog for implementing Touch ID as Fido2 device- https://developer.apple.com/videos/play/wwdc2020/10670/

4. Apple Anonymous attestation

a. "Attestation" (performed in the FIDO2 server during enrollment) is basically a secure way for you to ask a device manufacturer that the device is real and really has the capabilities it says it does. It is called Apple Anonymous attestation

Quoting from here - https://webkit.org/blog/11312/meet-face-id-and-touch-id-for-the-web/ Once verified, this attestation guarantees that an authentic Apple device performed the WebAuthn registration ceremony, but it does not guarantee the operating system running on that device is untampered. If the operating system is untampered, it also guarantees that the private key of the just generated credential is protected by the Secure Enclave and the usage of the private key is guarded with Face ID or Touch ID. (A note: the guard falls back to device passcode if biometric fails multiple times in a row.)

Apple Anonymous Attestation is first of its kind, providing a service like an Anonymization CA, where the authenticator works with a cloud operated CA owned by its manufacturer to dynamically generate per-credential attestation certificates such that no identification information of the authenticator will be revealed to websites in the attestation statement. Furthermore, among data relevant to the registration ceremony, only the public key of the credential along with a hash of the concatenated authenticator data and client data are sent to the CA for attestation, and the CA will not store any of these. This approach makes the whole attestation process privacy preserving. In addition, this approach avoids the security pitfall of Basic Attestation that the compromising of a single device results in revoking certificates from all devices with the same attestation certificate.

5. Registration ceremony


WebAuthn promise based API for creating a platform authenticator( Touch ID) cred

 var credentialDetails = {
                'challenge': challenge, 

                'rp': {
                    'name': 'test.gluu.org'
                },

                'user': {
                    'id': "mike",
                    'name': 'Mike Shwartz',
                    'displayName': 'Mike Shwartz'
                },

                'pubKeyCredParams': [
                    { 'type': 'public-key', 'alg': -7  },
                    { 'type': 'public-key', 'alg': -257 }
                ],

                'authenticatorSelection': {
                    'authenticatorAttachment': 'platform'
                },

                'attestation': 'direct'
            }

            navigator.credentials.create({ 'publicKey': credentialDetails })
                .then((newCredential) => {
                   // pass this information to the FIDO2 server to register the credential
                   
                })
                .catch((error) => {
                    
                    console.error('FAILURE: '+ error)
                })

6. Attestation on FIDO2 server (Enrolling / Registering the cred)

The response to the WebAuthn API call in the above step5 returns a response which contains metadata and an attestation object. In the FIDO server we do In the following

  • validate metadata which comprises of Client data and Authenticator data
  • Validate the attestation statement which is part of Authentication data (which contains public key data and attestation certificates). The attestation statement is signed by batch private key, who’s public key is in a batch certificate, that is chained to apple attestation root certificate. The implementation of this was done referring to the only blog available on this subject - https://medium.com/webauthnworks/webauthn-fido2-verifying-apple-anonymous-attestation-5eaff334c849
  • Persist this credential ID which will help identifying this platform Authenticator during subsequent sign ins.

7. Authentication ceremony


WebAuthn promise based API for using a Touch ID credential.
Here transports: ["internal"] denotes that the credential is a platform authenticator.

var credentials = {
    publicKey: {
        challenge: challengeBuffer,
        allowCredentials: [
            { type: "public-key", id: credentialIdBuffer1, transports: ["internal"] },
            // ... more Credential IDs can be supplied.
        ]
    }
};


 navigator.credentials.get({ 'publicKey': credentials })
                .then((credentialResponse) => {
                   // pass this information to the FIDO2 server to verify the credential
                   
                })
                .catch((error) => {
                    
                    console.error('FAILURE: '+ error)
                })

7. Assertion : Verify the credential on the FIDO2 server

Use the previously saved credential (public key) to verify signature. This step is similar to all authenticator devices has no additional changes for Touch ID.

⚠️ **GitHub.com Fallback** ⚠️