azuread / microsoft-identity-abstractions-for-dotnet Goto Github PK

See AzureAD/microsoft-identity-web#1991

Documentation related to component

General

Please check all that apply

• typo
• documentation doesn't exist
• documentation needs clarification
• error(s) in the example
• needs an example

Description of the issue

New 3.x releases are created but it's hard to understand what breaking changes it include and how to migrate.

Additionally, no new GitHub releases are created after 2.1.0

Which version of Microsoft Identity Abstractions for dotnet are you using?
5.1.0

In the ManagedIdentity member of AcquireTokenOptions, there is this content:

<format type="text/markdown"><![CDATA[
            The Json fragment below describes how to use a system-assigned Managed Identity for authentication in a confidential client application :
            :::code language="json" source="~/../abstractions-samples/test/Microsoft.Identity.Abstractions.Tests/AquireTokenOptions.cs" id="managedidentitysystem_json":::
            
            The code below describes the same, programmatically in C#.
            :::code language="csharp" source="~/../abstractions-samples/test/Microsoft.Identity.Abstractions.Tests/AquireTokenOptions.cs" id="managedidentitysystem_csharp":::
            
            The Json fragment below describes how to use a user-assigned Managed Identity for authentication in a confidential client application :
            :::code language="json" source="~/../abstractions-samples/test/Microsoft.Identity.Abstractions.Tests/AquireTokenOptions.cs" id="managedidentityuser_json":::
            
            The code below describes the same, programmatically in C#.
            :::code language="csharp" source="~/../abstractions-samples/test/Microsoft.Identity.Abstractions.Tests/AquireTokenOptions.cs" id="managedidentityuser_csharp":::
            ]]></format>

However the file is not AquireTokenOptions.cs, it's AquireTokenOptionsTests.cs

Which version of Microsoft Identity Abstractions for dotnet are you using?
Note that to get help, you need to run the latest version.
Microsoft Identity Abstractions 7.0.2

Is this a new or an existing app?
This is a new app using IDownstreamApi from a client to communicate with a downstream api

            var downstreamApiOptions = new Action<DownstreamApiOptions>(
                options =>
                {
                    options.HttpMethod = HttpMethod.Post;
                    options.BaseUrl = baseUrl;
                    options.RelativePath = relativePath;
                });
           
            // This is a Stream passed to the client
            var inputContent = new StreamContent(fileToUpload);

            inputContent.Headers.ContentDisposition = new ContentDispositionHeaderValue("form-data")
            {
                DispositionType = "form-data",
                FileName = fileName,
                Size = fileToUpload.Length
            };

            inputContent.Headers.ContentType =
                MediaTypeHeaderValue.Parse(SharePointFileManagementConstants.MimeResponseApplicationOctetStream);
            inputContent.Headers.ContentLength = fileToUpload.Length;

            var multipartFormDataContent = new MultipartFormDataContent {{inputContent, fileName, fileName}};

            var responseMessage = await _downstreamApi.CallApiForUserAsync(SiteServiceName,
                downstreamApiOptions,
                null,
                multipartFormDataContent
            );

Expected behavior
There should be a call to the downstream api using the POST HTTP method

Actual behavior
An exception is thrown when the client tries to send the request downstream:
Method not found: 'Void Microsoft.Identity.Abstractions.AuthorizationHeaderProviderOptions.set_HttpMethod(System.Net.Http.HttpMethod)'.

Is your feature request related to a problem? Please describe.

Level to make the API easier to understand.

DownstreamRestApiOptions

• repetition of scopes
• repetition of HttpVerb
• Generic for Apps
• delete
• update

Serialization:

• delegate for serialization
• delegate for de-serialization

What?
This PR updates the IAuthorizationHeaderProvider interface to include the CreateAuthorizationHeaderAsync API. This new API allows for acquiring an authorization header on behalf of either a user or an application. This is a breaking change. To accomodate it Microsoft.Identity.Abstractions will update its major version.

Why?
The current interface exposes separate APIs for obtaining headers on behalf of a user and an app.
The existing method for acquiring a header on behalf of an app does not accept a ClaimsPrincipal, limiting the flexibility and usability of the current API.

Why?
ATPop requires more than the Key

What?
Add a JwtClaim public property of type string to TokenAcquirerOptions

It would be nice to have a simple way to build and produce packages from the command line.

Be able to support the following configuration:

            {
                "TokenDecryptionCredentials": [
                {
                    "SourceType": "AutoDecryptKeys",
                    "DecryptKeysApplicationTenant": "mytenant.onmicrosoftonline.com"
                    "DecryptKeysProtocol" : "bearer"
                }]
            }

This credential does not affect the container or ReferenceOrValue properties which should not be set and should return null for the soruce type "AutoDecryptKeys".

Since DownstreamRestApiOptions is not sealed, a derived class will find it hard to implement Derived.Clone().
see:

Is your feature request related to a problem? Please describe.
When net462 libraries (think Id.Web, SAL) take a dependency on netstandard2.0 libraries, this ends-up pulling the whole framework, whereas Microsoft.Identity.Abstractions is tiny and does not reference much. By adding direct support for net462, this enables to draw less dependencies

