Running/handling multiple tasks within a program, where tasks can make progress without unnecessarily waiting for each other. Dart concurrency is not the same as “multiple Dart instructions running at exactly the same time.”

If you execute tasks strictly one by one, that’s Sequential Execution, not concurrency.

It does not necessarily mean that everything runs at the exact same moment.

Task A → API request
Task B → Database request
Task C → File operation

A → wait → finish
B → wait → finish
C → wait → finish

we can allow them to overlap:

A ──────────────────→ finish
B ───────────→ finish
C ────────→ finish

That’s concurrency.

Why do we need Concurrency?

Imagine your Flutter app needs to load:

1. User profile
2. User orders
3. Notifications

Each API takes around 2 seconds.

Sequential approach:

final profile = await getProfile();
final orders = await getOrders();
final notifications = await getNotifications();

Suppose each API takes 2 seconds:

Timeline:

0s                2s                4s                6s
│─────────────────│─────────────────│─────────────────│
   getProfile         getOrders          notifications
   ████████████       ████████████       ████████████

Total ≈ 6 seconds. But these APIs are independent. So we can start them together.

getProfile()
   ↓
START
   ↓
await → WAIT 2 sec
   ↓
profile received
   ↓
getOrders()          ← only NOW it starts
   ↓
await → WAIT 2 sec
   ↓
orders received
   ↓
getNotifications()   ← only NOW it starts

Concurrent approach:

final profileFuture = getProfile();
final ordersFuture = getOrders();
final notificationsFuture = getNotifications();

final profile = await profileFuture;
final orders = await ordersFuture;
final notifications = await notificationsFuture;

Now Look carefully at the first three lines:

final profileFuture = getProfile();
final ordersFuture = getOrders();
final notificationsFuture = getNotifications();

There is NO await here. So all three operations are started immediately:

0s
│
├── getProfile()        ████████████ → 2s
│
├── getOrders()         ████████████ → 2s
│
└── getNotifications()  ████████████ → 2s

Only after starting all three, we wait for their results:

final profile = await profileFuture;
final orders = await ordersFuture;
final notifications = await notificationsFuture;

So total ≈ 2 seconds, not 6. This is a very practical example of concurrency. In Dart, asynchronous operations commonly return a Future.

Think of a Future as:

“I don’t have the result right now, but I’ll give it to you later.”

What does await do?

final user = await fetchUser();

await means:

“Wait for this Future’s result before continuing this particular async function.” It does NOT mean that the entire Dart program freezes. That’s a very common beginner misunderstanding.

Sequential vs Concurrent

Sequential:

final a = await taskA();
final b = await taskB();
final c = await taskC();

Task A
████████

        Task B
        ████████

                Task C
                ████████

A = 2 sec
B = 3 sec
C = 1 sec

So Total, 2 + 3 + 1 = 6 seconds

Concurrent:

final futureA = taskA();
final futureB = taskB();
final futureC = taskC();

final a = await futureA;
final b = await futureB;
final c = await futureC;

Task A
████████████

Task B
██████████████████

Task C
██████

All three are started before we wait for their results.

Total: max(2, 3, 1) = 3 seconds

Future.wait()

specifically useful when you have multiple independent Futures and need all their results.

final results = await Future.wait([
  taskA(),
  taskB(),
  taskC(),
]);

             ┌── Task A ──┐
             │             │
Future.wait ─┼── Task B ──┼──→ All completed
             │             │
             └── Task C ──┘

Very important: Future.wait doesn't magically make code faster

Suppose:

Future<int> taskA() async {
  await Future.delayed(Duration(seconds: 2));
  return 10;
}

Future<int> taskB() async {
  await Future.delayed(Duration(seconds: 3));
  return 20;
}

This:

await Future.wait([
  taskA(),
  taskB(),
]);

doesn’t make either operation itself faster.

Instead:

Sequential:

A ████████ 2 sec
         B ████████████ 3 sec
Total = 5 sec


Concurrent:

A ████████
B ████████████
Total = 3 sec

What is a Dart Isolate?

An isolate is an independent Dart execution environment.

In a typical Flutter app, we mainly work with one isolate:

Flutter App
    │
    ▼
Main Dart Isolate
    │
    ├── Dart code
    ├── Event Loop
    ├── Microtask Queue
    └── Event Queue

One isolate normally executes one Dart operation at a time.

print("A");
print("B");
print("C");

We didn’t get A and B and C simultaneously. Instead:

A
↓
B
↓
C

The Dart isolate executes them sequentially.

How does asynchronous code work?

Future<void> loadData() async {
  print("Start");

  final user = await fetchUser();

  print(user);
  print("End");
}

Future<String> fetchUser() async {
  await Future.delayed(Duration(seconds: 2));
  return "Gaurav";
}

We might initially think:

Start
   ↓
wait 2 seconds
   ↓
Gaurav
   ↓
End

And that’s logically correct from the function’s perspective. But internally, Dart doesn’t simply freeze the entire isolate for 2 seconds. This is the important part.

What does await actually mean?

When Dart reaches:

final user = await fetchUser();

Dart essentially says:

“I need the result of fetchUser(), but that result isn't ready yet. I'll pause this async function and allow other work to execute."

loadData()
   │
   ├── print("Start")
   │
   └── await fetchUser()
             │
             └── Future not completed

At this point, loadData() is suspended. But the isolate itself is not necessarily blocked. That’s a huge distinction. await pauses the async function, not the entire Dart isolate.

Dart remembers Continue from here when fetchUser completes.

Imagine your app needs data that is not immediately available.

• Fetch user profile from server
• Read data from SQLite
• Load SharedPreferences
• Read a JSON file
• Authenticate user
• Download an image

App starts
      │
      ▼
Request data
      │
      ▼
Waiting...
      │
      ▼
Data arrives
      │
      ▼
Show UI

Flutter needs a widget that can automatically update the UI when that work finishes. That’s exactly what FutureBuilder does.

FutureBuilder listens to a Future and rebuilds the UI whenever the Future’s state changes.

What is a Future?

Before learning FutureBuilder, students must understand Future. A Future represents a value that will be available later. Think of ordering food online.

Restaurant

You order Pizza
      │
      ▼
Cooking
      │
      ▼
Delivery
      │
      ▼
You receive Pizza

While the pizza is cooking, you don’t have it. Exactly the same with Future.

Future<User>
↓
Waiting
↓
User object arrives later

Example:

Future<String> fetchName() async {
  await Future.delayed(Duration(seconds: 3));
  return "Gaurav";
}

Immediately after calling:

fetchName();

You don’t have:

"Gaurav"

You only have

Future<String>

Three seconds later:

Future<String>
↓
"Gaurav"

Why can’t we simply do this?

Many beginners try:

String name = fetchName();

Flutter says

A value of type Future<String>
can't be assigned to String

Because:

Future<String>
≠
String

It is like

Receipt
≠
Pizza

The receipt only promises you’ll get pizza later. Without FutureBuilder Suppose you want to show user data.

Without FutureBuilder

Screen opens
↓
Call API
↓
Show loading
↓
Wait
↓
Receive data
↓
setState()
↓
Hide loading
↓
Display data

You write lots of code.

bool loading = true;
String name = "";
void loadUser() async {
  name = await fetchName();
  loading = false;
  setState(() {});
}

Inside build:

if(loading){
   return CircularProgressIndicator();
}else{
   return Text(name);
}

Works But FutureBuilder does this automatically. FutureBuilder handles everything Instead of:

loading variable
+
setState()
+
error handling
+
success handling

You simply write:

FutureBuilder()

Basic Syntax:

FutureBuilder<String>(
  future: fetchName(),
  builder: (context, snapshot) {},
)

There are only two important properties.

future

builder

future

The async task.

future: fetchName()

future: getProducts()

future: loadUser()

builder

Builder receives an object called

AsyncSnapshot

builder: (context, snapshot) {}

Everything about the Future is inside snapshot.

What is AsyncSnapshot?

Think of it as a status report.

Future
↓
Snapshot

contains
• Current State
• Data
• Error

