[PATCH 0/2] access: add OpenID Connect support for #4281

[PATCH 0/2] access: add OpenID Connect support for #4281

[Azharul Haque]

The native Flutter "Proxmox VE Companion" app never implemented OpenID
Connect / OAuth realm login (bug #4281[0]): selecting an OAuth realm
just showed username/password fields that could never work.

This series adds the API-layer building blocks for OIDC login:

  - a `type` property on PveAccessDomainModel, needed to detect
    OpenID realms in the login UI
  - helpers for PVE's /access/openid/auth-url and /access/openid/login
    endpoints

A companion series to proxmox_login_manager builds the login UI and
OAuth flow on top of this, and a companion series to
pve_flutter_frontend wires up the Android-side callback activity.

Verified end-to-end against a real PVE server with an Authentik OIDC
realm, on both Android and iOS.

[0] https://bugzilla.proxmox.com/show_bug.cgi?id=4281

Azharul Haque (2):
  fix #4281: access: add `type` property to `PveAccessDomainModel`
  fix #4281: access: add OpenID Connect auth-url/login helpers

 lib/src/authenticate.dart                   | 85 +++++++++++++++++++++
 lib/src/handle_ticket_response.dart         | 36 +++++++++
 lib/src/models/pve_access_domain_model.dart |  2 +
 test/test.dart                              | 20 +++++
 4 files changed, 143 insertions(+)

-- 
2.50.1 (Apple Git-155)

[PATCH 1/2] fix #4281: access: add `type` property to `PveAccessDomainModel`

[Azharul Haque]

The realm/domain list returned by /access/domains always includes a
`type` field (pam, pve, ldap, ad, openid, ...), but the model never
captured it. Without it, callers have no way to tell an OpenID Connect
realm apart from a password-based one, which is why the login form
falls back to showing username/password fields even for realms that
require a browser-based OpenID login.

Add the property and an `isOpenIdRealm` convenience getter, used by
the login form in the following commits.

Signed-off-by: Azharul Haque <haque@azharul.com>
---
 lib/src/models/pve_access_domain_model.dart | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/lib/src/models/pve_access_domain_model.dart b/lib/src/models/pve_access_domain_model.dart
index 6298bbe..a2fff31 100644
--- a/lib/src/models/pve_access_domain_model.dart
+++ b/lib/src/models/pve_access_domain_model.dart
@@ -7,12 +7,14 @@ abstract class PveAccessDomainModel
     implements Built<PveAccessDomainModel, PveAccessDomainModelBuilder> {
   // Fields
   String get realm;
+  String get type;
   String? get comment;
   String? get tfa;
   @BuiltValueField(wireName: 'default')
   int? get defaultValue;
 
   bool get isDefaultRealm => defaultValue == 1;
+  bool get isOpenIdRealm => type == 'openid';
 
   PveAccessDomainModel._();
 
-- 
2.50.1 (Apple Git-155)

[PATCH 2/2] fix #4281: access: add OpenID Connect auth-url/login helpers

[Azharul Haque]

Add openIdAuthUrl() and openIdLogin(), mirroring the existing
authenticate()/accessDomains() functions used by the login form
before an authenticated ProxmoxApiClient exists.

openIdAuthUrl() requests the provider's authorization URL for a
realm from /access/openid/auth-url. openIdLogin() exchanges the
state/code obtained from the provider's redirect for a PVE ticket
via /access/openid/login, the same way authenticate() does for
password realms.

The OpenID login response carries the authenticated username in its
body rather than it being known upfront by the caller, so
handleOpenIdLoginResponse() is added alongside the existing
handleAccessTicketResponse()/handleTfaChallengeResponse() to build
Credentials from it.

Signed-off-by: Azharul Haque <haque@azharul.com>
---
 lib/src/authenticate.dart           | 85 +++++++++++++++++++++++++++++
 lib/src/handle_ticket_response.dart | 36 ++++++++++++
 test/test.dart                      | 20 +++++++
 3 files changed, 141 insertions(+)

diff --git a/lib/src/authenticate.dart b/lib/src/authenticate.dart
index 7bd9cef..e2d76a1 100644
--- a/lib/src/authenticate.dart
+++ b/lib/src/authenticate.dart
@@ -72,6 +72,91 @@ Future<ProxmoxApiClient> authenticate(
   }
 }
 
+/// Requests the provider's authorization URL for an OpenID Connect realm.
+///
+/// [redirectUrl] must match a redirect URI registered with the realm's
+/// OpenID provider, and is where the provider sends the user back to after
+/// they authenticate (carrying `state` and `code` query parameters).
+Future<String> openIdAuthUrl(
+  String realm,
+  Uri apiBaseUrl,
+  Uri redirectUrl,
+  bool validateSSL, {
+  http.Client? httpClient,
+}) async {
+  httpClient ??= getCustomIOHttpClient(validateSSL: validateSSL);
+
+  var body = {
+    'realm': realm,
+    'redirect-url': redirectUrl.toString(),
+  };
+
+  try {
+    final path = '/api2/json/access/openid/auth-url';
+    final response = await httpClient
+        .post(apiBaseUrl.replace(path: path), body: body)
+        .timeout(Duration(seconds: 25));
+
+    response.validate(true);
+
+    return jsonDecode(response.body)['data'] as String;
+  } on NSErrorClientException catch (e) {
+    if (e.error.code == -1202) {
+      throw HandshakeException(e.message);
+    }
+    rethrow;
+  } on http.ClientException catch (e) {
+    if (e.message.contains('net::ERR_CERT_AUTHORITY_INVALID')) {
+      throw HandshakeException(e.message);
+    }
+    rethrow;
+  }
+}
+
+/// Exchanges the `state`/`code` obtained from the OpenID provider's redirect
+/// for a Proxmox VE ticket, mirroring what [authenticate] does for password
+/// realms.
+Future<ProxmoxApiClient> openIdLogin(
+  String state,
+  String code,
+  Uri apiBaseUrl,
+  Uri redirectUrl,
+  bool validateSSL, {
+  http.Client? httpClient,
+}) async {
+  httpClient ??= getCustomIOHttpClient(validateSSL: validateSSL);
+
+  var body = {
+    'state': state,
+    'code': code,
+    'redirect-url': redirectUrl.toString(),
+  };
+
+  try {
+    final path = '/api2/json/access/openid/login';
+    final response = await httpClient
+        .post(apiBaseUrl.replace(path: path), body: body)
+        .timeout(Duration(seconds: 25));
+
+    final credentials = handleOpenIdLoginResponse(response, apiBaseUrl);
+
+    return ProxmoxApiClient(
+      credentials,
+      httpClient: httpClient,
+    );
+  } on NSErrorClientException catch (e) {
+    if (e.error.code == -1202) {
+      throw HandshakeException(e.message);
+    }
+    rethrow;
+  } on http.ClientException catch (e) {
+    if (e.message.contains('net::ERR_CERT_AUTHORITY_INVALID')) {
+      throw HandshakeException(e.message);
+    }
+    rethrow;
+  }
+}
+
 Future<List<PveAccessDomainModel?>> accessDomains(
   Uri apiBaseUrl,
   bool validateSSL, {
diff --git a/lib/src/handle_ticket_response.dart b/lib/src/handle_ticket_response.dart
index ba2128f..a43aed0 100644
--- a/lib/src/handle_ticket_response.dart
+++ b/lib/src/handle_ticket_response.dart
@@ -39,6 +39,42 @@ Credentials handleAccessTicketResponse(
   );
 }
 
+Credentials handleOpenIdLoginResponse(
+    http.Response response, Uri apiBaseUrl) {
+  response.validate(false);
+
+  final bodyJson = jsonDecode(response.body)['data'];
+
+  final ticket = bodyJson['ticket'];
+
+  final csrfToken = bodyJson['CSRFPreventionToken'];
+
+  final username = bodyJson['username'];
+
+  final ticketRegex = RegExp(r'(PVE|PMG)(?:QUAR)?:(?:(\S+):)?([A-Z0-9]{8})::')
+      .firstMatch(bodyJson['ticket'])!;
+
+  final time = DateTime.fromMillisecondsSinceEpoch(
+      int.parse(ticketRegex.group(3)!, radix: 16) * 1000);
+
+  TfaChallenge? tfa;
+  if (ticket.startsWith('PVE:!tfa!')) {
+    tfa = TfaChallenge.fromJson(
+        jsonDecode(Uri.decodeComponent(ticket.substring(9).split(':')[0])));
+  } else if (bodyJson['NeedTFA'] != null && bodyJson['NeedTFA'] == 1) {
+    tfa = TfaChallenge.legacy();
+  }
+
+  return Credentials(
+    apiBaseUrl,
+    username,
+    ticket: ticket,
+    csrfToken: csrfToken,
+    expiration: time,
+    tfa: tfa,
+  );
+}
+
 Credentials handleTfaChallengeResponse(
     http.Response response, Credentials pendingTfaCredentials) {
   response.validate(false);
diff --git a/test/test.dart b/test/test.dart
index 23368a2..86c2272 100644
--- a/test/test.dart
+++ b/test/test.dart
@@ -49,5 +49,25 @@ void main() {
                   DateTime.fromMillisecondsSinceEpoch(
                       int.parse('5DF8EC22', radix: 16) * 1000)));
     });
