{"id":21590240,"url":"https://github.com/corbado/example-passkeys-flutter","last_synced_at":"2025-04-06T00:09:03.213Z","repository":{"id":77529660,"uuid":"528723759","full_name":"corbado/example-passkeys-flutter","owner":"corbado","description":"Passkeys (FIDO2 / WebAuthn) example integration of Corbado in Flutter.","archived":false,"fork":false,"pushed_at":"2025-03-27T09:41:52.000Z","size":2284,"stargazers_count":106,"open_issues_count":12,"forks_count":5,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-29T23:09:14.139Z","etag":null,"topics":["android","authenticaton","face-id","fido2","flutter","ios","passkey","passkeys","passkeys-demo","passwordless","touch-id","webauthn","windows-hello"],"latest_commit_sha":null,"homepage":"https://www.corbado.com/passkeys/flutter","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/corbado.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-25T06:29:20.000Z","updated_at":"2025-03-27T09:41:55.000Z","dependencies_parsed_at":"2023-11-17T23:08:30.243Z","dependency_job_id":"a4ba273b-47f0-4c74-8bdb-7bf5fbfe0d8d","html_url":"https://github.com/corbado/example-passkeys-flutter","commit_stats":null,"previous_names":["corbado/example-passkeys-flutter"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corbado%2Fexample-passkeys-flutter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corbado%2Fexample-passkeys-flutter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corbado%2Fexample-passkeys-flutter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corbado%2Fexample-passkeys-flutter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/corbado","download_url":"https://codeload.github.com/corbado/example-passkeys-flutter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247415967,"owners_count":20935387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","authenticaton","face-id","fido2","flutter","ios","passkey","passkeys","passkeys-demo","passwordless","touch-id","webauthn","windows-hello"],"created_at":"2024-11-24T16:17:12.673Z","updated_at":"2025-04-06T00:09:03.194Z","avatar_url":"https://github.com/corbado.png","language":"Dart","readme":"# Flutter Passkeys Example Application\n\nThis is a sample implementation of the [Corbado passkeys-first authentication solution](https://www.corbado.com) using Flutter. The following package is being used:\n\n- [Corbado Auth Flutter](https://github.com/corbado/flutter-passkeys/tree/main/packages/corbado_auth)\n\n[![integration-guides](https://github.com/user-attachments/assets/7859201b-a345-4b68-b336-6e2edcc6577b)](https://app.corbado.com/integration-guides/flutter)\n\n## Getting Started\n\nThis example demonstrates how you can use the Corbado Auth package to setup Passkey based\nauthentication in a matter of minutes.\n\n## How to run the example\n\nTo get started with the `corbado_auth` it's nice to see a running version of an example application\nthat uses this package.\nYou can start the example like this:\n\n1. Run `flutter run lib/main.dart` to start the example (if you want to run on Android or iOS, start\n   a Simulator/Emulator beforehand)\n\n## How to integrate the package into your own app\n\nTo use `corbado_auth` in your own app, you need to create a free project at\nthe [Corbado developer panel](https://app.corbado.com).\n\nIntegrating the package is not just about running `flutter pub add corbado_auth`.\nYou need to configure and customize the package, which requires about one hour.\n\nFor that we have provided an integration guide that is\navailable [here](https://app.corbado.com/integration-guides/flutter).\n\n**Note:** Please make sure to also add your project frontend api link to the relying party Id,\nNavigate to your project in the developer panel then open Settings \u003e General \u003e URLs and input your\nlink.\nIt should be something like `pro-{projectID}.frontendapi.cloud.corbado.io`\n\n## A closer look at the example code\n\nIn addition to going through the integration guide it can be helpful to see the `corbado_auth`\npackage in an example application.\nFor that, let's take a closer look at this example.\n\nThe example is a typical flutter application that makes use of the following libraries:\n\n- go_router (routing)\n- riverpod (data binding and state management)\n- corbado_auth (authentication)\n\nIt consists of 3 pages:\n\n- loading (shown while the app is loading initially)\n- authentication (shown when a user signs up or logs in)\n- profile (shown for users after signup/log in)\n\nTo understand how the `corbado_auth` package is integrated into this example application,\nwe have to take a look at these files/directories:\n\n- **router.dart**: Here we handle routing that is based on the authentication state (e.g. a user\n  that is logged in should not see the authentication screen =\u003e that user must be navigated to the\n  profile screen).\n- **auth_provider.dart**: Here we set up the riverpod providers and thus make authentication state (\n  e.g. the user object) and functionality (e.g. the logout function) available throughout the app.\n- **pages/auth_page.dart**: Here we define the page that loads the Corbado auth screens. We\n  configure it with a set of custom Flutter components (see the next bullet point).\n- **screens/\\*.dart**: Here we define a set of custom Flutter components. Each of them must\n  implement `CorbadoScreen\u003cT\u003e` where `T` is one of 5 currently supported Corbado blocks. Find\n  details about this in the `Corbado blocks` section.\n\n### A quick note about Flutter web\n\nFlutter web relies on some JavaScript code that we provide\non [Github](https://github.com/corbado/example-passkeys-flutter/releases/download/2.4.0/bundle.js).\nIf you want to use `corbado_auth` in a Flutter web application you have to include this JavaScript\nbundle as part of your index.html.\nYou can do this by adding the following `\u003cscript\u003e` tag to your `\u003chead\u003e` section.\n\n```\n\u003cscript src=\"https://github.com/corbado/example-passkeys-flutter/releases/download/2.4.0/bundle.js\" type=\"application/javascript\"\u003e\u003c/script\u003e\n```\n\nFor an example how the `index.html` can look check\nout [index.html](https://github.com/corbado/example-passkeys-flutter/blob/main/web/index.html).\n\n## Corbado blocks\n\nIf you introduce passkeys into your application you will have to define a number of screens in your\nflutter app.\nA user wants to signup and log in with a passkey. We also have to provide fallbacks for situations\nwhere a user can not use a passkey.\nFinally we want to ask users that don't have a passkey yet if they want to create one.\n\nTriggering these screens in the right moments requires quite a bit of logic.\nAt Corbado we provide this as a service for developers and we make it configurable in our developer\npanel.\nAs a developer you have the freedom of defining your own UI implementation for these screens.\n\nTo give you guidance about what data and what functionalities are available for a screen we\nintroduced the concept of **Corbado blocks**.\nOne Corbado block (e.g. `SignupInitBlock`) defines the data and functionalities that you can use on\none of these screens.\nAdding `corbado_auth` to your app means defining these screens.\n\n### Overview of existing Corbado blocks\n\nCurrently, there are 5 Corbado blocks available in the `corbado_auth` package.\nOver time we will add additional blocks that you can implement (they are optional).\nThese 5 blocks are needed by most developers.\n\n#### SignupInitBlock\n\nThis block is used to initiate a sign up.\nThe goal of this block is to ask the user for a unique identifier (currently only email is\nsupported)\nand an optional nice name (we call this a fullname at Corbado).\nThe corresponding screen will thus be shown when a user starts a new signup in your app.\n\nIf the identifier is not available or in the wrong format the block will return an error.\n\nWhen you implement the screen for this block, you usually want to define one or multiple input\nfields\nand two buttons (\"submit\" and \"switch to login\").\nYou should also show the errors (ideally close to the input fields).\n\nCheck\nout [signup_init.dart](https://github.com/corbado/example-passkeys-flutter/blob/main/lib/screens/signup_init.dart)\nto see an example implementation for a screen that uses this block.\n\n#### PasskeyAppendBlock\n\nThis block is used to create a new passkey.\nThe corresponding screen will thus be shown during a signup (after the user has provided the\nidentifier)\nor potentially at the end of a login (if no passkey is existing for the user).\n\nIf setting up the passkey fails (e.g. because the user has cancelled the operation)\nthe block allows either a retry or switching to a fallback authentication method (currently\nemail-otp is supported).\n\nWhen you implement the screen for this block, you usually want to define two buttons.\n\nCheck\nout [passkey_append.dart](https://github.com/corbado/example-passkeys-flutter/blob/main/lib/screens/passkey_append.dart)\nto see an example implementation for a screen that uses this block.\n\n#### EmailVerifyBlock\n\nThis block is used to verify that a user has access to an email address.\nThe corresponding screen will thus be shown during a signup (e.g. if passkeys are not supported or\nif you have configured your Corbado project to verify each email address during signup)\nor during a login (if no passkey has been used).\n\nWhen the screen for this block is rendered, Corbado has already sent out an email to the user\ncontaining a 6-digit code.\nThe user should provide this code through the screen.\nIf the code is wrong the block will indicate this through an error.\nIt then allows to enter the code again or to resend the email (after 30s have passed).\n\nWhen you implement the screen for this block, you usually want to define one or two buttons (submit\nand resend).\nAlso you need an input field (for the 6-digit code).\n\nCheck\nout [email_verify_otp.dart](https://github.com/corbado/example-passkeys-flutter/blob/main/lib/screens/email_verify_otp.dart)\nto see an example implementation for a screen that uses this block.\n\n#### LoginInitBlock\n\nThis block is used to initiate a login process.\nThe goal of this block is to ask the user for her unique identifier (the email address).\nThe corresponding screen will thus be shown at the beginning of a login.\n\nWhen the screen for this block is rendered, conditional UI will be started.\nIf the user has a passkey available he can log in without typing his identifier.\nIt that's not the case he has to provide the email address to the block through an input field.\n\nWhen you implement the screen for this block, you usually want to define one input field (for the\nemail address).\nAlso usually you need two buttons (\"submit\" and \"switch to signup\").\n\nCheck\nout [login_init.dart](https://github.com/corbado/example-passkeys-flutter/blob/main/lib/screens/login_init.dart)\nto see an example implementation for a screen that uses this block.\n\n#### PasskeyVerifyBlock\n\nThis block is used to verify that a user has access to a passkey.\nThe corresponding screen will thus be shown during a login process.\n\nWhen the screen for this block is rendered, a passkey authentication is started.\nIf the user completes it he will move on to the next block (most of the time he directly is logged\nin).\nIf something goes wrong the user can either retry the passkey operation or use a fallback method.\n\nWhen you implement the screen for this block, you usually want to define two buttons\n(one to retry the passkey operation and another one to initiate the fallback).\n\nCheck\nout [passkey_verify.dart](https://github.com/corbado/example-passkeys-flutter/blob/main/lib/screens/passkey_verify.dart)\nto see an example implementation for a screen that uses this block.\n\n### Deep dive: why do we use the concept of Corbado blocks?\n\nWe understand that this concept of `blocks` and `screens` might be challenging at the beginning.\nFrom personal experience, integrating authentication (no matter what solution you use) is always a\nbit challenging at first.\nWhile passkeys are a great feature for end-users for us developers they tend to make life harder\n(at least at the beginning).\n\nWith `corbado_auth` we want to reduce complexity as much as possible for you.\nWe do this on the one hand by implementing parts of the system for you (e.g. the relying party\nserver and session management)\nOn the other hand we try to give clear guidance what authentication related functionalities you can\nuse on which screen.\nThis means that on each screen just by looking at the corresponding block you quickly get an idea\nhow you should build the screen.\nYou still have full control over the UI though.\nMost importantly we also render these screens in the right order for you so you don't need to bother\nwith complex routing during authentication.\n\n## Troubleshooting\n\n| Type                | Issue                      | Note                                                                                                                                                                                                          |\n| ------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| iOS Sim             | Localized string not found | For passkeys to work in the iOS simulator, you need to enable faceID first in the top menu bar under features \u003e faceID \u003e enrolled                                                                             |\n| iOS physical device | Passkeys not working       | Passkeys do not work when running your flutter application on your physical iOS device. This has to do with the signing of your app. Rather test on a virtual iOS device or virtual/ physical Android device. |\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorbado%2Fexample-passkeys-flutter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcorbado%2Fexample-passkeys-flutter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorbado%2Fexample-passkeys-flutter/lists"}