AsyncSnapshot
------------------------
ConnectionState
Data
Error
StackTrace
------------------------

snapshot.connectionState

This tells where the Future currently is. Possible values:

none
waiting
active
done

For FutureBuilder you’ll mostly use:

waiting
done

ConnectionState.none

No Future is attached.

FutureBuilder
↓
future = null

ConnectionState.waiting

The Future is still running.

API Call
↓
Waiting...
↓
No data yet

Usually show

CircularProgressIndicator()

ConnectionState.done

Future finished. Now either Success or Failed

snapshot.hasData

Returns if data arrived.

API
↓
User
↓
snapshot.hasData == true

snapshot.data

Actual result.

Text(snapshot.data!)

snapshot.hasError

If something failed.

Internet disconnected
↓
API failed
↓
snapshot.hasError == true

snapshot.error

Actual error.

Text(snapshot.error.toString())

Complete Flow:

Future Starts
↓
ConnectionState.waiting
↓
Loading Spinner
↓
Future Completes
↓
ConnectionState.done
↓
Success ?
↓
Yes
↓
snapshot.data
↓
Show Data

or

Future Starts
↓
Waiting
↓
Done
↓
Failed
↓
snapshot.error
↓
Show Error

Why should we NOT create the Future inside build()?

This is one of the most common beginner mistakes.

Widget build(BuildContext context) {
  return FutureBuilder(
    future: fetchName(),
    builder: ...
  );
}

Why is it a problem?

The build() method can run many times:

• The keyboard opens.
• The device rotates.
• The parent widget rebuilds.
• setState() is called anywhere that affects this widget.

Correct way

Create the Future once in initState() and reuse it.

class _HomeState extends State<Home> {

  late Future<String> futureName;

  @override
  void initState() {
    super.initState();
    futureName = fetchName();
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<String>(
      future: futureName,
      builder: (context, snapshot) {
        // Build UI
      },
    );
  }
}

Now the flow becomes:

initState()

↓

fetchName()

↓

Future stored

↓

build()

↓

FutureBuilder uses same Future

↓

Parent rebuilds

↓

build()

↓

Same Future reused

↓

No duplicate API call

What is initialData?

Suppose you don’t want to display null while waiting. You can provide an initial value.

FutureBuilder<String>(
  future: fetchName(),
  initialData: "Loading user...",
  builder: (context, snapshot) {
    return Text(snapshot.data!);
  },
)

During the waiting state, snapshot.data is "Loading user...". After the Future completes, it becomes the real value (for example, "Gaurav").

FutureBuilder vs StreamBuilder

| Feature           | FutureBuilder             | StreamBuilder                                  |
| ----------------- | ------------------------- | ---------------------------------------------- |
| Data count        | One result                | Multiple results                               |
| Updates           | Once                      | Continuously                                   |
| Example           | API call, database read   | Chat messages, sensor data, Firebase listeners |
| Connection states | Mainly `waiting` → `done` | `waiting` → `active` → `done`                  |

Think of them like this:

• FutureBuilder: “Tell me once when you’re finished.”
• StreamBuilder: “Keep telling me whenever something changes.”

Real-world examples of FutureBuilder

| Scenario          | Future                                 
| ----------------- | -------------------------------------- 
| Login             | Authenticate the user                  
| Splash screen     | Check if the user is already logged in 
| E-commerce        | Fetch product list                     
| News app          | Load latest articles                   
| Banking app       | Fetch account balance                  
| Weather app       | Get current weather                    
| Gallery app       | Load images from storage               
| SharedPreferences | Read saved theme or language           
| SQLite            | Load local notes or tasks              

Key takeaways for beginners

• A Future represents a single result that will arrive later.
• FutureBuilder rebuilds the UI automatically when that Future changes state.
• AsyncSnapshot gives you the current state (connectionState), data (data), and any error (error).
• Show a loading indicator while connectionState == ConnectionState.waiting.
• Check snapshot.hasError before using the data.
• Use snapshot.hasData and snapshot.data to display the result.
• Never create a new Future inside build() unless you intentionally want the asynchronous operation to restart on every rebuild. Store the Future in initState() (or another lifecycle method) and reuse it.

Both widgets use the same AsyncSnapshot pattern—the main difference is that a Future emits one result, while a Stream can emit many results over time. In next article we will explain StreamBuilder in next part.

“Close your eyes. Can you still use Instagram? Can you still order food from Swiggy? Can you still book a cab?”

Most will answer:

“No.” But millions of visually impaired users use these apps every day.

How?

Because of screen readers. A screen reader doesn’t see your UI.

• Android → TalkBack
• iPhone → VoiceOver

It reads your app.

So your Flutter app needs to tell Android and iOS:

“This widget is a button.”

“This image is a profile picture.”

“This switch is ON.”

That information is called Semantics.

Many beginners think Flutter builds only one tree. Actually Flutter builds multiple trees.

Your Flutter Code
       │
       ▼
Widget Tree
       │
       ▼
Element Tree
       │
       ▼
Render Tree
       │
       ▼
Semantics Tree
       │
       ▼
Android TalkBack
iOS VoiceOver

Accessibility introduces a fourth important tree: The Semantics Tree.

What is a Semantics Tree?

it as a translated version of your UI.

Suppose your screen looks like this.

 -----------------------------
| 👤  Gaurav Kumar            |
|                             |
|  [ Follow ]                 |
 -----------------------------

A normal user sees

• Avatar
• Name
• Button

A blind user doesn’t. The screen reader asks Flutter: “Describe this screen.” Flutter answers using the Semantics Tree.

Profile picture

John Smith

Follow Button

Accessibility widgets are basically Braille for your app.

What is Semantics Widget?

The Semantics widget gives meaning to another widget. Think of it as adding a label.

Suppose you have: Icon(Icons.delete) Everyone knows it’s delete. But TalkBack sees as Image.

That’s it. So we add Semantics.

Semantics(
  label: "Delete",
  child: Icon(Icons.delete),
)

Now TalkBack says Delete.

hint

Hint tells the user what will happen.

Example

Semantics(
  label: "Delete",
  hint: "Double tap to delete this message",
  child: Icon(Icons.delete),
)

TalkBack:

Delete
Double tap to delete this message

value

Used when the widget changes. Suppose we have a volume slider.

========O-------

Semantics

Semantics(
  label: "Volume",
  value: "70 percent",
  child: Slider(...),
)

TalkBack

Volume
70 percent

button

Flutter doesn’t always know your custom widget behaves like a button.

Example

GestureDetector(
  onTap: () {},
  child: Container(
    padding: EdgeInsets.all(16),
    color: Colors.blue,
    child: Text("Login"),
  ),
)

Looks like a button.

Flutter sees Container.

TalkBack will say: Login

This is Not enough.

Now

Semantics(
  button: true,
  label: "Login",
  child: GestureDetector(...),
)

TalkBack

Login
Button

Now users know it is tappable.

What is MergeSemantics?

Let’s imagine a product card.

📱
iPhone 16
₹90,000

Without MergeSemantics TalkBack stops three times.

Image
iPhone 16
90,000 Rupees

User keeps swiping. Very annoying.

With MergeSemantics

MergeSemantics(
  child: ProductCard(),
)

TalkBack

iPhone 16
90,000 Rupees

One stop. One announcement. Much better.

Another Example

Profile Card

👤
John
Software Engineer

Without merge will TalkBack consider

Image
John
Software Engineer

Three stops. With merge

John
Software Engineer

One stop.

What is ExcludeSemantics?

This one confuses almost everyone initially. Let’s understand with an example.

Imagine this widget.

Row(
  children: [
    Icon(Icons.home),
    Text("Home"),
  ],
)

Screen reader says:

Home Icon

Home

Two announcements. But both mean the same thing. We don’t need both. So we hide the icon.

ExcludeSemantics(
  child: Icon(Icons.home),
)

Now : Home Only Once

Example

Imagine someone introduces themselves.

Hi,
I'm Rahul.
My name is Rahul.

That’s repetitive. Instead

Hi,
I'm Rahul.

