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.
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.
To better understand the Flutter passkeys flow as well as the architecture of the Flutter passkeys package, please first a look at at
Structure:
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
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
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
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.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.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).
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.dartIf you run the example from your IDE, please make sure to either
- set the
CORBADO_PROJECT_IDenvironment variable to your Corbado project ID - replace
const String.fromEnvironment('CORBADO_PROJECT_ID')directly in the example with your Corbado project ID
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
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):
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.
Last modified 1mo ago