10. REL-ID Update Password Flow

🎯 Learning Path:

Complete REL-ID Complete Activation & Login Flow Codelab
Complete REL-ID Additional Device Activation Flow Codelab
You are here → Update Password Flow Implementation (Post-Login)

Welcome to the REL-ID Update Password codelab! This tutorial builds upon your existing MFA implementation to add secure user-initiated password update capabilities using REL-ID SDK's credential management APIs.

What You'll Build

In this codelab, you'll enhance your existing MFA application with:

🔐 Post-Login Password Update: User-initiated password change from dashboard with challengeMode = 2 (RDNA_OP_UPDATE_CREDENTIALS)
📋 Credential Availability Detection: Automatic detection using getAllChallenges() API and onCredentialsAvailableForUpdate event
🎯 Conditional Menu Display: Show "Update Password" only when credential is available for update
📝 Three-Field Password Form: Current password, new password, and confirm password validation with focus management
🔄 Screen-Level Event Handling: Proper onUpdateCredentialResponse event handling with cleanup
⚠️ SDK Event Chain Management: Handle automatic onUserLoggedOff → getUser events for status codes 110/153

What You'll Learn

By completing this codelab, you'll master:

Credential Availability Check: Post-login detection using getAllChallenges() API
Update Flow Initiation: Triggering password update with initiateUpdateFlowForCredential('Password') API
Drawer Navigation Integration: Conditional menu item rendering based on credential availability
UpdatePassword API Integration: Implementing updatePassword(current, new, RDNA_OP_UPDATE_CREDENTIALS) with challengeMode 2
Password Policy Extraction: Parsing RELID_PASSWORD_POLICY from challenge data
Screen-Level Event Management: onUpdateCredentialResponse handler with proper cleanup
SDK Event Chain Handling: Managing automatic logout events for specific status codes
Focus Management: Proper FocusNode implementation for multi-field forms

Prerequisites

Before starting this codelab, ensure you have:

✅ Completed REL-ID MFA Complete Activation & Login Flow Codelab - All MFA screens and flows must be fully implemented
✅ Flutter Development Environment - Flutter SDK, Android Studio/VS Code configured
✅ REL-ID SDK Integration - Latest SDK with credential management APIs
✅ Dart Knowledge - Understanding of Dart classes and type safety patterns
✅ Drawer Navigation Setup - Drawer navigation configured with Dashboard screen
✅ Server Configuration - REL-ID server with password update credential enabled

Get the Code from GitHub

The code to get started can be found in a GitHub repository.

You can clone the repository using the following command:

git clone https://github.com/uniken-public/codelab-flutter.git

Navigate to the relid-MFA-update-password folder in the repository you cloned earlier

Codelab Architecture Overview

This codelab extends your MFA application with five core password update components:

UpdatePasswordScreen: Three-field password form with policy display and focus management in drawer navigation
Credential Availability Detection: getAllChallenges() API integration after login with onCredentialsAvailableForUpdate event handler
Update Flow Initiation: initiateUpdateFlowForCredential('Password') API to trigger password update from drawer menu
Conditional Menu Rendering: Dynamic drawer menu based on onCredentialsAvailableForUpdate event
Screen-Level Event Handling: onUpdateCredentialResponse handler with automatic cleanup and SDK event chain management

Before implementing password update functionality, let's understand the key SDK events and APIs that power the user-initiated password update workflow (post-login).

Update Password Event Flow

The password update process follows this event-driven pattern:

User Logs In Successfully → getAllChallenges() Called →
onCredentialsAvailableForUpdate Event → Drawer Menu Shows "Update Password" →
User Taps Menu Item → initiateUpdateFlowForCredential('Password') →
getPassword Event (challengeMode=2) → UpdatePasswordScreen Displays →
User Updates Password → updatePassword(current, new, RDNA_OP_UPDATE_CREDENTIALS) →
onUpdateCredentialResponse (statusCode 110/153) →
SDK Triggers onUserLoggedOff → getUser Event → Navigation to Login

