Skip to content

Add credential-free-dev skill#196

Open
ArLucaID wants to merge 2 commits intomicrosoft:mainfrom
ArLucaID:credential-free-dev-skill
Open

Add credential-free-dev skill#196
ArLucaID wants to merge 2 commits intomicrosoft:mainfrom
ArLucaID:credential-free-dev-skill

Conversation

@ArLucaID
Copy link
Copy Markdown
Contributor

Core skill for eliminating secrets from Azure apps using managed identities, workload identity federation, and Azure Identity SDK.

What's included

  • SKILL.md (155 lines): Core principles, credential type decision table, DefaultAzureCredential chain, RBAC role quick reference, WIF patterns, common pitfalls
  • references/migration-patterns.md: Before/after migration code for Azure SQL, Storage, Cosmos DB, Service Bus, Event Hubs, Key Vault, App Configuration across Python, .NET, TypeScript, Java
  • references/acceptance-criteria.md: Correct/incorrect patterns for auth, client init, RBAC, MI selection, WIF
  • tests/scenarios/credential-free-dev/scenarios.yaml: 6 test scenarios, 100% pass rate
  • Symlinks in python/dotnet/typescript/java/rust entra categories
  • README.md updated: total 132->133, Core 9->10, test coverage updated

Test results

Scenarios: 6 | Passed: 6 | Pass Rate: 100.0% | Average Score: 100.0

…ranting

Addresses 6 gaps in the entra-agent-id skill:

1. Runtime token exchange — Added fmi_path two-step exchange pattern (parent
   token via client_credentials + fmi_path, then client_assertion exchange for
   Graph-scoped Agent Identity token). Covers both autonomous (app-only) and
   OBO (delegated) modes with complete code samples.

2. fmi_path parameter — Documented the fmi_path parameter on the standard
   /oauth2/v2.0/token endpoint that targets a specific Agent Identity. Clarified
   this is NOT RFC 8693 token exchange (which returns AADSTS82001).

3. OBO/delegated flow — Added Blueprint API configuration (identifierUris,
   oauth2PermissionScopes, preAuthorizedApplications, optionalClaims), user
   token audience requirements, and complete OBO exchange code.

4. Cross-tenant guidance — Documented that fmi_path works cross-tenant when
   the Blueprint is multi-tenant. Critical rule: step 1 must target the Agent
   Identity's home tenant, not the Blueprint's (AADSTS700211 otherwise).

5. Permission granting — Added appRoleAssignments for autonomous mode and
   oauth2PermissionGrants for OBO mode, with per-agent scoping examples.

6. oauth2-token-flow.md completion — Option B now shows the full two-step
   exchange (was incomplete — stopped at Blueprint token). Added Option C for
   OBO flow. Added cross-tenant exchange section.

Updated acceptance-criteria.md with sections 9-12 covering runtime exchange,
OBO, cross-tenant, and permission grant patterns (correct/incorrect examples).

Added Troubleshooting table with 8 common errors and fixes.

Tested patterns verified against live Entra endpoints (same-tenant autonomous,
cross-tenant fmi_path exchange, OBO with delegated permissions).
Core skill for eliminating secrets from Azure apps using managed identities, workload identity federation, and Azure Identity SDK.

- SKILL.md (155 lines) with principles, credential type table, RBAC roles, WIF patterns

- references/migration-patterns.md: before/after code for 7 services, 4 languages

- references/acceptance-criteria.md: correct/incorrect patterns

- 6 test scenarios, 100% pass rate

- Symlinks in python/dotnet/typescript/java/rust entra categories
@ArLucaID
Copy link
Copy Markdown
Contributor Author

@thegovind / @spboyer : Could I get some help in merging this one? I don't have permissions to request reviewers.

@thegovind
Copy link
Copy Markdown
Collaborator

@ArLucaID - Could you resolve the merge conflict?

Copy link
Copy Markdown
Collaborator

@thegovind thegovind left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review summary

The credential-free-dev skill content is solid (good RBAC table, clean migration guidance, correct DAC chain). But the PR has a few real blockers around scope/branch hygiene, broken symlinks, and a direct conflict with PR #199's auth guidance.

Issues

🔴 Blocking

1. Scope creep — two skills bundled into one PR

The PR title is "Add credential-free-dev skill" but the branch contains three commits, including two for entra-agent-id:

  • cdb4bfc — Add entra-agent-id skill
  • 72a5710 — feat: Add runtime token exchange to entra-agent-id
  • b68f0ce — Add credential-free-dev skill (the actual PR)

Result: 13 files change, ~800 of the 1669 added lines belong to a different skill that's covered by PR #195. Please rebase b68f0ce onto main (or wait for entra-agent-id PRs to merge first) so this PR carries only the credential-free-dev commit.

2. Symlinks in skills/{python,dotnet,java,rust,typescript}/entra/credential-free-dev are committed as plain text files, not symlinks

$ file skills/python/entra/credential-free-dev
skills/python/entra/credential-free-dev: ASCII text, with no line terminators

The file just contains the literal string ../../../.github/skills/credential-free-dev. Compare to a working sibling:

lrwxr-xr-x   azure-identity      -> ../../../.github/skills/azure-identity-py
-rw-r--r--   credential-free-dev   ❌ regular file

Fix:

for lang in python dotnet java rust typescript; do
  rm "skills/$lang/entra/credential-free-dev"
  (cd "skills/$lang/entra" && ln -s ../../../.github/skills/credential-free-dev credential-free-dev)
done
git add skills/

This usually happens when the file is staged/committed on Windows or via the GitHub web editor — please verify after the fix that git ls-tree HEAD skills/python/entra/credential-free-dev reports mode 120000, not 100644.

3. Direct conflict with PR #199 on the production-auth recommendation

This PR (line 26 of credential-free-dev/SKILL.md) teaches:

"DefaultAzureCredential is the standard entry point. Unified credential chain that works locally and in production (managed identity) without code changes."

PR #199 (same author, same area) reverses this and recommends ManagedIdentityCredential in production, citing the Azure SDK best-practices doc that explicitly warns against DefaultAzureCredential in production due to credential-chain probing, latency, and silent fallback. Two skills landing simultaneously with contradictory production guidance is bad for the catalog.

Please decide which is canonical and reconcile both PRs before merge. If #199 is the intended final state, this skill needs the same treatment (or should land after #199 with consistent wording).

🟡 Recommended

  • entra-agent-id/SKILL.md L53 regression: <your-tenant-id> was changed to <your tenant-id> (hyphen → space). Same finding I left on #195 — please drop that hunk.
  • README.md test totals. The PR bumps Core to 8 skills / 78 scenarios (+6 from tests/scenarios/credential-free-dev/scenarios.yaml), but the global totals row and the per-language rows should be re-summed by tests/ rather than hand-edited. Worth running the test harness or counting script after rebase.

🟢 Nits

  • SKILL.md "Common Pitfall #5" links to managed-identities-status — fine, but consider also linking the canonical "services that support Microsoft Entra authentication" page; that's the more actionable list when someone is migrating off keys.
  • "Stepping stone" wording for Key Vault references is terse — consider: "Intermediate step — secrets in Key Vault rather than config; not the end state."
  • The migration-patterns reference is the right structure, but make sure the per-service code blocks specify the non-async path for languages where folks copy-paste in scripts (e.g., Python sync BlobServiceClient alongside aio variant).

Once the branch is rebased and the symlinks are fixed, the skill content itself looks good to merge — pending the #199 reconciliation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants