docs: add README.md for PPDS.Auth package#29
Conversation
Required for NuGet package publishing (PackageReadmeFile). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Summary of ChangesHello @joshsmithxrm, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request resolves a critical issue that prevented the Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds a README.md file for the PPDS.Auth package. The README provides a good overview of the library's features. However, almost all of the code examples are incorrect and do not align with the actual API surface provided in the C# source files. This includes invalid constructor calls, incorrect method signatures, usage of non-existent methods and properties, and logically flawed examples. These errors are critical, especially in the Quick Start and Custom Credential Provider sections, as they will prevent users from successfully using the library. I have provided detailed comments and suggestions to correct these examples throughout the file.
| // 1. Create and store a profile | ||
| var store = new ProfileStore(); | ||
| var profile = new AuthProfile("dev") | ||
| { | ||
| AuthMethod = AuthMethod.InteractiveBrowser, | ||
| ClientId = "51f81489-12ee-4a9e-aaae-a2591f45987d" // Default Power Platform client | ||
| }; | ||
| await store.SaveAsync(profile); | ||
|
|
||
| // 2. Authenticate and get a ServiceClient | ||
| var provider = CredentialProviderFactory.Create(profile); | ||
| var client = await ServiceClientFactory.CreateAsync(provider, profile); |
There was a problem hiding this comment.
The Quick Start example contains several errors that will prevent a user from getting started successfully. It appears to be based on an outdated or incorrect version of the API.
new AuthProfile("dev")is not a valid constructor.AuthProfileshould be initialized using an object initializer likenew AuthProfile { Name = "dev" }.store.SaveAsyncexpects aProfileCollection, but is called with a singleAuthProfile.ServiceClientFactory.CreateAsyncis not a valid static method. To get aServiceClient, you should useprovider.CreateServiceClientAsync(environmentUrl).- The example is missing the environment URL, which is a required parameter.
This suggestion corrects the code to align with the library's API.
| // 1. Create and store a profile | |
| var store = new ProfileStore(); | |
| var profile = new AuthProfile("dev") | |
| { | |
| AuthMethod = AuthMethod.InteractiveBrowser, | |
| ClientId = "51f81489-12ee-4a9e-aaae-a2591f45987d" // Default Power Platform client | |
| }; | |
| await store.SaveAsync(profile); | |
| // 2. Authenticate and get a ServiceClient | |
| var provider = CredentialProviderFactory.Create(profile); | |
| var client = await ServiceClientFactory.CreateAsync(provider, profile); | |
| // 1. Create a profile | |
| var profile = new AuthProfile | |
| { | |
| Name = "dev", | |
| AuthMethod = AuthMethod.InteractiveBrowser, | |
| ClientId = "51f81489-12ee-4a9e-aaae-a2591f45987d" // Default Power Platform client | |
| }; | |
| // 2. Authenticate and get a ServiceClient | |
| var provider = CredentialProviderFactory.Create(profile); | |
| var client = await provider.CreateServiceClientAsync("https://your-org.crm.dynamics.com"); |
| ```csharp | ||
| public class CustomCredentialProvider : ICredentialProvider | ||
| { | ||
| public string Name => "Custom"; | ||
| public bool RequiresInteraction => false; | ||
|
|
||
| public Task<string> GetTokenAsync(string resource, CancellationToken ct) | ||
| { | ||
| // Your custom token acquisition logic | ||
| return Task.FromResult("your-token"); | ||
| } | ||
|
|
||
| public Task<TokenInfo> GetTokenInfoAsync(CancellationToken ct) | ||
| { | ||
| return Task.FromResult(new TokenInfo | ||
| { | ||
| UserPrincipalName = "user@example.com", | ||
| TenantId = "..." | ||
| }); | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
The example for implementing ICredentialProvider is incorrect and does not match the interface definition. The ICredentialProvider interface requires implementing properties like AuthMethod and the method CreateServiceClientAsync, not GetTokenAsync or GetTokenInfoAsync.
A correct, minimal implementation would look something like this:
public class CustomCredentialProvider : ICredentialProvider
{
public AuthMethod AuthMethod => AuthMethod.InteractiveBrowser; // Or a custom value if you extend the enum
public string? Identity { get; private set; }
public DateTimeOffset? TokenExpiresAt { get; private set; }
public string? TenantId { get; private set; }
public string? ObjectId { get; private set; }
public string? AccessToken { get; private set; }
public System.Security.Claims.ClaimsPrincipal? IdTokenClaims { get; private set; }
public async Task<ServiceClient> CreateServiceClientAsync(
string environmentUrl,
CancellationToken cancellationToken = default,
bool forceInteractive = false)
{
// Your custom token acquisition logic to get a token string
var token = "your-token";
this.AccessToken = token;
this.Identity = "user@example.com";
var client = new ServiceClient(
new Uri(environmentUrl),
_ => Task.FromResult(token),
useUniqueInstance: true);
if (!client.IsReady)
{
throw new Exception("Failed to connect");
}
return client;
}
public void Dispose() { /* Cleanup */ }
}| var store = new ProfileStore(); | ||
|
|
||
| // Save a profile | ||
| await store.SaveAsync(profile); |
There was a problem hiding this comment.
The SaveAsync method on ProfileStore expects a ProfileCollection object, not a single AuthProfile. To save a new profile, you should first load the existing collection, add the new profile to it, and then save the collection.
|
|
||
| ```csharp | ||
| // Interactive Browser (opens browser for OAuth) | ||
| var profile = new AuthProfile("dev") |
There was a problem hiding this comment.
AuthProfile does not have a constructor that accepts a name. This should be initialized using an object initializer, e.g., new AuthProfile { Name = "dev", ... }. This issue is repeated in all subsequent examples in this section.
| AuthMethod = AuthMethod.AzureDevOpsFederated, | ||
| ApplicationId = "your-app-id", | ||
| TenantId = "your-tenant-id", | ||
| AzureDevOpsServiceConnectionId = "service-connection-id" |
There was a problem hiding this comment.
The AzureDevOpsServiceConnectionId property does not exist on the AuthProfile class. The credential provider for Azure DevOps retrieves this information from environment variables, so this line should be removed.
| var resolver = new EnvironmentResolver(discovery, provider.GetTokenAsync); | ||
|
|
||
| // By URL | ||
| var env = await resolver.ResolveAsync("https://org.crm.dynamics.com"); | ||
|
|
||
| // By unique name | ||
| var env = await resolver.ResolveAsync("org"); | ||
|
|
||
| // By environment ID | ||
| var env = await resolver.ResolveAsync("00000000-0000-0000-0000-000000000000"); | ||
|
|
||
| // By partial friendly name (fuzzy match) | ||
| var env = await resolver.ResolveAsync("Production"); |
There was a problem hiding this comment.
This example for environment resolution is incorrect. EnvironmentResolver is a static class and does not have a constructor or an ResolveAsync method. You should first get a list of environments and then pass it to the static EnvironmentResolver.Resolve method.
| var resolver = new EnvironmentResolver(discovery, provider.GetTokenAsync); | |
| // By URL | |
| var env = await resolver.ResolveAsync("https://org.crm.dynamics.com"); | |
| // By unique name | |
| var env = await resolver.ResolveAsync("org"); | |
| // By environment ID | |
| var env = await resolver.ResolveAsync("00000000-0000-0000-0000-000000000000"); | |
| // By partial friendly name (fuzzy match) | |
| var env = await resolver.ResolveAsync("Production"); | |
| // First, get the list of available environments | |
| var discovery = new GlobalDiscoveryService(); | |
| var environments = await discovery.GetEnvironmentsAsync(); | |
| // Then, resolve a specific environment from the list | |
| // By URL | |
| var envByUrl = EnvironmentResolver.Resolve(environments, "https://org.crm.dynamics.com"); | |
| // By unique name | |
| var envByUniqueName = EnvironmentResolver.Resolve(environments, "org"); | |
| // By environment ID | |
| var envById = EnvironmentResolver.Resolve(environments, "00000000-0000-0000-0000-000000000000"); | |
| // By partial friendly name (fuzzy match) | |
| var envByFriendlyName = EnvironmentResolver.Resolve(environments, "Production"); |
| var profile = profiles.GetActiveProfile(); | ||
|
|
||
| var provider = CredentialProviderFactory.Create(profile); | ||
| var source = new ProfileConnectionSource(profile, provider); |
There was a problem hiding this comment.
The constructor for ProfileConnectionSource is incorrect. It does not accept an ICredentialProvider. You should use the static factory method ProfileConnectionSource.FromProfile(profile), which requires the profile to have an environment selected.
| var source = new ProfileConnectionSource(profile, provider); | |
| var source = ProfileConnectionSource.FromProfile(profile); |
| var profile = new AuthProfile("dev") | ||
| { | ||
| TokenCacheType = TokenCacheType.Persistent // Default | ||
| // TokenCacheType = TokenCacheType.InMemory // Per-process only | ||
| }; |
There was a problem hiding this comment.
This example is incorrect. The AuthProfile class does not have a TokenCacheType property. Additionally, the TokenCacheType enum does not contain a Persistent value. Token caching is handled internally by the credential providers and is persistent by default where possible. This section should probably be removed or corrected to explain the automatic caching behavior.
| // - CloudEnvironment.UsNat | ||
| // - CloudEnvironment.UsSec |
There was a problem hiding this comment.
The list of supported clouds includes UsNat and UsSec, which are not defined in the CloudEnvironment enum. These should be removed to reflect the actual supported clouds.
|
|
||
| Secrets (client secrets, passwords, etc.) are encrypted at rest: | ||
| - **Windows**: DPAPI (user-scoped encryption) | ||
| - **Linux/macOS**: Base64 encoding (use OS-level file permissions) |
There was a problem hiding this comment.
Describing the non-Windows encryption as 'Base64 encoding' is misleading. ProfileEncryption.cs shows it uses XOR obfuscation with a machine-specific key, and then Base64 encodes the result. It would be more accurate to describe this as 'simple obfuscation' to avoid giving the impression that secrets are stored in plain Base64.
| - **Linux/macOS**: Base64 encoding (use OS-level file permissions) | |
| - **Linux/macOS**: Simple obfuscation (use OS-level file permissions) |
There was a problem hiding this comment.
Pull request overview
This PR adds a README.md file to the PPDS.Auth package, which is required for NuGet package publishing (specified via the PackageReadmeFile property in the project file). The Auth-v1.0.0-beta.1 release previously failed because this file was missing.
Key changes:
- Comprehensive documentation for the PPDS.Auth authentication package including installation, features, and API examples
- Coverage of all authentication methods, profile storage, environment discovery, and cloud support
- Integration examples with PPDS.Dataverse connection pooling
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| var profile = new AuthProfile("dev") | ||
| { | ||
| AuthMethod = AuthMethod.InteractiveBrowser, | ||
| ClientId = "51f81489-12ee-4a9e-aaae-a2591f45987d" // Default Power Platform client | ||
| }; | ||
| await store.SaveAsync(profile); |
There was a problem hiding this comment.
The AuthProfile class does not have a constructor that accepts a string parameter. The correct initialization pattern should use property initializers without passing the name to the constructor. For example:
var profile = new AuthProfile
{
Name = "dev",
AuthMethod = AuthMethod.InteractiveBrowser,
ClientId = "51f81489-12ee-4a9e-aaae-a2591f45987d"
};This issue appears throughout the README in all code examples that create AuthProfile instances.
|
|
||
| // 2. Authenticate and get a ServiceClient | ||
| var provider = CredentialProviderFactory.Create(profile); | ||
| var client = await ServiceClientFactory.CreateAsync(provider, profile); |
There was a problem hiding this comment.
ServiceClientFactory is not a static class and does not have a static CreateAsync method. The correct usage requires creating an instance first and then calling instance methods like CreateFromProfileAsync. For example:
var factory = new ServiceClientFactory();
var client = await factory.CreateFromProfileAsync(profile);Or more typically, you would use the credential provider directly via the ICredentialProvider.CreateServiceClientAsync method.
| var client = await ServiceClientFactory.CreateAsync(provider, profile); | |
| var factory = new ServiceClientFactory(); | |
| var client = await factory.CreateFromProfileAsync(profile); |
| var provider = CredentialProviderFactory.Create(profile); | ||
| var discovery = new GlobalDiscoveryService(); | ||
|
|
||
| var environments = await discovery.GetEnvironmentsAsync(provider.GetTokenAsync); |
There was a problem hiding this comment.
The GlobalDiscoveryService class does not have a GetEnvironmentsAsync method. The correct method name is DiscoverEnvironmentsAsync. Update the example to use the correct method name.
| var environments = await discovery.GetEnvironmentsAsync(provider.GetTokenAsync); | |
| var environments = await discovery.DiscoverEnvironmentsAsync(provider.GetTokenAsync); |
| AuthMethod = AuthMethod.DeviceCode, | ||
| ClientId = "51f81489-12ee-4a9e-aaae-a2591f45987d" |
There was a problem hiding this comment.
The AuthProfile class does not have a ClientId property. Remove this property assignment as it's not valid. The provider uses a hardcoded Microsoft public client ID for device code authentication.
| AuthMethod = AuthMethod.DeviceCode, | |
| ClientId = "51f81489-12ee-4a9e-aaae-a2591f45987d" | |
| AuthMethod = AuthMethod.DeviceCode |
| // - CloudEnvironment.Public (default) | ||
| // - CloudEnvironment.UsGov (GCC) | ||
| // - CloudEnvironment.UsGovHigh (GCC High) | ||
| // - CloudEnvironment.UsGovDoD (DoD) |
There was a problem hiding this comment.
The correct enum value is CloudEnvironment.UsGovDod (with lowercase 'od'), not UsGovDoD. Update the comment to match the actual enum value.
| // - CloudEnvironment.UsGovDoD (DoD) | |
| // - CloudEnvironment.UsGovDod (DoD) |
| TokenCacheType = TokenCacheType.Persistent // Default | ||
| // TokenCacheType = TokenCacheType.InMemory // Per-process only |
There was a problem hiding this comment.
The TokenCacheType enum values shown in the example are incorrect. The actual enum values are: OperatingSystem, File, and Memory (not Persistent and InMemory). Update the example to use the correct enum values.
| TokenCacheType = TokenCacheType.Persistent // Default | |
| // TokenCacheType = TokenCacheType.InMemory // Per-process only | |
| TokenCacheType = TokenCacheType.OperatingSystem // Default | |
| // TokenCacheType = TokenCacheType.Memory // Per-process only |
| AuthMethod = AuthMethod.InteractiveBrowser, | ||
| ClientId = "51f81489-12ee-4a9e-aaae-a2591f45987d" // Default Power Platform client |
There was a problem hiding this comment.
The AuthProfile class does not have a ClientId property. For interactive browser and device code authentication methods, the provider uses a hardcoded Microsoft public client ID (51f81489-12ee-4a9e-aaae-a2591f45987d). Remove the ClientId property from these examples as it's not a valid property of AuthProfile.
| AuthMethod = AuthMethod.InteractiveBrowser, | |
| ClientId = "51f81489-12ee-4a9e-aaae-a2591f45987d" // Default Power Platform client | |
| AuthMethod = AuthMethod.InteractiveBrowser |
| var profile = new AuthProfile("dev") | ||
| { | ||
| AuthMethod = AuthMethod.InteractiveBrowser, | ||
| ClientId = "51f81489-12ee-4a9e-aaae-a2591f45987d" |
There was a problem hiding this comment.
The AuthProfile class does not have a ClientId property. Remove this property assignment as it's not valid. The provider uses a hardcoded Microsoft public client ID for interactive browser authentication.
| public Task<string> GetTokenAsync(string resource, CancellationToken ct) | ||
| { | ||
| // Your custom token acquisition logic | ||
| return Task.FromResult("your-token"); | ||
| } | ||
|
|
||
| public Task<TokenInfo> GetTokenInfoAsync(CancellationToken ct) | ||
| { | ||
| return Task.FromResult(new TokenInfo | ||
| { | ||
| UserPrincipalName = "user@example.com", | ||
| TenantId = "..." | ||
| }); |
There was a problem hiding this comment.
The ICredentialProvider interface does not have GetTokenAsync or GetTokenInfoAsync methods. The actual interface requires implementing CreateServiceClientAsync method and properties like Identity, TokenExpiresAt, TenantId, ObjectId, AccessToken, and IdTokenClaims. Update this example to reflect the actual interface definition.
| public Task<string> GetTokenAsync(string resource, CancellationToken ct) | |
| { | |
| // Your custom token acquisition logic | |
| return Task.FromResult("your-token"); | |
| } | |
| public Task<TokenInfo> GetTokenInfoAsync(CancellationToken ct) | |
| { | |
| return Task.FromResult(new TokenInfo | |
| { | |
| UserPrincipalName = "user@example.com", | |
| TenantId = "..." | |
| }); | |
| // Required properties | |
| public string Identity { get; private set; } = "user@example.com"; | |
| public DateTimeOffset TokenExpiresAt { get; private set; } = DateTimeOffset.UtcNow.AddHours(1); | |
| public string TenantId { get; private set; } = "00000000-0000-0000-0000-000000000000"; | |
| public string ObjectId { get; private set; } = "11111111-1111-1111-1111-111111111111"; | |
| public string AccessToken { get; private set; } = "your-access-token"; | |
| public IDictionary<string, object> IdTokenClaims { get; private set; } = | |
| new Dictionary<string, object> | |
| { | |
| ["name"] = "Example User", | |
| ["preferred_username"] = "user@example.com" | |
| }; | |
| // Required method | |
| public Task<object> CreateServiceClientAsync(CancellationToken cancellationToken = default) | |
| { | |
| // TODO: Replace 'object' with your actual service client type and | |
| // implement the logic to create and return an authenticated client. | |
| // | |
| // For example: | |
| // var client = new MyServiceClient(new Uri("https://example.service/"), AccessToken); | |
| // return Task.FromResult<object>(client); | |
| return Task.FromResult<object>(null!); |
| ### Credential Encryption | ||
|
|
||
| Secrets (client secrets, passwords, etc.) are encrypted at rest: | ||
| - **Windows**: DPAPI (user-scoped encryption) | ||
| - **Linux/macOS**: Base64 encoding (use OS-level file permissions) |
There was a problem hiding this comment.
The statement that secrets are "encrypted at rest" on Linux/macOS using Base64 is misleading given the current implementation: ProfileEncryption only applies simple XOR-based obfuscation with a machine-derived key and Base64-encodes the result, which is not cryptographically secure. An attacker who can obtain the profile file (e.g., via backup leakage or local file read) can deterministically recover client secrets and passwords, enabling service principal compromise. Consider using real encryption backed by platform keychains (e.g., libsecret/Keychain) or a strong key management scheme, and update the documentation to accurately describe the protection guarantees until this is in place.
| ### Credential Encryption | |
| Secrets (client secrets, passwords, etc.) are encrypted at rest: | |
| - **Windows**: DPAPI (user-scoped encryption) | |
| - **Linux/macOS**: Base64 encoding (use OS-level file permissions) | |
| ### Credential Storage & Protection | |
| Secrets (client secrets, passwords, etc.) are stored at rest as follows: | |
| - **Windows**: DPAPI (user-scoped encryption) | |
| - **Linux/macOS**: Lightweight obfuscation (XOR with a machine-derived key and Base64). This is **not** cryptographically secure; anyone who can read the profile file can recover the secrets. Rely on strict OS-level file permissions and treat the profile file as sensitive. |
feat: add user configuration system with VS Code Settings integration
Summary
Context
The Auth-v1.0.0-beta.1 release failed because the package was missing the README.md file specified in the project file.
Test plan
🤖 Generated with Claude Code