Challenge Mode 2 vs Challenge Mode 4

It's crucial to understand the difference between user-initiated update and password expiry:

Challenge Mode	Use Case	Trigger	User Action	Screen Location
`challengeMode = 2`	User-initiated password update (post-login)	User taps "Update Password" menu	Provide current + new password	Drawer Navigation
`challengeMode = 4`	Password expiry during login	Server detects expired password	Provide current + new password	Stack Navigation
`challengeMode = 0`	Password verification for login	User attempts to log in	Enter password	Stack Navigation
`challengeMode = 1`	Set new password during activation	First-time activation	Create password	Stack Navigation

Credential Availability Detection Flow

Post-login password update requires credential availability check:

Step	API/Event	Description
1. User Login	`onUserLoggedIn` event	User successfully completes MFA login
2. Credential Check	`getAllChallenges(username)` API	Check which credentials are available for update
3. Availability Event	`onCredentialsAvailableForUpdate` event	SDK returns list of updatable credentials (e.g., `["Password"]`)
4. Menu Display	Conditional rendering	Show "Update Password" menu item if `options` includes "Password"
5. User Initiates	`initiateUpdateFlowForCredential('Password')` API	User taps menu item to start update flow
6. SDK Triggers	`getPassword` event with `challengeMode = 2`	SDK requests password update
7. Screen Display	UpdatePasswordScreen	Show three-field password form in drawer

Core Update Password APIs and Events

The REL-ID SDK provides these APIs and events for password update:

API/Event	Type	Description	User Action Required
`getAllChallenges(username)`	API	Check available credential updates after login	System calls automatically
`onCredentialsAvailableForUpdate`	Event	Receives list of updatable credentials	System stores in state
`initiateUpdateFlowForCredential(type)`	API	Initiate update flow for specific credential	User taps menu item
`getPassword` (challengeMode=2)	Event	Password update request with policy	User provides passwords
`updatePassword(current, new, mode)`	API	Submit password update	User submits form
`onUpdateCredentialResponse`	Event	Password update result with status codes	System handles response

Password Policy Extraction

Password update flow uses the standard policy key:

Flow	Policy Key	Description
Password Creation (challengeMode=1)	`RELID_PASSWORD_POLICY`	Policy for new password creation
Password Update (challengeMode=2)	`RELID_PASSWORD_POLICY`	Policy for user-initiated password update
Password Expiry (challengeMode=4)	`RELID_PASSWORD_POLICY`	Policy for expired password update

SDK Event Chain - Critical Status Codes

When onUpdateCredentialResponse receives these status codes, the SDK automatically triggers onUserLoggedOff → getUser event chain:

Status Code	Meaning	SDK Behavior	Action Required
`statusCode = 110`	Password has expired while updating	SDK triggers `onUserLoggedOff` → `getUser`	Clear fields, user must re-login
`statusCode = 153`	Attempts exhausted	SDK triggers `onUserLoggedOff` → `getUser`	Clear fields, user logs out
`statusCode = 190`	Password does not meet policy	No automatic logout but triggers `getPassword`	Clear fields, display error

Drawer Navigation vs Stack Navigation

Update Password flow uses Drawer navigation, not Stack navigation:

Screen	Navigation Type	Reason	Access Method
UpdatePasswordScreen	Drawer Navigation	Post-login feature, conditional access	Menu item in drawer
UpdateExpiryPasswordScreen	Stack Navigation	Login-blocking feature, forced update	Automatic SDK navigation
SetPasswordScreen	Stack Navigation	Activation flow, first-time setup	Automatic SDK navigation
VerifyPasswordScreen	Stack Navigation	Login flow, authentication	Automatic SDK navigation

Screen-Level Event Handler Pattern

Update password uses screen-level event handling with cleanup:

