Expose the current iOS/Android CredentialManager configurations on the Flutter SDK as well

[farhad-ris]

Checklist

• I have looked into the Readme, Examples, and FAQ and have not found a suitable solution or answer.
• I have looked into the API documentation and have not found a suitable solution or answer.
• I have searched the issues and have not found a suitable solution or answer.
• I have searched the Auth0 Community forums and have not found a suitable solution or answer.
• I agree to the terms within the Auth0 Code of Conduct.

Describe the problem you'd like to have solved

🛠️ Proposal: Native CredentialsManager Configuration Support in auth0_flutter

We’d like to propose a change to the auth0_flutter SDK that would allow teams to securely share tokens across native extensions/widgets (e.g. iOS home screen widgets, Android slices) by enabling native CredentialsManager configuration directly from Flutter.

---

📌 Intent

We’re using the auth0_flutter SDK to manage authentication within our Flutter app, which also includes a native iOS home screen widget.

For both seamless UX and security, the widget must access the same Auth0 credentials (e.g. access_token, refresh_token) obtained by the main app — without requiring reauthentication (which isn’t supported in widget contexts).

To comply with Apple’s recommended approach, the app stores credentials using:

SimpleKeychain(accessGroup: "group.com.company.shared")

This works great with the native Swift SDK, but the current Flutter SDK lacks support for configuring this behavior — making it difficult to securely integrate with widgets or extensions.

---

🧠 Use Case

• ✅ The iOS app logs the user in via Auth0 and stores tokens using CredentialsManager (via Flutter SDK).
• ✅ A native widget, part of the same App Group, needs to read those credentials via the native iOS SDK.
• ✅ When tokens expire, both app and widget rely on CredentialsManager to auto-refresh using the refresh_token.

This is achievable today by manually creating a native CredentialsManager like:

CredentialsManager(
  authentication: Auth0.authentication(),
  storage: SimpleKeychain(accessGroup: ...)
)

But currently, there’s no way to do this via the Flutter SDK.

---

🔧 Proposed Enhancement

We propose adding a way to pass native CredentialsManager configurations when creating the Auth0 instance in Flutter:

Option 1 – With embedded platformConfig

final auth0 = Auth0(
  domain,
  clientId,
  credentialsManager: DefaultCredentialsManager(
    platformConfig: CredentialsManagerPlatformConfig(
      ios: IOSCredentialsConfig(
        accessGroup: 'group.com.company.shared',
        storeKey: 'custom_key',
        accessibility: 'afterFirstUnlock',
      ),
      android: AndroidCredentialsConfig(
        sharedPreferencesName: 'auth_prefs',
        encrypted: true,
      ),
    ),
  ),
);

Option 2 – With separate platform configs

final auth0 = Auth0(
  domain,
  clientId,
  iOSConfig: IOSCredentialsManagerConfig(
    accessGroup: "group.com.myapp.shared",
    storeKey: "credentials",
    accessibility: KeychainAccessibility.unlocked,
  ),
  androidConfig: AndroidCredentialsManagerConfig(
    sharedPrefsName: "auth0",
    keyAlias: "auth_key",
  ),
);

On iOS, this would map to:

CredentialsManager(
  authentication: Auth0.authentication(),
  storage: SimpleKeychain(
    accessGroup: ...,
    accessibility: ...
  ),
  storeKey: ...
)

On Android, this could hook into SharedPreferences or EncryptedSharedPreferences similarly.

---

✅ Benefits

• 🔐 Secure token sharing between app + widgets/extensions.
• 🍏 Native iOS support for App Groups and Keychain sharing.
• ♻️ Auto-refresh support from both app and extension contexts.
• 🩼 No need to fork or wrap the Flutter SDK.
• 🔄 Fully backward-compatible (defaults to current behavior if config is omitted).

---

📊 Visual Comparison

We've included 3 diagrams showing the trade-offs:

❌ Not a Good Solution

Tokens are stored separately on the Flutter and native layers — two isolated Keychains make syncing fragile.

---

⚠️ A Better Workaround

A custom CredentialsManager is built using a platform channel to delegate storage to the native SDK. The native SDK then uses a shared accessGroup.

---

✅ The Best Solution

Flutter directly configures the native SDK via auth0_flutter. No platform channel plumbing, and native SDKs work as intended.

➡️ The third approach is ideal, but it requires the Flutter SDK to expose native configuration options — which is the enhancement we’re proposing.

---

Thanks again for the excellent SDK and all your hard work!

Describe the ideal solution

🔧 Proposed Enhancement

We propose adding a way to pass native CredentialsManager configurations when creating the Auth0 instance in Flutter:

Option 1 – With embedded platformConfig

final auth0 = Auth0(
  domain,
  clientId,
  credentialsManager: DefaultCredentialsManager(
    platformConfig: CredentialsManagerPlatformConfig(
      ios: IOSCredentialsConfig(
        accessGroup: 'group.com.company.shared',
        storeKey: 'custom_key',
        accessibility: 'afterFirstUnlock',
      ),
      android: AndroidCredentialsConfig(
        sharedPreferencesName: 'auth_prefs',
        encrypted: true,
      ),
    ),
  ),
);

Option 2 – With separate platform configs

final auth0 = Auth0(
  domain,
  clientId,
  iOSConfig: IOSCredentialsManagerConfig(
    accessGroup: "group.com.myapp.shared",
    storeKey: "credentials",
    accessibility: KeychainAccessibility.unlocked,
  ),
  androidConfig: AndroidCredentialsManagerConfig(
    sharedPrefsName: "auth0",
    keyAlias: "auth_key",
  ),
);

On iOS, this would map to:

CredentialsManager(
  authentication: Auth0.authentication(),
  storage: SimpleKeychain(
    accessGroup: ...,
    accessibility: ...
  ),
  storeKey: ...
)

On Android, this could hook into SharedPreferences or EncryptedSharedPreferences similarly.

---

✅ The Best Solution

Flutter directly configures the native SDK via auth0_flutter. No platform channel plumbing, and native SDKs work as intended.

Alternatives and current workarounds

⚠️ A Better Workaround

A custom CredentialsManager is built using a platform channel to delegate storage to the native SDK. The native SDK then uses a shared accessGroup.

Additional context

Currently Auth0 iOS and Android SDKs seem to have these CredentialManager configurations but are not exposed on the Flutter SDK.

This change would help Flutter apps that also have native widgets/extensions to share the same token easily

[Widcket]

Hi @farhad-ris, thanks for the thoughtful and detailed feature request. We'll look into this and get back to you. By the way, @pmathew92 would be the point of contact for the feature.