Links

Flutter

Corbado offers an open-source Flutter passkeys package for iOS and Android with emphasis on maximum flexibility and ease of use for developers
To see a full example of a Flutter app working with the passkeys package, please check the repo on GitHub.

Introduction

Corbado offers an open-source Flutter passkeys package that easily enables authentication via passkeys for Flutter apps with the following platform support:
Android
yes
iOS
yes
Linux
no
macOS
no
Web
no
Windows
no
The main goals of the Flutter passkeys package are:
  • Simplicity: Build an easy-to-use Flutter passkey package that enables every Flutter developer to use passkeys.
  • Flexibility: Provide users the possibility to integrate their own passkey backend.
  • Support: There are a few pitfalls when setting up passkeys. We try to provide guidance and help for common mistakes.

Overview

To better understand the Flutter passkeys flow as well as the architecture of the Flutter passkeys package, please first a look at at
Structure:

1. Flutter passkeys package

The passkeys package enables you to sign up and log in users with passkeys.
To use this package, add passkeys as a dependency in your pubspec.yaml file.
To have a simple app working and not needing to set everything up from scracth, we'll be using the example provided by the passkeys package. Therefore, please clone the following repository:
git clone https://github.com/corbado/flutter-passkeys
The specific Flutter example project is in the following directory
flutter-passkeys/packages/passkeys/passkeys/example

2. Configuration to set up the example

In the following example, we will use Corbado as a relying party server. This gives you the advantage that you don't have to implement anything on your backend side to make passkey authentication work. If you wanted you could implement your own relying party server. For this example we want to keep it simple though. All you need to do is a bit of configuration in Corbado's developer panel.
Go to the Corbado developer panel and create a new account and project. After successful sign up, in the wizard, select ‘Integration guide’, ‘Native / mobile app’ and ‘No existing users’.
Note: Please make sure that under "Settings" - "User interface" - "Identity verification" Option 2: No verification required" is selected. This should be set by default, when selecting “Native / mobile app” in the previous step.
Now, some platform-specific settings have to be made, navigate to the Native Apps settings and add a new Android / iOS app as shown in the next steps.
Android
iOS

2.1 Android

Setup an Android app by clicking "Add new". You will need your package name (e.g. com.corbado.passkeys.example) and your SHA-256 fingerprint (e.g. 54:4C:94:2C:E9:...).
The package name of your app is defined in example/android/app/build.gradle (applicationId). Its default value for the example app is com.corbado.passkeys.example.
You can obtain the SHA-256 fingerprint of your debug signing certificate by executing the following command:
macOS / Linux
Windows
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
keytool -list -v -keystore "\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android
If you have issues getting the certificate, please see Troubleshooting.

2.2 iOS

2.2.1 Create an iOS app and configure the example in XCode

We need to establish trust between your iOS app and the relying party server. Your app will be identified through your Application Identifier Prefix (e.g. 9RF9KY77B2) and your Bundle Identifier (e.g. com.corbado.passkeys). You need an Apple developer account to set up both. If you haven't got one yet, set up a new account.
When creating your Bundle Identifier make sure that the "Associated Domains" capability is enabled:
The Application Identifier Prefix can be obtained by going to your Apple Developer Certificates, Identifier & Profiles associated with your Apple Developer account.
Open the example in Xcode now by opening packages/passkeys/passkeys/example/ios. In Runner -> Signing & Capabilites enter your Application Identifier Prefix and your Bundle Identifier.

2.2.2 Set up iOS Application Identifier Prefix and Bundle Identifier

Setup an iOS app by clicking "Add New". You will need your Application Identifier Prefix and your Bundle Identifier that we set up in step 2.2.1.
Afterwards, the Corbado relying party server will host an apple-app-site-association file at https://{PROJECT_ID}}.frontendapi.corbado.io/.well-known/apple-app-site-association. This file will be downloaded by iOS when you install your app. To tell iOS where to look for the file, we need the next step in our set up.

2.2.3 Configure your iOS project

In your Xcode workspace, you need to configure the following settings: In Signing & Capabilities tab, add the Associated Domains capability and add the following domain: webcredentials:{PROJECT_ID}.frontendapi.corbado.io Now, iOS knows where to download the apple-app-site-association file from.
If you forget about this step the example will show you an error message like
Your app is not associated with your relying party server. You have to add...
Your configuration inside Xcode should look something like in the screenshot below (you will have your own project ID and a different Bundle Identifier).

3. Run the example app

When you cloned the GitHub repo in step 1, make sure that you are now in the right directory to run the example app:
  • For Android: flutter-passkeys/packages/passkeys/passkeys/example/android
  • For iOS: flutter-passkeys/packages/passkeys/passkeys/example/ios
Make sure that you have a running virtual device or a physical device connected to your machine.
Now, you are fully set and you can start registering your first passkey in the example by running the following command:
flutter run --dart-define=CORBADO_PROJECT_ID=PROJECT_ID lib/main.dart
If you run the example from your IDE, please make sure to either
  • set the CORBADO_PROJECT_ID environment variable to your Corbado project ID
  • replace const String.fromEnvironment('CORBADO_PROJECT_ID') directly in the example with your Corbado project ID

4. Troubleshooting

4.1 Weak SHA1 algorithm for Android keystore

If you’ve executed one of the commands in step 2.1 to view your SHA256 fingerprint and you see an error message like the following “SHA1withRSA (weak)”:
Then, you need to create a new Android keystore with a stronger algorithm. You can do with one of the following commands:
macOS / Linux
Windows
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
keytool -list -v -keystore "\.android\debug.keystore”-alias androiddebugkey -storepass android -keypass android

4.2 Android screen lock not set up on virtual Android device

If you run the application in a virtual Android device, and it says that you can't create a passkey, you have to properly set up a screen lock or biometrics on the device. To do so, open the settings, search for security settings and add a PIN as well as a fingerprint as shown below (PIN is required for fingerprint):

5. A closer look at the example

After you've started the app, you will see the login page on the first screen. Here, you can create a new user account by providing an email address and clicking on 'sign up'. After providing your fingerprint / face scan, a new passkey is created and stored on your device.
You will now be logged into the app and see the home page. Your user info is represented by an id token that has been retrieved from the Corbado Frontend API during the sign up process. You can view that token by clicking on "token details". Here, you can observe how the token is refreshed automatically (its lifetime will increase once in a while).
You can also close and reopen the app. You should still be logged in.