Much better. ExcludeSemantics removes repetition.

When All Three Work Together

Imagine a custom settings tile.

⚙️
Settings
>

Without accessibility TalkBack will see:

Image
Settings
Arrow

Three stops. Poor experience.

Now:

Semantics(
  label: "Settings",
  hint: "Double tap to open settings",
  button: true,
  child: MergeSemantics(
    child: Row(
      children: [
        ExcludeSemantics(
          child: Icon(Icons.settings),
        ),
        ExcludeSemantics(
          child: Text("Settings"),
        ),
        ExcludeSemantics(
          child: Icon(Icons.arrow_forward),
        ),
      ],
    ),
  ),
)

Now TalkBack announces: “Settings. Button. Double tap to open settings.”

This is concise, meaningful, and easy to navigate.

Summary:

| Widget               | Think of it as                           | What it does                                          |
| -------------------- | ---------------------------------------- | ----------------------------------------------------- |
|   Semantics          | Giving someone a name tag                | Adds meaning to a widget                              |
|   MergeSemantics     | Putting related papers into one folder   | Combines multiple widgets into one accessible element |
|   ExcludeSemantics   | Removing duplicate words from a sentence | Hides unnecessary accessibility information           |

Please find attach demo app on github:

https://github.com/Anonymousgaurav/Accessibility_Widgets

Why This Bug Was Interesting

Every Flutter developer eventually encounters a bug that looks simple but isn’t.

You might think:

• Maybe FocusNode is wrong.
• Maybe TextInput.hide() isn't working.
• Maybe setState() is rebuilding too much.

But sometimes none of those are the real cause.

Our Stripe CardFormField issue is one of those cases. The keyboard flicker wasn’t caused by Flutter. It happened because Flutter and Android were both trying to control the keyboard at the same time.

How Flutter Receives Keyboard Input

Before discussing Stripe, we need to understand how Flutter normally handles text input. We already discussed this in Part — 1 of this article.

User taps TextField
        │
        ▼
Flutter gives it Focus
        │
        ▼
FocusManager updates
        │
        ▼
Flutter tells Android:
"I need the keyboard."
        │
        ▼
Android IME opens

IME

IME stands for Input Method Editor. Most developers simply call it Soft Keyboard.

Examples:

• Android keyboard
• Gboard
• Samsung Keyboard
• SwiftKey

Flutter does not create the keyboard. Android does. Flutter only requests Android to show or hide it.

Flutter communicates with Android using the TextInput channel. When Flutter wants the keyboard:

Flutter

↓

TextInput.show

↓

Android IME

When Flutter wants to hide it:

SystemChannels.textInput.invokeMethod(
    'TextInput.hide');

Android receives that request. Normally that’s enough.

Why Stripe Is Different?

A normal TextField looks like this.

Flutter
     │
     ▼
TextField

Everything belongs to Flutter. But Stripe is different.

Flutter

↓

Platform View

↓

Android EditTexts

The card number field, expiry field, and CVC field are real Android views.

Flutter does not own them.

Why Platform Views Are Difficult?

Platform views introduce a second UI framework. Instead of Flutter we now have Flutter + Android. Both can request focus. Both can request the keyboard. Both can rebuild. Both can animate. This is why platform views are more complex than ordinary widgets.

The Android Keyboard System

Android has a service called It controls

• opening keyboard
• closing keyboard
• moving focus
• connecting EditTexts

Whenever an EditText gains focus

Android automatically says Open keyboard. Flutter cannot stop this with TextInput.hide() because Android owns the EditText.

Why Our Bug Happened:

User types card

↓

CardFormField owns focus

↓

User presses Add

↓

Flutter hides keyboard

↓

Stripe begins createPaymentMethod()

↓

Native EditText gains focus again

↓

Android opens keyboard

↓

Flutter hides keyboard again

↓

Flicker

Nothing was actually broken. Both frameworks were simply doing their jobs. Many developers try:

FocusManager.instance.primaryFocus?.unfocus();

await SystemChannels.textInput.invokeMethod(
    'TextInput.hide');

That removes Flutter’s focus. But Android still has

EditText

↓

requestFocus()

So Android opens the keyboard again.

This is why our Flutter solution worked only about 80–90% of the time.

The remaining 10–20% required native Android code. Flutter cannot directly execute Android code. Instead, Flutter and Android communicate through a bridge called a MethodChannel.

Flutter (Dart)

        │

MethodChannel

        │

Android (Kotlin)

we will do communication bridge between Flutter (Dart) and Android (Kotlin). Flutter cannot directly execute Android methods.

Similarly Android cannot directly call Dart methods. They need a communication bridge. That bridge is called a MethodChannel. Flutter creates the channel.

static const MethodChannel _imeChannel =
    MethodChannel("your_app_name/ime_control");

Flutter says:

“I’m going to communicate using a channel named your_app_name/ime_control.”

Nothing happens yet. It simply creates a communication endpoint. Android will create same channel.

MethodChannel(
    flutterEngine.dartExecutor.binaryMessenger,
    IME_CHANNEL
)

where IME_CHANNEL:

private val IME_CHANNEL = “your_app_name/ime_control”

Did you Notice something ?

Flutter:

your_app_name/ime_control

Android:

your_app_name/ime_control

These names must be identical. Now Android starts listening:

.setMethodCallHandler { call, result ->

means “Android is now waiting for Flutter to send a message.” Nothing happens until Flutter calls the channel. Flutter Calls Android Somewhere in Dart we write:

await _imeChannel.invokeMethod(
    "suppressSoftInput");

Flutter sends this message.

Channel

Method Name

↓

suppressSoftInput

This message travels to Android. Android Receives the Message. Now this code executes.

when (call.method)

Think like this:

Flutter said

↓

"suppressSoftInput"

↓

Which method is this?

↓

Run suppressSoftInput()

If Flutter instead sends → invokeMethod(“restoreSoftInput”) then Android executes restoreSoftInput().

What’s Next?

In this article, we explored how Flutter manages focus, the relationship between FocusManager, FocusNode, and the platform's Input Method Editor (IME), and why simply hiding the keyboard isn't always enough when working with embedded native Android views such as Stripe CardField, Google Maps, or other Platform Views.

In the next article, we’ll move beyond theory and dive into the native Android implementation. We’ll learn how to communicate between Flutter and Android using Method Channels, and implement native APIs to programmatically hide, show, suppress, and restore the Android IME keyboard. We’ll also explore how this approach helps eliminate keyboard flickering, prevents focus conflicts between Flutter and native views, and provides a smoother user experience when integrating Platform Views into Flutter applications.

Have you ever encountered keyboard or focus issues in your Flutter app while integrating native SDKs like Stripe, Google Maps, WebView, Camera, or other Platform Views?

you’ve probably run into strange keyboard behavior — especially when working with native components such as Stripe CardFormField, Google Maps, WebView, Camera, or other Platform Views.

Some common symptoms include:

• The keyboard won’t dismiss.
• The keyboard disappears and immediately comes back.
• FocusScope.of(context).unfocus() doesn't seem to work.
• TextInput.hide() works on Android but behaves differently on iOS.
• Navigation causes the keyboard to reopen unexpectedly.

If you’ve experienced any of these, you’re not alone. 😄

In reality, Flutter is doing exactly what it was designed to do. The confusion comes from assuming that removing focus and hiding the keyboard are the same operation. They are not.

In this article, we’ll explore how Flutter manages focus, how the Flutter Engine communicates with Android and iOS, and why understanding this architecture will save you hours of debugging keyboard-related issues.

Hidden Difference Between unfocus() and TextInput.hide() in Flutter

Every Flutter developer has written code like this:

FocusManager.instance.primaryFocus?.unfocus();

or

await SystemChannels.textInput.invokeMethod('TextInput.hide');

Both make the keyboard disappear.

So naturally the question is:

Are they actually the same?

The answer is No.

One changes Flutter’s focus system.

The other talks directly to the native operating system. Understanding this difference makes keyboard bugs, Stripe CardFormField issues, WebViews, PlatformViews, and custom input widgets much easier to debug. Flutter has its own focus management system.

Think of focus as answering one simple question:

Which widget is currently receiving keyboard input?

When the cursor is blinking then focus is on First Name. Internally Flutter knows

FocusManager
│
▼
FocusNode
│
▼
TextField

Only one widget usually has the primary focus. You can inspect it anytime. Only one widget generally owns the keyboard at a time.

FocusManager.instance.primaryFocus

Focus System Architecture

Flutter has an entire focus management system.

There are two important classes.

• FocusManager
• FocusNode

What is FocusManager?

FocusManager is the global manager of every focusable widget in the application.

There is only one FocusManager. “The traffic controller of keyboard focus.”

It always knows

• Which widget currently has focus
• Which widget lost focus
• Which widget should receive the next focus

Internally FocusManager.instance is a singleton.

Meaning

Entire App
     │
     ▼
FocusManager.instance

Everything goes through this object.

What is FocusNode?

FocusNode represents the focus state of one widget.

Think of it as an ID card.

Every TextField may have one.

Email TextField
      │
      ▼
 EmailFocusNode

Password TextField
      │
      ▼
 PasswordFocusNode

Example:

final emailFocus = FocusNode();

TextField(
  focusNode: emailFocus,
)

Now:

TextField
      │
      ▼
 emailFocus

Relationship:

FocusManager
      │
      │ manages
      ▼
 FocusNode
      │
      │ attached to
      ▼
 TextField

FocusManager never directly manages TextField.

Primary Focus

Flutter exposes

FocusManager.instance.primaryFocus

This means “The widget currently receiving keyboard input.” Suppose Email is active.

FocusManager

primaryFocus
      │
      ▼
Email FocusNode

If you want to print active widget focus node:

print(FocusManager.instance.primaryFocus);

you will get output like this → FocusNode#12345 which belongs to the active widget.

requestFocus()

Suppose user presses Next. Instead of tapping manually. You can move focus yourself.

passwordFocus.requestFocus();

requestFocus()

      │

      ▼

FocusManager

      │

      ▼

Password becomes focused

unfocus()

Now suppose user taps outside. Flutter removes focus.

emailFocus.unfocus();

FocusScope

One screen can have many FocusNodes. Flutter groups them into a FocusScope.

Login Screen

FocusScope
      │
      ├── Email
      ├── Password
      ├── OTP
      └── Login Button

Calling FocusScope.of(context).nextFocus(); Moves

Email

↓

Password

↓

OTP

↓

Login

Focus Tree

Flutter actually builds a tree.

This tree helps Flutter know where focus should move when users press Tab, Shift+Tab, or navigate with a keyboard.

Why FocusNode is important

Without FocusNode Flutter cannot

• move cursor
• detect focus
• remove focus
• highlight active widget
• support keyboard shortcuts
• support accessibility

The key idea is that the keyboard doesn’t belong to a TextField directly. The keyboard sends input to the currently focused FocusNode, and the FocusManager is responsible for deciding which FocusNode that is at any given moment. This separation allows Flutter to support seamless focus traversal, hardware keyboards, accessibility, and complex widget hierarchies across platforms.

Microsoft Calendar integration is the process of connecting a Microsoft Calendar, such as Outlook Calendar or Microsoft 365 Calendar, with other applications to enable seamless scheduling, event management, and collaboration. This integration can be achieved using APIs, connectors, or third-party tools.

How to Implement Microsoft Calendar Integration

Use Microsoft Graph API:

• Provides robust features for managing calendar events programmatically.

Use Native Connectors:

• Tools like Zapier, Power Automate, or IFTTT simplify integration.

Custom Development:

• Build tailored integrations using development platforms or libraries.

So in this article we are going to follow Microsoft Graph API. Let’s go step by step.

1. Create your account on Azure portal.
2. Register your application by Navigating to “Azure Active Directory” > “App registrations.”

3. Click on “New Registration.”

4. Provide a name for your app, select account types, and enter a redirect URI (e.g., http://localhost:3000 for testing)

5. Take Note of Application Credentials:

• Once registered, note the Application (Client) ID and Directory (Tenant) ID.

• Generate a Client Secret under the “Certificates & Secrets” section.

Congrats. we have regsitered our application on Azure portal.

Now we have to configure API Permissions.

Your app needs permissions to access users’ calendars.

1. Go to your app registration.
2. Navigate to API Permissions under Manage section.

3. Click Add a Permission:

4. Select Microsoft Graph.

• Add Delegated Permissions (if the app will act on behalf of a user) like Calendars.ReadWrite offline_access User.Read
• Optionally, add Application Permissions for server-to-server calls.

5. Grant Admin Consent for your organization if required.

We have done with API Permissions.

Conclusion

In this article, we took the first crucial steps toward integrating Microsoft Outlook Calendar by registering our application in Azure Active Directory and configuring the necessary API permissions. These actions lay the foundation for secure communication with Microsoft Graph API, enabling us to access and manage calendar data in future steps. Stay tuned as we move forward to implement authentication and interact with the calendar API in the next article!

Keycloak offers various built-in features for the login page.

Enabling “Forgot Password”

To allow users to reset their passwords or OTPs:

1. Go to Realm Settings in the menu.
2. Click the Login tab

Built-in login features, like “Forgot Password,” enhance usability, security, and user experience. They simplify account recovery, reduce support requests, and ensure seamless access to applications.

Use Cases:

1. Forgot Password Feature:

• Why? Users often forget their passwords. A built-in “Forgot Password” feature helps them reset it without contacting support, improving user satisfaction.
• Example:
  In an e-commerce app, if a user forgets their password while trying to complete a purchase, they can use the “Forgot Password” option to reset it instantly and proceed without abandoning their cart.

3. Toggle Forgot password to ON.

A Forgot Password? link displays in your login pages.

Forgot password link

4. Set the Host and From fields in the Email tab so Keycloak can send password reset emails.

5. When users click the “Forgot Password” link, they can enter their username or email address to get an email with a link to reset their password.

6. The email text for password reset can be customized. Refer to the Server Developer Guide for details.

When users click the reset link in the email, Keycloak prompts them to update their password. If they use an OTP generator, Keycloak will also ask them to reconfigure it. For higher security, you can choose to prevent users from resetting their OTP generator via email.

To modify the behavior for resetting OTP during password resets, follow these steps:

Go to the Authentication menu.

1. Click the Flows tab.
2. Select the Reset Credentials flow.
3. Set the Reset — Conditional OTP sub-flow requirement to Disabled if you want to prevent OTP reset.

In the Authentication menu, click the Required actions tab.

Ensure that Update Password is enabled.

Enabling Remember Me

To enable the Remember Me feature in Keycloak:

1. Go to the Realm Settings menu.
2. Click the Login tab.
3. Toggle the Remember Me switch to On.

When enabled, the login page will display a “Remember Me” checkbox. If a user selects it during login, their session remains active even after closing the browser, as the login cookie becomes persistent instead of session-only.

ACR to Level of Authentication (LoA) Mapping

ACR to Level of Authentication (LoA) Mapping links an Authentication Context Class Reference (ACR) value to a Level of Authentication (LoA). This mapping helps define and enforce the security level of user authentication required for specific scenarios.

What is ACR?

ACR stands for Authentication Context Class Reference, which is a value used in OpenID Connect (OIDC) to describe the context or method of user authentication.
For example:

• ACR values may indicate that a user logged in using a password, biometrics, or multi-factor authentication (MFA). Multi-Factor Authentication (MFA) is a security process requiring users to verify their identity using two or more authentication factors from different categories. It enhances security by combining multiple layers of protection.

Three Categories of Authentication Factors

1. Something You Know
   Information only the user knows, such as:

• Passwords
• PINs
• Security questions

2. Something You Have
Physical items or tokens the user possesses, such as:

• Mobile phones (for OTP or app-based authentication)
• Security tokens (e.g., hardware keys like YubiKey)
• Smart cards

3. Something You Are
Biometric traits unique to the user, such as:

• Fingerprints
• Facial recognition
• Iris scans
• Voice recognition

How MFA Works

When logging into a system, the user must provide credentials from at least two of the above categories.
Example Workflow:

1. Step 1: Enter a username and password (Something You Know).
2. Step 2: Receive a One-Time Password (OTP) on a mobile phone and enter it (Something You Have).
3. Optional Step 3: Use fingerprint verification (Something You Are) for higher security requirements.

Real-World Examples

1. Online Banking

• Step 1: Enter username and password to access the account.
• Step 2: Confirm identity by entering an OTP sent to the registered phone.

2. Workplace Access

• Step 1: Swipe a smart card to access the office.
• Step 2: Provide a fingerprint scan at the door.

3. Cloud Services (e.g., Google)

• Step 1: Log in with a password.
• Step 2: Verify login with an authentication app like Google Authenticator or receive a push notification on a trusted device.

What is LoA Mapping?

LoA (Level of Authentication) mapping refers to the process of associating specific authentication methods with a numeric value that represents their strength or security level. The numeric Level of Authentication (LoA) helps define the assurance or confidence that the user is who they claim to be, based on the method(s) used to authenticate them.

How LoA Mapping Works

1. Define Levels of Authentication: Assign numeric values to different authentication strengths. For example:

• LoA 1: Basic authentication (e.g., username and password).
• LoA 2: Two-factor authentication (e.g., password + OTP).
• LoA 3: Advanced authentication (e.g., password + biometric scan).
• LoA 4: Very high-security authentication (e.g., hardware tokens + biometric + geo-location checks).

2. Associate Authentication Contexts (ACRs): The authentication method (or context) is mapped to the numeric LoA. This allows systems to enforce security policies based on the required level of assurance.

3. Use in Applications: When a user accesses a system or service, the authentication method they use determines the LoA, and access is granted only if the LoA meets or exceeds the system’s requirements.

Real-World Examples of LoA Mapping

1. Banking Applications

• LoA 1: A user logs in to check account balances using only a password.
• LoA 2: A user makes a fund transfer, requiring OTP verification sent to their phone.
• LoA 3: A user accesses sensitive features like account deletion, requiring a biometric scan in addition to an OTP.

2. Government Services

• LoA 1: Citizens log in to view public service announcements using a simple username and password.
• LoA 2: To file taxes, they use two-factor authentication (password + OTP).
• LoA 3: For higher-level services (e.g., applying for visas or accessing personal health records), users authenticate using a hardware token and biometric scan.

3. Corporate Systems

• LoA 1: Employees log in to check their work schedules using passwords.
• LoA 2: Employees access confidential internal documents requiring MFA (password + mobile push notification).
• LoA 3: Administrators modify system configurations requiring a password, hardware token, and location verification.

In the general settings of a realm, you can define which Authentication Context Class Reference (ACR) value is mapped to which Level of Authentication (LoA).

Key (ACR): Enter a string representing the authentication method or context. For example:

• "basic": Username and password.
• "mfa": Multi-factor authentication (e.g., password + OTP).
• "passwordless": Authentication without passwords (e.g., biometrics or magic links).

Value (LoA): Enter a numeric value representing the strength of the authentication method:

• 1: Basic authentication (low assurance).
• 2: Multi-factor authentication (medium assurance).
• 3: Passwordless or hardware token-based authentication (high assurance).

How to Use This Functionality?

1. Set the Mapping:

• Go to Realm Settings → General Settings.
• Under ACR to LoA Mapping, enter the ACRs and their corresponding LoAs.

2. To configure authentication flows in Keycloak that check the Level of Authentication (LoA) based on the mapped ACR, you need to set up authentication flows within the Keycloak admin console. These flows are used to determine the level of authentication required before granting access to a user.

Process to Configure Authentication Flows Based on ACR to LoA Mapping

1. Access Authentication Flows:

• In the Keycloak Admin Console, go to Authentication from the left-hand menu.
• Then, click on the Flows tab at the top of the page.

2. Create or Modify an Authentication Flow:

• Create a new flow or edit an existing flow to customize the authentication process.
• Click Add flow to create a new flow or click the Edit icon next to an existing flow if you want to modify it.

When configuring authentication flows in Keycloak, the two options you’re seeing — Basic Flow and Client Flow — are different types of authentication flows that serve specific purposes:

1. Basic Flow

• Purpose: This is the most commonly used flow, designed for general authentication scenarios.
• Use Case: It’s used for authenticating users through traditional means such as username/password, OTP, etc.
• Example: When a user tries to log in via the browser, this flow checks the username/password, may ask for OTP if multi-factor authentication (MFA) is enabled, and then grants access to the system.
• Common Flow Types: Login with username/password, OTP verification, password reset, etc.

Example Configuration:

• If the user tries to log in, they are first authenticated using their username and password (LoA 1). Then, if they are accessing a sensitive action, they are prompted for OTP (LoA 2).

2. Client Flow

• Purpose: This flow type is specifically designed for client-side applications (e.g., mobile apps, service-to-service authentication, etc.).
• Use Case: Used when a client (like a mobile app or an API) authenticates itself with Keycloak to obtain an access token (for OAuth or OpenID Connect flows).
• Example: When a mobile app needs to authenticate a user or request an access token to access backend APIs, a client flow is used.

Which One to Choose?

• Basic Flow: If you are working on user login and want to configure the authentication steps based on Level of Authentication (LoA), go with the Basic Flow. This is typically used for browser-based login scenarios where user credentials are involved.
• Client Flow: If you are working with client-side apps or API integrations (e.g., when your application needs to authenticate itself to access Keycloak or other resources), then you should use Client Flow.

For Basic Flow:

If you choose Basic Flow, you can then proceed to configure specific execution steps in the flow:

1. Add Executions: You can add execution steps like:

• Username/password form.
• OTP verification for multi-factor authentication (LoA 2).

For Client Flow:

The executions we listed in the Client Flow in Keycloak are methods for client authentication. These executions define how Keycloak validates the client (i.e., the application or service trying to authenticate) when it attempts to interact with Keycloak.

1. Client ID and Secret:

This is the most common method for authenticating clients. When a client application (like a web app or mobile app) needs to authenticate, it sends its client ID and client secret (like a username and password for the application).

• The client sends its client_id and client_secret either in the request parameters or in the Authorization header (using Basic authentication).
• A backend service that interacts with Keycloak to get an access token for accessing a protected API would authenticate using its client_id and client_secret.
• This is used when you want to authenticate using traditional client credentials (client ID + secret).

2. Signed JWT:

• In this method, the client uses a signed JSON Web Token (JWT) to authenticate. The JWT is signed with the client’s private key, and Keycloak will verify this signature using the client’s public key.
• The client generates a JWT that includes information like the client ID and some claims (additional information), signs it with its private key, and sends it to Keycloak. Keycloak verifies the signature using the public key that it already has for the client.
• A client application that wants to authenticate without sending sensitive credentials like a secret could use JWT. For example, a secure service-to-service communication where the client securely signs a JWT for authentication.
• This is useful when you want a more secure, token-based authentication that avoids sending secrets over the wire.

3. Signed JWT with Client Secret:

• This is a variation of the Signed JWT method, but here the client signs the JWT using its client secret instead of a private key.
• The client generates a JWT and signs it with the client secret. Keycloak will then verify this JWT against the client’s known secret.
• This is useful when you want to use a JWT-based authentication but prefer to use the client secret for signing instead of managing private keys. It is a simpler option for clients that don’t have access to private keys.
• This method is good if you want to authenticate using JWTs but still prefer using secrets over private keys.

4. X509 Certificate:

• This method allows a client to authenticate using a client certificate (an X.509 certificate).
• The client presents a certificate (which includes the client’s public key) during the authentication process, and Keycloak verifies the certificate against a list of trusted certificates. The client also proves its identity by signing with its private key.
• A high-security environment where client-server communication requires certificates. For example, an enterprise service using mutual TLS (mTLS) for secure authentication.
• This method is used when you want to authenticate clients in environments that rely on public key infrastructure (PKI), using certificates instead of passwords or secrets.

When to Use Each Execution in Client Flow:

• Client ID and Secret: Ideal for most client applications that require a straightforward and simple authentication method using a client ID and secret.
• Signed JWT: Use when you want a more secure, token-based authentication, and avoid sending the client secret in requests.
• Signed JWT with Client Secret: A hybrid solution that allows you to authenticate using a JWT while still signing it with the client secret. It provides a good balance between using tokens and keeping secrets secure.
• X509 Certificate: Use this in high-security environments where you want to authenticate clients using certificates (for example, in scenarios involving mTLS or strict identity verification).

By selecting the appropriate execution in the client flow, you can customize how your clients authenticate with Keycloak based on your security needs and requirements.

Summary

we discussed key login options and authentication configurations in Keycloak, which are crucial for enhancing security and user experience:

1. Forgot Password: This feature allows users to reset their passwords without contacting support. It helps improve user satisfaction and reduces support requests. If not configured, users may be unable to recover their accounts on their own, leading to frustration and possible abandonment of your app.
2. Remember Me: Enabling this feature allows users to stay logged in even after closing the browser, enhancing user convenience. Without it, users would need to log in repeatedly, which may lead to a less user-friendly experience.
3. ACR to LoA Mapping: This feature links Authentication Context Class Reference (ACR) values to Levels of Authentication (LoA). It allows systems to enforce varying levels of security, depending on the authentication method (e.g., username/password, multi-factor authentication). Without proper mapping, your application may not enforce appropriate security policies for different actions, potentially exposing sensitive data.
4. Authentication Flows: These define the sequence of authentication steps a user or client must complete. Flows such as Basic Flow (for general user login) and Client Flow (for service-to-service authentication) help secure access based on the required security level. Without customized flows, you might not be able to enforce multi-factor authentication or handle client-specific authentication properly, leading to security risks.

These configurations and features enhance both user experience and security. If not properly implemented, users may face difficulties like account recovery issues, repeated logins, or security risks due to insufficient authentication checks.

Once we have an admin account, you can configure realms in Keycloak. A realm is a space for managing users, applications, roles, and groups, and users belong to and log into a specific realm. One Keycloak installation can handle multiple realms.

Using the Admin Console

To configure realms and perform other administrative tasks, you use the Keycloak Admin Console.

Steps to Access the Admin Console:

1. Go to the Admin Console URL (e.g., for localhost: http://localhost:8080/admin/).
2. Log in with the admin username and password you created earlier.
3. Once logged in, you can:

• Select a realm to manage from the menu labeled Master or create a new one.

In the Admin Console, there are two types of realms:

1. Master Realm: This is the default realm created when you first set up Keycloak. It contains the administrator account you created during the initial login. The Master realm is only used for creating and managing other realms in your system.
2. Other Realms: These are realms created by an administrator within the Master realm. They are used to manage users and applications for your organization. Each realm can have its own set of users, roles, and applications, and applications are owned by the users within those realms.

we will create a realm to manage users and assign permissions for accessing applications. When you first log in, you start in the Master realm, which is the top-level realm. From there, you can create other realms to organize and manage users and applications.

1. Click Keycloak next to master realm, then click Create Realm.

2. Enter a name for the realm.

3. Click Create.

The current realm is now set to the realm we just created.

Configuring SSL for a realm

SSL (Secure Socket Layer) is a protocol used to encrypt data transmitted between a server and a client, ensuring that the communication remains secure. In the context of Keycloak and its realms, configuring SSL ensures that all communication between users and Keycloak (e.g., login, user management, and accessing protected applications) is encrypted and secure.

Why SSL is Important for a Realm

SSL encryption helps in protecting sensitive information such as passwords, user data, and authentication tokens from being intercepted during transmission. This is especially critical when Keycloak is used for authentication and authorization in production environments, as the data being exchanged could be highly sensitive.

SSL encryption ensures:

1. Data Privacy: All data between clients and the Keycloak server is encrypted, making it difficult for attackers to eavesdrop on communication.
2. Data Integrity: SSL ensures that the data being transmitted is not altered or tampered with during transit.
3. Authentication of the Server: SSL helps clients verify that they are communicating with the correct Keycloak server, preventing man-in-the-middle attacks.

How to Configure SSL for a Realm in Keycloak

1. Obtain an SSL Certificate: To enable SSL, you need an SSL certificate, which you can either purchase from a certificate authority (CA) or generate a self-signed certificate for testing purposes.
2. Install the Certificate on the Keycloak Server:

• For Keycloak to serve content over HTTPS, the certificate must be installed on the Keycloak server.
• You can modify the Keycloak configuration to enable HTTPS (using SSL) by updating the standalone.xml or application.properties (depending on your setup).
• Configure the HTTPS Settings:
• In the Keycloak Admin Console, under the realm settings, you can specify whether the realm should enforce HTTPS or accept both HTTP and HTTPS connections.
• You can also define the SSL redirect to ensure that users are always redirected to the HTTPS version of your site, enhancing security.
• Force HTTPS for Realm Communications: In your realm settings, you can choose to enforce secure connections, ensuring that all login, registration, and other communications are done over HTTPS.

What Happens If You Don’t Use SSL?

If you don’t configure SSL for your Keycloak realm, the data exchanged between users and the Keycloak server (and between the server and applications) will be sent in plain text. This introduces several risks:

1. Data Interception: Attackers can intercept sensitive data, such as usernames, passwords, and authentication tokens, by sniffing the traffic over unencrypted channels. This is especially risky when dealing with login credentials and sensitive user information.
2. Man-in-the-Middle Attacks: Without SSL, attackers can impersonate the Keycloak server and intercept or alter the communication between the client and the server. This could lead to unauthorized access or data corruption.

Steps to Configure SSL

1. Click Realm settings in the menu.
2. Click the General tab.

We can set the Require SSL option in Keycloak to one of these modes:

1. External requests: Keycloak allows non-SSL access only from private IP addresses (like localhost or local network addresses). If you try to access Keycloak from a public IP without SSL, you’ll get an error.
2. None: Keycloak does not require SSL. This is typically used for development or testing when you don’t need secure connections.
3. All requests: Keycloak requires SSL for all IP addresses, ensuring that all communication is encrypted.

Configure Email for realm

To configure email for a realm in Keycloak, you need to set up the SMTP server settings. This allows Keycloak to send emails for various purposes like verifying email addresses, password recovery, or notifying administrators about server events. By providing the SMTP server details, you enable Keycloak to send those emails to users.

For example, you would configure the SMTP settings to connect to your email server, specify the sender’s email address, and ensure that the email delivery process is secure and functional.

Steps:

1. Click Realm settings in the menu.
2. Click the Email tab.

To configure email settings in Keycloak, here’s a breakdown of what each option means:

1. From: This is the email address that appears as the sender of the emails from Keycloak, such as “noreply@example.com.”
2. From display name: This is an optional, user-friendly name that can be shown instead of the email address, like “Keycloak Support.” If not set, the plain email address will be shown.
3. Reply to: This is the email address that will be used when someone replies to an email from Keycloak. If not set, it will default to the “From” email address.
4. Reply to display name: Similar to the “From display name,” this is an optional, user-friendly name for the “Reply to” email address.
5. Envelope from: This is the bounce address, or the email address that will receive undelivered emails (optional).

Connection & Authentication Settings

1. Host: This is the SMTP server address that Keycloak will use to send emails, such as “smtp.example.com.”
2. Port: This is the port number for the SMTP server. For secure connections, you’ll typically use port 465 (SSL/TLS) or 587 (STARTTLS).
3. Encryption: Choose whether to use SSL or TLS to secure the email sending process. SSL/TLS is recommended, especially if you’re using an external SMTP server.
4. Authentication: If the SMTP server requires a username and password to send emails, enable this setting and provide the necessary credentials. The password can also be retrieved from a secure external vault.

Example

For instance, if you are using Gmail’s SMTP server, you would set:

• Host: smtp.gmail.com
• Port: 465 (SSL)
• From: noreply@example.com
• From display name: “Keycloak Support”
• Authentication: ON, with the Gmail username and app-specific password.

This setup would allow Keycloak to send emails securely using Gmail’s SMTP server.

Configure Theme

To configure themes in Keycloak and change the appearance of the UI for a specific realm, follow these steps:

1. Go to Realm Settings: In the Keycloak Admin Console, click on the Realm Settings option in the menu.
2. Click on the Themes Tab: Under the Realm Settings, click on the Themes tab. Here, you can choose and configure different themes for the UI elements in your realm.

This allows you to customize the look and feel of pages such as the login page, error pages, and account management pages to match your organization’s branding or style.

1. Click Realm setting in the menu.
2. Click the Themes tab.

To configure themes for different UI categories in Keycloak, follow these steps:

1. Login Theme: Select the theme you want for login-related screens such as username/password entry, OTP entry, and new user registration. This affects how the login pages appear to users.
2. Account Theme: Choose the theme for the console users will use to manage their account settings, like updating profile information or changing their password.
3. Admin Console Theme: Pick a theme for the Keycloak Admin Console, which is used by administrators to manage realms, users, and other configurations.
4. Email Theme: Select the theme for emails sent by Keycloak, such as password reset emails or account verification messages. The templates defined in this theme determine how the emails will look.

Once you choose the desired theme for each category, click Save to apply the changes. This customizes the appearance of the different parts of Keycloak based on your preferences.

Localization

To enable internationalization in Keycloak and support multiple languages, follow these steps:

1. Go to Realm Settings: In the Keycloak Admin Console, click on Realm Settings in the menu.
2. Click the Localization Tab: In the Realm Settings, click on the Localization tab.
3. Enable Internationalization: Toggle the option to Enable Internationalization. This will allow you to support multiple languages in your realm.
4. Select Supported Languages: Choose the languages you want to support for your UI screens. You can select multiple languages, and users will see Keycloak in their preferred language.

Once you save these settings, Keycloak will present the UI in the default or selected language based on user preferences. This makes the application accessible to a wider audience by supporting different languages.

Once you enable internationalization in Keycloak and select the supported languages, users can choose their preferred language the next time they log in. Here’s how it works:

1. User Login Page: When a user navigates to the login page, they will see a language selection option (like a dropdown or a language switcher). This allows them to choose the language they want to use for the login screens.
2. Account Console and Admin Console: After logging in, the selected language will also apply to the Account Console (where users manage their account settings) and Admin Console (for administrators managing the Keycloak server).

Summary:

We have configured Keycloak by setting up a realm, enabling themes, configuring email settings, and enabling internationalization (i18n) for a better user experience. First, we created and managed a realm where we could define users, roles, and applications. We then customized the appearance of Keycloak by selecting different themes for the login page, account console, admin console, and email templates. Additionally, we configured email settings to enable Keycloak to send verification and recovery emails by specifying SMTP server details. Finally, we enabled internationalization in the realm, allowing users to choose their preferred language during login.

Hope you enjoyed this article!

Clap 👏 If this article helps you.

See you all again soon!

Keycloak is a tool that makes it super easy for developers to add security features to their apps. Instead of coding everything from scratch, Keycloak gives you ready-made features for things like:

• Logging in and signing up users
• Managing user accounts
• Connecting to company directories like LDAP or Active Directory
• Using third-party logins like Google or Facebook

Example

Imagine you’re building an online shopping app. Without Keycloak, you’d have to write the code for:

1. User Login — Setting up forms, storing passwords securely, etc.
2. Social Login — If users want to log in with Google, you’d need to handle Google’s authentication process.
3. Password Management — Adding features like “Forgot Password” and “Change Password.”

With Keycloak:

1. Users see a customizable login screen provided by Keycloak.
2. If they want to sign in using Google or Facebook, Keycloak takes care of all the technical stuff for you.
3. Keycloak can even integrate with your company’s LDAP directory so employees can log in using their work accounts.

In short, Keycloak saves time and effort by providing all these security features out of the box while letting you tweak them to fit your app!

How KeyCloak Works:

Keycloak is like a security guard for your apps. It’s a separate server that handles user authentication and authorization. Here’s how it works:

1. Apps Point to Keycloak
   Your app (e.g., an online store or dashboard) connects to Keycloak for security. Keycloak uses standard protocols like OpenID Connect and SAML 2.0 to ensure secure communication.
2. When a user wants to log in:
3. The app redirects the user to Keycloak’s login page.
4. The user enters their credentials (like username and password).
5. Keycloak handles the login process and ensures the credentials are never seen by your app.
6. Once the user is authenticated, Keycloak gives the app a token (like a digital badge). This token is:

• Cryptographically signed to prevent tampering.
• Includes user information (e.g., username, email, roles).
• Can also include permissions (e.g., what the user can or cannot do).

7. Using the Token

• The app can use this token to personalize the user experience (e.g., showing their name).
• If the app needs to call a secure backend service (like fetching user orders), it sends the token along. The backend checks the token to verify the user and their permissions.

Core Concepts of Keycloak

1. Users
   Users are the people who log in to your app. They have details like email, username, or phone number and can belong to groups or have roles (e.g., Admin, Employee).
2. Authentication
   This is the process of confirming who the user is (e.g., entering a password).
3. Authorization
   This is about deciding what the user is allowed to do (e.g., access admin features).
4. Credentials
   Data used for authentication, like passwords, OTPs, or fingerprints.
5. Roles
   Categories for users (e.g., Admin, Manager) that define their permissions.
6. User Role Mapping
   Connecting a user to one or more roles. For example, assigning the “Manager” role to a user gives them permissions linked to that role.
7. Composite Roles
   A role that combines other roles. For instance, a “Superuser” role could include both “Admin” and “Manager” roles.
8. Groups
   Collections of users with shared attributes or roles. For example, all “Marketing Team” members can inherit common permissions.
9. Realms
   Separate spaces in Keycloak for managing users, roles, and groups. Each realm is independent (like having separate security zones for different apps).
10. Clients
    Applications or services that use Keycloak to authenticate users. For example, your web app or mobile app is a client.
11. Client Adapters
    Plugins that help your app work with Keycloak.
12. Consent
    Asking users for permission before sharing their data with an app. For example, showing what info (like email) an app will access.
13. Client Scopes
    Predefined settings for clients to simplify configurations.
14. Identity Token
    A token with user information (like name and email) given to an app after login.
15. Access Token
    A token that allows an app to access resources securely (e.g., fetch user data).
16. Service Account
    A built-in account for clients to obtain tokens.
17. Protocol Mappers
    Rules for customizing what user info is included in tokens (like email or roles).
18. User Federation Provider
    Connect Keycloak to existing user directories like LDAP or Active Directory.
19. Identity Provider (IDP)
    A service that authenticates users (e.g., Facebook or Google). Keycloak can also act as an IDP.
20. Identity Provider Federation
    Keycloak can delegate authentication to external IDPs, like enabling social logins.
21. Required Actions
    Actions users must complete during login, like resetting a password.
22. Authentication Flows
    Steps a user follows to log in or register (e.g., entering a password and completing CAPTCHA).
23. Events
    Logs that track what happens in Keycloak (e.g., user login attempts).
24. Themes
    Customizable templates and styles for Keycloak screens, like login or registration pages.

Example

In a company:

• Users are employees.
• Roles like “Admin” allow access to sensitive features.
• Groups like “HR” or “IT” manage permissions collectively.
• Keycloak connects to the company’s LDAP for login and delegates social login to Google for external partners.
• Apps use tokens to securely access resources without storing passwords directly.

Installing Keycloak:

1. Download Keycloak setup file from the official website.

2. Open bin folder:

3. Navigate your terminal to bin folder of keycloak. (Make sure you are running terminal as an administrator) & run .\kc.bat (Window Batch File)

4. You will get some commands to run:

5. Now run .\kc.bat start-dev to run dev server.

Now your Keycloak server is running.

6. After setup we will create first administrator account. After installing Keycloak, we need to create an admin account. This account has full control to manage everything in Keycloak. Using this account, you can:

• Log in to the Keycloak Admin Console.
• Set up realms (security zones).
• Add users.
• Register applications to secure them with Keycloak.

To access Keycloak:

* Open a web browser and go to http://localhost:8080.

* Enter a username and password that you can easily remember for future use.

Once you create user you got confirmation.

Now Open Adminstration console. you will see something like this:

If you need to create the admin account remotely or via the command line, follow these steps:

1. Set up environment variables for the admin account by running:

export KC_BOOTSTRAP_ADMIN_USERNAME=<username>
export KC_BOOTSTRAP_ADMIN_PASSWORD=<password>

• Replace <username> and <password> with the desired admin credentials.

2. Start Keycloak using the appropriate command for your system:

bin\kc.bat start

This will create the initial admin account that you can use to log in to the Keycloak Admin Console.

Summary :

We set up Keycloak by first installing it on the system and creating an admin account with full permissions to manage the platform. This was done either through the browser at http://localhost:8080 or by using environment variables and starting Keycloak via the command line.

Once the admin account was created, we started the Keycloak server using the appropriate command (kc.sh or kc.bat) to initialize it. With the setup complete, Keycloak is now ready for managing users, realms, and securing applications.

Hope you enjoyed this article!

Clap 👏 If this article helps you.

See you all again soon!

What is Keycloak?

Keycloak is an open-source identity and access management (IAM) solution. Open-source identity and access management (IAM) solution refers to a software platform that is manages User identities, which include details like usernames, passwords, email addresses, roles, and more.

• Example: When you log into a website using your email and password, the platform managing your credentials is handling identity management.

whereas access management controls what authenticated users are allowed to do once their identity is verified.

• Example: A system admin can access sensitive admin dashboards, but a regular user cannot. This restriction is enforced by access management.

It provides features such as:

• User Authentication: Supports login via username/password, social logins, or Single Sign-On (SSO) using SAML or OpenID Connect.
• Authorization: Role-based and attribute-based access control for securing applications.
• Admin Console: Allows managing users, roles, and permissions.
• Token Management: Issues and validates JSON Web Tokens (JWT) to secure communication between applications and services.

IAM Solution

• Identity and Access Management (IAM): A system that combines both identity and access management.
• Authentication: Validates a user’s identity.
• Authorization: Determines what resources the authenticated user is allowed to access.
• Single Sign-On (SSO): Lets users log in once to access multiple systems or services.
• Role-Based Access Control (RBAC): Assigns permissions based on user roles.
• Federated Identity: Allows integration with external identity providers (e.g., Google, Facebook).
• Session Management: Monitors and manages user sessions for enhanced security.

Examples of IAM Use Cases

1. E-commerce:

• Manage millions of users with different roles (buyers, sellers, admins).
• Use social login (Google, Facebook) for quick user authentication.

2. Corporate Applications:

• Enable employees to log in to multiple tools with a single account (SSO).
• Assign different permissions based on roles (e.g., HR, Finance, IT).

3. APIs:

• Secure APIs by issuing and verifying tokens (e.g., for mobile apps accessing backend services).

Keycloak as an open-source IAM solution makes it easy to handle all these scenarios efficiently and securely.

Keycloak is commonly used to secure modern applications (web, mobile, APIs) and provides SDKs and adapters for integration with various frameworks.

Implementing Keycloak with Fastify and TypeScript

To secure a Fastify application using Keycloak, we’ll use the fastify-keycloak-adapter package.

npm install fastify fastify-keycloak-adapter

What You Need Before Implementing Keycloak

Before integrating Keycloak into your Fastify application, you need to set up a few essential configurations and gather specific information. Here’s a detailed breakdown of the prerequisites:

Environment Variables Example

Set up a .env file to store sensitive data:

APP_ORIGIN=http://localhost:8888
KEYCLOAK_SERVER_URL=http://localhost:8080/realms/my-realm
KEYCLOAK_CLIENT_ID=client01
KEYCLOAK_CLIENT_SECRET=client01secret

So we are using bypassFn for Route Security.

Using bypassFn in KeycloakOptions allows you to define custom logic to bypass Keycloak protection for specific routes. Here's a step-by-step explanation and implementation:

1. Define Unprotected Routes in securityUtils.ts

You create a list of unprotected routes, specifying their URL, HTTP method, and optionally query parameters. For example:

export const unProtectedRoutes: { 
  url: string; 
  method: string; 
  queryParams?: Record<string, string>; 
}[] = [
  { url: '/public', method: 'GET' }, 
  { url: '/health', method: 'GET' }, 
  { url: '/status', method: 'GET', queryParams: { detail: 'basic' } },
];

2. Handle Route Security Logic

handleRouteSecurity checks if a request matches any of the defined unprotected routes. If it does, the route is bypassed, and Keycloak authentication is skipped.

import { FastifyRequest } from 'fastify';
import { unProtectedRoutes } from './securityUtils';

export const handleRouteSecurity = (request: FastifyRequest): boolean => {
  const query = (request.query as Record<string, string>) || {};

  return unProtectedRoutes.some((route) => {
    const isUrlMatch = route.url === request.routerPath;
    const isMethodMatch = route.method === request.method;

    if (isUrlMatch && isMethodMatch) {
      const isQueryParamsMatch =
        !route.queryParams || JSON.stringify(route.queryParams) === JSON.stringify(query);
      return isQueryParamsMatch;
    }

    return false;
  });
};

• URL Match: Compares the request’s URL (request.routerPath) to the route's url.
• Method Match: Compares the request’s method (request.method) to the route's method.
• Query Params Match: Optionally checks if query parameters match for the route.

Now go to your main file.

import fastify from 'fastify';
import keycloak, { KeycloakOptions } from 'fastify-keycloak-adapter';

const server = fastify();

// Environment variables
const opts: KeycloakOptions = {
  appOrigin: process.env.APP_ORIGIN as string, // Example: 'http://localhost:8888'
  keycloakSubdomain: process.env.KEYCLOAK_SERVER_URL as string, // Example: 'http://localhost:8080/realms/my-realm'
  clientId: process.env.KEYCLOAK_CLIENT_ID as string, // Example: 'client01'
  clientSecret: process.env.KEYCLOAK_CLIENT_SECRET as string, // Client secret from Keycloak
  bypassFn: (req) => handleRouteSecurity(req), // Optional: Define logic to bypass routes
};

// Register Keycloak plugin
server.register(keycloak, opts);

// Protected Route
server.get('/protected', { preValidation: server.keycloak.protect() }, async (request, reply) => {
  return {
    message: 'Access granted to protected route!',
    user: request.keycloak,
  };
});

// Public Route
server.get('/public', async (request, reply) => {
  return { message: 'This is a public route.' };
});

// Start Server
server.listen({ port: 8888 }, (err, address) => {
  if (err) {
    console.error(err);
    process.exit(1);
  }
  console.log(`Server running at ${address}`);
});

By default if token is not valid we will get unauthorised message in postman response. If you want to show custom message we will use unauthorizedHandler.

  const opts: KeycloakOptions = {
    appOrigin: process.env.APP_ORIGIN as string,
    keycloakSubdomain: process.env.KEYCLOAK_SERVER_URL as string,
    clientId: process.env.KEYCLOAK_CLIENT_ID as string,
    clientSecret: process.env.KEYCLOAK_CLIENT_SECRET as string,
    bypassFn: (req) => handleRouteSecurity(req),
    unauthorizedHandler: (request, reply) => {
      reply.status(401).send({
        statusCode: 401,
        error: "Unauthorized",
        message: "Access denied. You are not authorized to perform this action.",
      });
    },
  };

Testing

1. Run the Server

Start the Fastify server:

node index.js

2. Test with Postman

• Protected Route (/protected):
• Send a request with a valid JWT from Keycloak.
• Response: Access granted to protected route!.
• Public Route (/public):
• No authentication needed.
• Response: This is a public route.

Conclusion

This setup ensures a secure and flexible integration between Keycloak and Fastify, supporting modern authentication and access management requirements.