// UpdatePasswordScreen - Screen-level event handler
void _setupEventHandlers() {
  final eventManager = _rdnaService.getEventManager();

  // Set handler when screen initializes
  eventManager.setUpdateCredentialResponseHandler((data) {
    // Process status codes 110, 153
    // SDK will trigger onUserLoggedOff → getUser after this
  });
}

@override
void dispose() {
  // Cleanup when screen unmounts
  _rdnaService.getEventManager().setUpdateCredentialResponseHandler(null);
  super.dispose();
}

Let's implement the credential management APIs in your service layer following established REL-ID SDK patterns.

Step 1: Add getAllChallenges API

Add this method to

lib/uniken/services/rdna_service.dart

// lib/uniken/services/rdna_service.dart (addition to existing class)

/// Get all available challenges for credential updates
///
/// This API checks which credentials are available for update after successful login.
/// Call this immediately after onUserLoggedIn event to populate the drawer menu with
/// available credential update options.
///
/// See: https://developer.uniken.com/docs/getallchallenges
///
/// Workflow:
/// 1. User logs in successfully (onUserLoggedIn event)
/// 2. Call getAllChallenges(username) immediately after login
/// 3. SDK checks server for available credential updates
/// 4. SDK triggers onCredentialsAvailableForUpdate event
/// 5. Event handler receives options list (e.g., ["Password", "PIN"])
/// 6. App displays conditional menu items in drawer
///
/// Response Validation Logic:
/// 1. Check error.longErrorCode: 0 = success, > 0 = error
/// 2. On success, triggers onCredentialsAvailableForUpdate event
/// 3. On failure, credentials update unavailable
/// 4. Async event will be handled by SDKEventProvider
///
/// @param username The username to check credential availability
/// @returns Future<RDNASyncResponse> that resolves with sync response structure
Future<RDNASyncResponse> getAllChallenges(String username) async {
  print('RdnaService - Getting all available challenges for user: $username');

  final response = await _rdnaClient.getAllChallenges(username);

  print('RdnaService - GetAllChallenges sync response received');
  print('RdnaService - Sync response:');
  print('  Long Error Code: ${response.error?.longErrorCode}');
  print('  Short Error Code: ${response.error?.shortErrorCode}');

  return response;
}

Step 2: Add initiateUpdateFlowForCredential API

Add this method to

lib/uniken/services/rdna_service.dart

// lib/uniken/services/rdna_service.dart (addition to existing class)

/// Initiate update flow for a specific credential
///
/// This API triggers the SDK to start the credential update flow for a specific type.
/// Call this when user taps "Update Password" menu item in drawer.
/// The SDK will respond with getPassword event (challengeMode=2).
///
/// See: https://developer.uniken.com/docs/initiateupdateflowforcredential
///
/// Workflow:
/// 1. User taps "Update Password" menu item
/// 2. Call initiateUpdateFlowForCredential('Password')
/// 3. SDK processes request
/// 4. SDK triggers getPassword event with challengeMode=2
/// 5. SDKEventProvider navigates to UpdatePasswordScreen in drawer
/// 6. User provides current and new passwords
///
/// Response Validation Logic:
/// 1. Check error.longErrorCode: 0 = success, > 0 = error
/// 2. On success, triggers getPassword event with challengeMode=2
/// 3. On failure, update flow cannot be initiated
/// 4. Async event will be handled by SDKEventProvider
///
/// @param credentialType The credential type to update (e.g., "Password", "PIN")
/// @returns Future<RDNASyncResponse> that resolves with sync response structure
Future<RDNASyncResponse> initiateUpdateFlowForCredential(String credentialType) async {
  print('RdnaService - Initiating update flow for credential: $credentialType');

  final response = await _rdnaClient.initiateUpdateFlowForCredential(credentialType);

  print('RdnaService - InitiateUpdateFlowForCredential sync response received');
  print('RdnaService - Sync response:');
  print('  Long Error Code: ${response.error?.longErrorCode}');
  print('  Short Error Code: ${response.error?.shortErrorCode}');

  return response;
}