+
+    test('valid openid login response extraction', () {
+      final ticket =
+          'PVE:jdoe@keycloak:5DF8EC22::STV4HNO1wplmsyMDM5s6SUsU4cS7sBBBw+HOCEhSSV+6WGtz3zwIzHqBhq/ziJoBs7NqqyLXG4wn9jXJCMdYht+ndqwxtdFQsUNOF1Q/eTWwcyl+Q1fmPNOIIUoxMY8OqGBVozgIimiAJxdqm+2SJnrPEmlJge6m3yf/OEVAkKFCfRMOtSuyVnIbuLx6h6obvezBUP5+ZHzeTMmmXcH4rOsOKgW9XfwryLHbkjjq9Ennx0xjQaBD9Bo5ERquY0hNmWcdPC/p7ZzILTr4xH9sJe9Na2z6GhgJyTgOCAMengyIegySMq7IKIkmsp8odF4/iIC3005/XLF4w/DjPYQUMA==';
+      final csrfToken = '5DF8EDEC:/bb44xdHyVQDo2eD/8ty0WVXwMgwt1HjhVHLZX2YbxQ';
+      var response = http.Response(
+          '{"data":{"clustername":"testcluster","username":"jdoe@keycloak","CSRFPreventionToken":"5DF8EDEC:/bb44xdHyVQDo2eD/8ty0WVXwMgwt1HjhVHLZX2YbxQ","cap":{},"ticket":"$ticket"}}',
+          200);
+      expect(
+          handleOpenIdLoginResponse(response, dummyEndpoint),
+          isA<Credentials>()
+              .having((e) => e.username, 'Username', 'jdoe@keycloak')
+              .having((e) => e.ticket, 'Ticket', ticket)
+              .having((e) => e.csrfToken, 'CSRF Token', csrfToken)
+              .having(
+                  (e) => e.expiration,
+                  'Token expiration time',
+                  DateTime.fromMillisecondsSinceEpoch(
+                      int.parse('5DF8EC22', radix: 16) * 1000)));
+    });
   });
 }
-- 
2.50.1 (Apple Git-155)