Clarify OIDC vs. client secret auth guidance in Azure Insights docs

[CamSoper]

Summary

This PR clarifies the authentication options for configuring Pulumi Insights with Azure, addressing confusion where the documentation claimed to use OIDC but actually described client secret authentication.

Changes

File Modified:

• content/docs/insights/discovery/get-started/begin.md

What Changed:

• Replaced misleading Azure section that claimed to use OIDC but showed client secret setup
• Now presents both authentication options clearly upfront
• Added explicit recommendation to use OIDC for best practices (passwordless, more secure, no long-lived credentials)
• Provided correct OIDC ESC configuration example with oidc: true and proper environment variables
• Added note directing users to comprehensive accounts documentation for complete setup instructions
• Ensures consistency with how other cloud providers (AWS) reference detailed guides

Root Cause

The original documentation:

1. Stated "you will use OpenID Connect (OIDC)" (line 104)
2. Then described creating a Service Principal with a client secret (lines 106-110)
3. Showed ESC configuration using clientSecret, not OIDC (lines 114-131)

This mismatch confused users who expected OIDC instructions but got client secret setup instead.

Solution

The new documentation:

1. Clearly presents both authentication options upfront
2. Recommends OIDC as the best practice
3. Shows correct OIDC configuration example
4. Briefly mentions client secret as an alternative
5. Directs users to comprehensive documentation for detailed setup steps

Benefits

• Users understand that OIDC is recommended for Azure authentication
• Clear distinction between OIDC and client secret authentication
• No more misleading instructions
• Better alignment with security best practices
• Consistent with how other providers are documented

Testing

• ✅ make lint - All checks passed
• ✅ make build - Site builds successfully
• ✅ Pre-commit hooks passed
• ✅ Link to /docs/insights/discovery/accounts/#azure verified

Fixes

Closes #15812

---

🤖 Generated with Claude Code

[claude]

Documentation Review

This PR successfully addresses the confusion between OIDC and client secret authentication for Azure in the Pulumi Insights documentation. The changes are clear, accurate, and well-structured.

✅ Strengths

• Clear distinction: The two authentication options are now presented upfront with a clear recommendation for OIDC
• Accurate examples: The OIDC configuration example correctly uses oidc: true and appropriate environment variables
• Proper linking: The reference to /docs/insights/discovery/accounts/#azure is valid and provides users with comprehensive setup instructions
• Style compliance: Follows ordered list conventions (all items start with 1.), proper heading case, and appropriate use of the notes shortcode
• Consistent terminology: "passwordless authentication" aligns with usage in related documentation

✅ No Issues Found

All content meets the repository's style guidelines:

• Headings follow sentence case (H2+)
• Lists use correct numbering format
• Links are descriptive and resolve correctly
• Spelling and grammar are correct
• No jargon or complex sentences
• Specific and provides examples
• File ends with a newline

✅ Technical Accuracy

• OIDC configuration example is correct
• Security recommendation is appropriate
• Link to comprehensive guide provides proper escape hatch for detailed instructions
• Consistent with how other cloud providers are documented in this file

---

Status: ✅ Approved - No changes needed. This PR is ready to merge.

Mention me ('@claude') if you'd like additional reviews or have questions about any feedback.

[pulumi-bot]

Your site preview for commit 6f04e8f is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16329-6f04e8f3.s3-website.us-west-2.amazonaws.com.

[jkodroff]

I can't vouch for the technical correctness of the content, but the formatting and verbiage looks fine.

[pulumi-bot]

Your site preview for commit 028b70e is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16329-028b70e1.s3-website.us-west-2.amazonaws.com.