Step 3: Add updatePassword API with challengeMode 2

Add this method to

lib/uniken/services/rdna_service.dart

// lib/uniken/services/rdna_service.dart (addition to existing class)

/// Updates password for user-initiated password update (Post-Login)
///
/// This method is specifically used for user-initiated password updates after login.
/// When user taps "Update Password" in drawer and enters passwords, this API
/// submits the password update request with challengeMode=RDNA_OP_UPDATE_CREDENTIALS.
/// Uses async/await pattern for Flutter SDK integration.
///
/// See: https://developer.uniken.com/docs/updating-other-credentials
///
/// Workflow:
/// 1. User taps "Update Password" menu item (post-login)
/// 2. initiateUpdateFlowForCredential('Password') called
/// 3. SDK triggers getPassword with challengeMode=2
/// 4. App displays UpdatePasswordScreen in drawer
/// 5. User provides current and new passwords
/// 6. App calls updatePassword(current, new, RDNA_OP_UPDATE_CREDENTIALS)
/// 7. SDK validates and updates password
/// 8. SDK triggers onUpdateCredentialResponse event
/// 9. On statusCode 110/153, SDK auto-triggers onUserLoggedOff → getUser
///
/// Response Validation Logic:
/// 1. Check error.longErrorCode: 0 = success, > 0 = error
/// 2. On success, triggers onUpdateCredentialResponse event
/// 3. On failure, may trigger getPassword again with error status
/// 4. StatusCode 100 = Success
/// 5. StatusCode 110 = Password expired (SDK triggers logout)
/// 6. StatusCode 153 = Attempts exhausted (SDK triggers logout)
/// 7. StatusCode 190 = Policy violation (no automatic logout)
/// 8. Async events will be handled by screen-level handler
///
/// @param currentPassword The user's current password
/// @param newPassword The new password to set
/// @param challengeMode Challenge mode (should be RDNA_OP_UPDATE_CREDENTIALS for mode 2)
/// @returns Future<RDNASyncResponse> that resolves with sync response structure
Future<RDNASyncResponse> updatePassword(
  String currentPassword,
  String newPassword,
  RDNAChallengeOpMode challengeMode
) async {
  print('RdnaService - Updating password (challengeMode: $challengeMode)');

  final response = await _rdnaClient.updatePassword(
    currentPassword,
    newPassword,
    challengeMode
  );

  print('RdnaService - UpdatePassword sync response received');
  print('RdnaService - Sync response:');
  print('  Long Error Code: ${response.error?.longErrorCode}');
  print('  Short Error Code: ${response.error?.shortErrorCode}');

  return response;
}

Step 4: Verify Service Layer Integration

Ensure these imports exist in

lib/uniken/services/rdna_service.dart

import 'package:rdna_client/rdna_client.dart';
import '../types/rdna_events.dart';

Verify your service class exports all methods:

class RdnaService {
  // Existing MFA methods...

  // ✅ New credential management methods
  Future<RDNASyncResponse> getAllChallenges(String username) async { /* ... */ }
  Future<RDNASyncResponse> initiateUpdateFlowForCredential(String credentialType) async { /* ... */ }
  Future<RDNASyncResponse> updatePassword(String currentPassword, String newPassword, RDNAChallengeOpMode challengeMode) async { /* ... */ }
}

Now let's enhance your SDKEventProvider to handle credential availability detection and password update routing.

Step 1: Add Dart Type Definitions

Ensure these types exist in

lib/uniken/types/rdna_events.dart

// lib/uniken/types/rdna_events.dart (additions)

/// Credentials Available for Update Event Data
/// Triggered after getAllChallenges() API call
class RDNACredentialsAvailableForUpdate {
  final String? userID;
  final List<String>? options; // List of updatable credentials: ["Password", "PIN", etc.]

