IAM: integrating the Flutter app

How the mobile app signs users in to Astra and calls the API. The local stack (make k3d-up) serves the API and the Keycloak login page from one origin, http://localhost:8080 by default.

What the app talks to

{BASE} is the value of ASTRA_PUBLIC_URL that the cluster was started with. Keycloak writes it into every token as the issuer, and the server rejects tokens from any other issuer. The app must therefore reach the stack through exactly that origin.

Reaching the laptop from a device

The local stack is plain HTTP. Allow it in debug builds only:

• Android: pass allowInsecureConnections: true to flutter_appauth requests, and allow cleartext traffic to the dev host with a debug-only network_security_config.xml.
• iOS: add NSAppTransportSecurity → NSAllowsLocalNetworking = YES to the debug Info.plist. If token calls to a LAN IP are still blocked, add a debug-only exception for that host.

Flutter setup

# pubspec.yaml
dependencies:
  flutter_appauth: ^12.1.0
  flutter_secure_storage: ^11.2.0
  http: ^1.6.0

Android, android/app/build.gradle:

android {
  defaultConfig {
    manifestPlaceholders += [appAuthRedirectScheme: 'io.astra.mobile']
  }
}

iOS, ios/Runner/Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array><string>io.astra.mobile</string></array>
  </dict>
</array>

Sign in, register, refresh, sign out

import 'dart:convert';
import 'package:flutter_appauth/flutter_appauth.dart';
import 'package:flutter_secure_storage/flutter_secure_storage.dart';
import 'package:http/http.dart' as http;

class AstraAuth {
  AstraAuth(this.base); // e.g. 'http://localhost:8080'
  final String base;
  final _appAuth = const FlutterAppAuth();
  final _store = const FlutterSecureStorage();

  static const clientId = 'astra-mobile';
  static const redirect = 'io.astra.mobile:/oauthredirect';
  static const scopes = ['openid', 'profile', 'email', 'offline_access'];
  String get discovery => '$base/auth/realms/astra/.well-known/openid-configuration';

  /// Opens the Astra login page. Set [register] to open the sign-up form instead.
  Future<void> signIn({String locale = 'vi', bool register = false}) async {
    final r = await _appAuth.authorizeAndExchangeCode(AuthorizationTokenRequest(
      clientId, redirect,
      discoveryUrl: discovery,
      scopes: scopes,
      additionalParameters: {
        'ui_locales': locale,
        if (register) 'prompt': 'create',
      },
      allowInsecureConnections: true, // local HTTP stack only
    ));
    await _save(r.accessToken, r.refreshToken, r.idToken);
  }

  /// Exchanges the refresh token. Call on 401, and after joining a tenant or a role change.
  Future<bool> refresh() async {
    final rt = await _store.read(key: 'refresh_token');
    if (rt == null) return false;
    try {
      final r = await _appAuth.token(TokenRequest(clientId, redirect,
          discoveryUrl: discovery, refreshToken: rt, scopes: scopes,
          allowInsecureConnections: true));
      await _save(r.accessToken, r.refreshToken ?? rt, r.idToken);
      return true;
    } catch (_) {
      await _store.deleteAll(); // refresh token expired or revoked: sign in again
      return false;
    }
  }

  Future<void> signOut() async {
    final idToken = await _store.read(key: 'id_token');
    await _appAuth.endSession(EndSessionRequest(
      idTokenHint: idToken,
      postLogoutRedirectUrl: redirect,
      discoveryUrl: discovery,
      allowInsecureConnections: true,
    ));
    await _store.deleteAll();
  }

  Future<String?> accessToken() => _store.read(key: 'access_token');

  Future<void> _save(String? at, String? rt, String? idt) async {
    await _store.write(key: 'access_token', value: at);
    await _store.write(key: 'refresh_token', value: rt);
    await _store.write(key: 'id_token', value: idt);
  }
}

/// Calls the Astra API with the bearer token and tenant header; retries once after a refresh on 401.
class AstraApi {
  AstraApi(this.auth, {this.tenant});
  final AstraAuth auth;
  String? tenant;

  Future<http.Response> send(String method, String path, {Object? body}) async {
    Future<http.Response> once() async {
      final req = http.Request(method, Uri.parse('${auth.base}$path'))
        ..headers['Authorization'] = 'Bearer ${await auth.accessToken()}'
        ..headers['Content-Type'] = 'application/json';
      if (tenant != null) req.headers['X-Astra-Tenant'] = tenant!;
      if (body != null) req.body = jsonEncode(body);
      return http.Response.fromStream(await req.send());
    }
    var res = await once();
    if (res.statusCode == 401 && await auth.refresh()) res = await once();
    return res;
  }
}

After sign-in

1. Call GET /api/iam/me. It returns the user's profile, platformAdmin, and a tenants list. Each entry holds the user's roles in that tenant and the effective permissions per DocType, for example {"Article": {"read": true, "create": true, "write": "own"}}. Use these to show or hide actions. The server enforces the same rules either way.
2. If tenants is empty, the user just self-registered. Join the app's tenant with POST /api/iam/tenants/{tenant}/join, or let the user pick one from GET /api/iam/tenants/public. The user joins as reader. The response contains "refreshToken": true. Call refresh() before using the tenant, because the current access token was issued before the join.
3. If the user belongs to several tenants, send X-Astra-Tenant on every document call.

Role changes made by a tenant admin reach the user's token at the next refresh, within 5 minutes.

API reference

Tenant roles are admin, editor, author and reader. For Article, admins and editors can read, create and write everything. Authors can read and create, and can write only their own documents. Readers can only read. A platform admin manages tenants and members but gets no document access unless also made a member.

Errors are JSON {"error": "..."}:

Seeded local accounts

All seeded accounts use the password Astra@123. They exist only in the local realm export.

acme allows public sign-up and globex does not. The Keycloak admin console is at {BASE}/auth/admin (user admin; the password is in the astra-keycloak secret).

Not in this release

Forgot-password by email (no SMTP yet), MFA, social login, and filtering drafts out of readers' lists.

Troubleshooting

• "Invalid parameter: redirect_uri": the app's redirect must be exactly io.astra.mobile:/oauthredirect.
• 401 on every API call right after sign-in: the app reached the stack through a different origin than ASTRA_PUBLIC_URL, so the token issuer does not match. Compare iss in the token with /api/iam/config.
• 403 "not a member of tenant ..." after joining: refresh the token first.
• Run the checks: scripts/demo-iam.sh http://localhost:8080 exercises all of the above with real tokens.