Describe the solution you'd like
Add the net462 target framework

Describe alternatives you've considered
None

Additional context
See also the common dependency management.

Is your feature request related to a problem? Please describe.
We can do better for the serialization

Describe the solution you'd like
Add 2 string properties AcceptHeader and a ContentType in DownstreamApiOptions

Which version of Microsoft Identity Abstractions for dotnet are you using?
4.1.0

Is this a new or an existing app?
This is an app that I'm trying to compile with AoT

Repro

<Project Sdk="Microsoft.NET.Sdk">
	<PropertyGroup>
		<OutputType>Exe</OutputType>
		<TargetFramework>net8.0</TargetFramework>
		<ImplicitUsings>enable</ImplicitUsings>
		<Nullable>enable</Nullable>
		<PublishAot>true</PublishAot>
		<InvariantGlobalization>true</InvariantGlobalization>
		<EnableConfigurationBindingGenerator>true</EnableConfigurationBindingGenerator>
		<LangVersion>latest</LangVersion>
		<Features>InterceptorsPreview</Features>
		<AdditionalCompilerArguments>-outputgeneratedcode:GeneratedCode</AdditionalCompilerArguments>
	</PropertyGroup>

	<ItemGroup>
	  <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="8.0.0-rc.1.23419.4" />
	  <PackageReference Include="Microsoft.Identity.Abstractions" Version="4.1.0" />
	</ItemGroup>

</Project>

And the code:

#pragma warning disable SYSLIB1100 // Did not generate binding logic for a type
#pragma warning disable SYSLIB1101 // Did not generate binding logic for a property on a type
            builder.Configuration.GetSection("DownstreamApi").Bind(downstreamApiOptions);
#pragma warning restore SYSLIB1101 // Did not generate binding logic for a property on a type
#pragma warning restore SYSLIB1100 // Did not generate binding logic for a type
            downstreamApiOptions.HttpMethod = HttpMethod.Parse(builder.Configuration.GetSection("DownstreamApi")["HttpMethod"]);

Expected behavior
No issues. The code generator can produce the binding on .NET 8 (we won't even try on lower versions of .NET, as we don't want to force a new dependency for these)

Actual behavior
The following properties issue warnings

• Method (System.Net.HttpMethod), is not bound/de-serialized.
• Serializer, Deserializer, CustomizeHttpRequestMessage should not be serializable (they are code-only configuration). Add a JsonIgnore attribute.

Possible solution

• Direct the serialization better with attribute and a type converter

Which version of Microsoft Identity Abstractions for dotnet are you using?
Microsoft Identity Abstractions version 5.3.0 via Microsoft.Identity.Web.DownstreamApi version 2.18.1

Is this a new or an existing app?
New app

Repro

Debug an ASP.NET 8.0 application using multiple IDP's and Azure Web PubSub.

// IDP 1
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("EntraExternalID"))
                .EnableTokenAcquisitionToCallDownstreamApi()
                .AddDownstreamApi("ServiceA", builder.Configuration.GetSection("ServiceA"))
                .AddDownstreamApi("ServiceB", builder.Configuration.GetSection("ServiceB"))
                .AddInMemoryTokenCaches();

// IDP 2
builder.Services.AddAuthentication().AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("EntraID"), "EntraID");

// Add Web PubSub Service Client
builder.Services.AddWebPubSub(options =>
{
    var config = builder.Configuration.GetSection("Config").Get<Configuration<Config>>();
    options.ServiceEndpoint = new WebPubSubServiceEndpoint(config.ConnectionString);
}).AddWebPubSubServiceClient<webpubsub>();

// standard init in between e.g. var app = builder.Build();

// Further down map web pubsub event handler
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.MapWebPubSubHub<webpubsub>("/eventhandler/{*path}");
app.Run();

Expected behavior
Error is not observed when debugging on Windows via Visual Studio.

Actual behavior
The call to app.MapWebPubSubHub<webpubsub>("/eventhandler/{*path}"); triggers System.InvalidOperationException: 'Cannot resolve scoped service 'Microsoft.Identity.Abstractions.IDownstreamApi' from root provider.' only when debugging via Visual Studio (latest version - 17.9.6) on Windows. When run in a Linux Container the app runs fine.

Possible solution
N/A

What?
Having this JSON content