  RDNACredentialsAvailableForUpdate({
    this.userID,
    this.options,
  });

  factory RDNACredentialsAvailableForUpdate.fromJson(Map<String, dynamic> json) {
    return RDNACredentialsAvailableForUpdate(
      userID: json['userID'] as String?,
      options: (json['options'] as List<dynamic>?)?.cast<String>(),
    );
  }
}

/// Update Credential Response Event Data
/// Triggered after updatePassword() API call
class RDNAUpdateCredentialResponse {
  final String? userId;
  final String? credType; // "Password", "PIN", etc.
  final RDNAStatus? status;
  final RDNAError? error;

  RDNAUpdateCredentialResponse({
    this.userId,
    this.credType,
    this.status,
    this.error,
  });

  factory RDNAUpdateCredentialResponse.fromJson(Map<String, dynamic> json) {
    return RDNAUpdateCredentialResponse(
      userId: json['userId'] as String?,
      credType: json['credType'] as String?,
      status: json['status'] != null ? RDNAStatus.fromJson(json['status']) : null,
      error: json['error'] != null ? RDNAError.fromJson(json['error']) : null,
    );
  }
}

// Callback type definitions
typedef RDNACredentialsAvailableForUpdateCallback = void Function(RDNACredentialsAvailableForUpdate);
typedef RDNAUpdateCredentialResponseCallback = void Function(RDNAUpdateCredentialResponse);

Step 2: Add Event Handlers to rdnaEventManager

Enhance

lib/uniken/services/rdna_event_manager.dart

// lib/uniken/services/rdna_event_manager.dart (additions)

class RdnaEventManager {
  // Existing callbacks...

  // ✅ New callback properties
  RDNACredentialsAvailableForUpdateCallback? _credentialsAvailableForUpdateHandler;
  RDNAUpdateCredentialResponseCallback? _updateCredentialResponseHandler;

  // ✅ New event listener methods
  void _onCredentialsAvailableForUpdate(dynamic credentialsData) {
    print('RdnaEventManager - Credentials available for update event received');

    final data = credentialsData as RDNACredentialsAvailableForUpdate;
    print('RdnaEventManager - Available options: ${data.options}');

    if (_credentialsAvailableForUpdateHandler != null) {
      _credentialsAvailableForUpdateHandler!(data);
    }
  }

  void _onUpdateCredentialResponse(dynamic updateData) {
    print('RdnaEventManager - Update credential response event received');

    final response = updateData as RDNAUpdateCredentialResponse;
    print('RdnaEventManager - Update credential response:');
    print('  userId: ${response.userId}');
    print('  credType: ${response.credType}');
    print('  statusCode: ${response.status?.statusCode}');
    print('  statusMessage: ${response.status?.statusMessage}');

    if (_updateCredentialResponseHandler != null) {
      _updateCredentialResponseHandler!(response);
    }
  }

  // ✅ New setter methods
  void setCredentialsAvailableForUpdateHandler(RDNACredentialsAvailableForUpdateCallback? callback) {
    _credentialsAvailableForUpdateHandler = callback;
  }

  void setUpdateCredentialResponseHandler(RDNAUpdateCredentialResponseCallback? callback) {
    _updateCredentialResponseHandler = callback;
  }

  // ✅ Register listeners in _registerEventListeners()
  void _registerEventListeners() {
    // Existing listeners...

    _listeners.add(
      _rdnaClient.on(RdnaClient.onCredentialsAvailableForUpdate, _onCredentialsAvailableForUpdate),
    );
    _listeners.add(
      _rdnaClient.on(RdnaClient.onUpdateCredentialResponse, _onUpdateCredentialResponse),
    );
  }

  void cleanup() {
    // Existing cleanup...
    _credentialsAvailableForUpdateHandler = null;
    _updateCredentialResponseHandler = null;
  }
}