Re: [PATCH dart-api-client v2 2/2] fix #4281: access: add OpenID Connect auth-url/login helpers

["Shan Shaji" <s.shaji@proxmox.com>]

On Mon Aug 10, 2026 at 4:47 PM CEST, Azharul Haque wrote:
> 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})::')

    I know, you copied this regex from the handleAccessTicketResponse function. But IMHO,
    the first group don't need to match for PMG as well. It could just be PVE.

      final ticketRegex = RegExp(r'(PVE)(?: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();
    > +  }

  This block is common in both handleAccessTicketResponse and handleOpenIdLogiResponse
  functions. IMHO, we could seperate this into its own function.

> +  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)));
> +    });
>    });
>  }

If you would like to make the changes I mentioned, please feel free to do
that, else I can do it in a seperate series.