Azure / Azure/azure-sdk-for-cpp

[azure-core-amqp] Preserve structured CBS failures through token refresh retries

Open
#7,379 0 comments 0 reactions 0 assignees View on GitHub
needs-triage
Dominant language
C++
Stars
205
Forks
172
Avg merge
1d 3h
Merged PRs (30d)
37

Description

## Summary

`RefreshTokenForAudience` catches every standard exception and retains only `what()`. The refresh scheduler therefore cannot distinguish credential acquisition, CBS open, put-token refusal, transport failure, timeout, and shutdown cancellation. It can only retry every failure with the same policy and write an unstructured warning.

Issue #7330 covers the low-level ambiguity where `PutTokenForAudience` raises `AuthenticationException` for every non-`Ok` CBS result. This issue carries structured failure information through the refresh worker after the low-level result has been classified. Rust transport parity is outside this issue.

## Proposal

Introduce an internal refresh outcome that records:

- The failed stage: credential acquisition, CBS open, put-token, or cleanup.
- The CBS operation result and service status when available.
- Whether the failure is retryable on the same connection.
- Whether a fresh connection is required.
- Whether the operation ended because of caller cancellation or connection shutdown.

Use the outcome rather than exception text to select the next refresh action. Transport errors, timeouts, throttling, and retryable service failures may retain the current authorization and schedule another attempt. An explicit credential or claim rejection remains a permanent authentication result after the bounded fresh-connection probe in the Event Hubs layer.

Preserve exception text for diagnostics, but do not parse it to make a retry decision. Logs may include the audience, connection instance, failure stage, attempt number, remaining token lifetime, and next delay. They must never include the token.

## Validation

- [ ] Each credential and CBS failure stage produces a distinct internal outcome.
- [ ] Cancellation and shutdown are not logged or scheduled as ordinary retryable failures.
- [ ] CBS service status and description survive to the final actionable exception when available.
- [ ] Retry decisions do not inspect exception text.
- [ ] Logs state the retry decision and next delay without exposing token material.
- [ ] Tests cover transient transport failure, explicit authorization refusal, timeout, cancellation, and unknown exception paths.

This issue changes authentication failure handling and requires explicit security-focused review.

Contributor guide

Open the contributing guide

Research direction

Start by tracing RefreshTokenForAudience through credential acquisition, CBS open, PutTokenForAudience, and cleanup, then inspect how the Event Hubs layer consumes the result. Use the validation checklist to define completion: distinct outcomes, preserved CBS status, non-text-based retry decisions, correct cancellation handling, and tests for each listed failure path without logging token material.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure, cpp
Domain
authentication, security
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
32/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.