"ClientCredentials": [
            {
                "SourceType": "Path",
                "CertificateDiskPath": "C:\\myCert.pfx",
                "CertificatePassword": "something here"
            }

and then reading the certificate description, this will read "something here" for both the CertificateDiskPath and CertificatePassword

Analysis?
This is because of the Container/ReferenceOrValue calculated properties that are not consistent with each other in this case

Suggestion
Write the unit test for these as well (even if they are only used for testing)

Does the AcquireTokenOptions.CorrelationId need to be a Guid or would a string be sufficient?

If not set, then the default value for this will be the default value of a Guid, all zeros.

Is it strictly required that the correlation ID being a GUID is another question

https://learn.microsoft.com/en-us/dotnet/fundamentals/package-validation/baseline-version-validator

See AzureAD/microsoft-identity-web#1980

Which version of Microsoft Identity Abstractions for dotnet are you using?
We need to implement CallRestApiForAppAsync<TOutput> and CallRestApiForAppAsync<TInput, TOutput> which are the missing counterpart of CallRestApiForUserAsync<TOutput> and CallRestApiForUserAsync<TInput, TOutput>

Alongside the descriptions, we’re also able to include example code snippets. For enhanced rendering, the platform also allows us to include markdown content in the triple slash comments. Here’s a good example for ML.NET API ref:· 
 - Source: machinelearning/ValueMapping.cs at main · dotnet/machinelearning (github.com) · 
 - Rendered file - ValueMappingEstimator Class (Microsoft.ML.Transforms) | Microsoft Learn 

 Notice how in the above ML.NET ref, we have example snippets, member/type descriptions, and even markdown content (you’d usually put this in a wiki) all surfacing in the autogenerated library reference.

Which version of Microsoft Identity Abstractions for dotnet are you using?
4.1.0

Repro

DownstreamApiOptions downstreamApiOptions = new DownstreamApiOptions();
builder.Configuration.GetSection("DownstreamApi").Bind(downstreamApiOptions);

Expected behavior
no exception thrown, and the properties can be read from the configuration.

Actual behavior

1. Exceptions are thrown if the "ProtocolScheme" is not set in the configuration
2. The HttpMethod property cannot be read from the configuration (there is no converter from string to HttpMethod)

Possible solution

1. Change the HttpMethod property to be a string, instead of an HttpMethod (same for the backing field _httpMethod). This will be a breaking change (people will have to change their code to use httpMethod.ToString(), for instance HttpMethod.Post.ToString(). This impacts the public API:

   • AuthorizationHeaderProviderOptions.HttpMethod, AuthorizationHeaderProviderOptions._httpMethod which need to move to be a string
   • DownstreamApiOptionsReadOnlyHttpMethod(DownstreamApiOptions options, HttpMethod httpMethod) (the last parameter needs to be a string)
   • DownstreamApiOptionsReadOnlyHttpMethod.HttpMethod that needs to be a string too.
   • the tests (lines such as options.HttpMethod = HttpMethod.Patch; becomes options.HttpMethod = HttpMethod.Patch.ToString();)

2. Remove the throw new ArgumentNullException in the properties that have a default value (ProtocolScheme that should return "Get", HttpMethod, that should return "Get"). Setting them to null (that is not setting them in the configuration), sets them to their default value.

   DefaultValue("Bearer")]
   public string ProtocolScheme
   {
    get
    {
     return _protocolScheme;
    }
    set
    {
   -  _protocolScheme = string.IsNullOrEmpty(value) ? throw new ArgumentNullException(_protocolScheme) : value;
   + _protocolScheme = string.IsNullOrEmpty(value) ? "Bearer" : value;
     }
   }

   This impacts tests as assigning null to these properties won't throw any longer (they will get a default value)

The downstream library Microsoft.Identity.Web needs additional information in these abstractions in order to support user-assigned/system-assigned managed identities see the correlated Identity.Web issue #1775 for more details.

To do this we can:

• Create a new ManagedIdentityOptions class to hold necessary information like the Client ID of a user-assigned identity.
• Add a ManagedIdentity property to the AcquireTokenOptions class in order to hold an instance of ManagedIdentityOptions.

Is your feature request related to a problem? Please describe.
Property name JwtClaim is specific to Json Web Tokens (JWT).

Describe the solution you'd like
The intent of the claim is providing proof-of-possession. By renaming the property to PopClaim, it can also be applied to other token types.

1. Remove this override of ITokenAcquirerFactory.GetTokenAcquirer():
   

   microsoft-identity-abstractions-for-dotnet/src/Microsoft.Identity.Abstractions/TokenAcquisition/ITokenAcquirerFactory.cs

   Line 23 in 3de79ae

   ITokenAcquirer GetTokenAcquirer(string authority, string clientId, IEnumerable<CredentialDescription> clientCredentials, string? region);

2. Rename:

   • ApplicationAuthenticationOptions to IdentityApplicationOptions,
   • and MicrosoftAuthenticationOptions to MicrosoftIdentityApplicationOptions

3. Remove HasClientCredentials in ApplicationAuthenticationOptions / IdentityApplicationOptions

[Bug] For netstandard2.1 skus, the HttpMethod.Patch method should be supported

Is your feature request related to a problem? Please describe.
Because the implementations of the Downstream Api methods rely on generic types (and often reflection), warnings for these methods will always have trim warnings.

Describe the solution you'd like
Apply RequiresUnreferencedCode attributes to the methods whose implementations are trim-unfriendly.

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...].
The OAuth 2.0 specification requires TokenType (https://www.rfc-editor.org/rfc/rfc6749#section-7.1) this should be a first class property.

see:

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.