Skip to content

Commit 9f2ddb6

Browse files
mdchennumdchennu
authored
Merge branch 'main' into copilot/update-to-dotnet-10-rc2
2 parents 36b9a15 + 1a50b8e commit 9f2ddb6

File tree

3 files changed

+164
-101
lines changed

3 files changed

+164
-101
lines changed

‎README.md‎

Lines changed: 142 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
1-
[![CI](https://github.com/AzureAD/microsoft-identity-abstractions-for-dotnet/actions/workflows/dotnetcore.yml/badge.svg)](https://github.com/AzureAD/microsoft-identity-abstractions-for-dotnet/actions/workflows/dotnetcore.yml)
1+
[![CI](https://github.com/AzureAD/microsoft-identity-abstractions-for-dotnet/actions/workflows/dotnetcore.yml/badge.svg)](https://github.com/AzureAD/microsoft-identity-abstractions-for-dotnet/actions/workflows/dotnetcore.yml) ![Diagrams Synced](https://img.shields.io/badge/Diagrams%20Synced-2025--10--15-blue)
22

33
# Microsoft.Identity.Abstractions
44

55
Microsoft.Identity.Abstractions contain interfaces and POCO classes used in the Microsoft .NET authentication
66
libraries (Microsoft.IdentityModel, MSAL.NET and Microsoft.Identity.Web). It exposes concepts in three domains:
7+
- Application and credentials
8+
- Acquire tokens, get authorization headers and call downstream APIs
9+
- Extensibility to bring your own credential providers
710

811
## NuGet Package
912

@@ -27,31 +30,33 @@ the following diagram provides an overview of the data classes exposed by Micros
2730

2831
```mermaid
2932
classDiagram
30-
namespace ApplicationOptions {
31-
class CredentialDescription {
32-
<<ro>> +string Id
33-
<<rw>> +CredentialSource SourceType
34-
<<rw>> +string KeyVaultUrl
35-
<<rw>> +string CertificateStorePath
36-
<<rw>> +string CertificateDistinguishedName
37-
<<rw>> +string KeyVaultCertificateName
38-
<<rw>> +string CertificateThumbprint
39-
<<rw>> +string CertificateDiskPath
40-
<<rw>> +string CertificatePassword
41-
<<rw>> +string Base64EncodedValue
42-
<<rw>> +string ClientSecret
43-
<<rw>> +string ManagedIdentityClientId
44-
<<rw>> +string SignedAssertionFileDiskPath
45-
<<rw>> +AuthorizationHeaderProviderOptions DecryptKeysAuthenticationOptions
46-
<<rw>> +string TokenExchangeAuthority
47-
<<rw>> +X509Certificate2 Certificate
48-
<<rw>> +Object CachedValue
49-
<<rw>> +bool Skip
50-
<<ro>> +CredentialType CredentialType
51-
<<rw>> +string TokenExchangeUrl
52-
<<rw>> +string CustomSignedAssertionProviderName
53-
<<rw>> +Dictionary<string, Object> CustomSignedAssertionProviderData
54-
}
33+
direction TB
34+
namespace ApplicationOptions {
35+
class CredentialDescription {
36+
<<ro>> +string Id
37+
<<rw>> +CredentialSource SourceType
38+
<<rw>> +string KeyVaultUrl
39+
<<rw>> +string CertificateStorePath
40+
<<rw>> +string CertificateDistinguishedName
41+
<<rw>> +string KeyVaultCertificateName
42+
<<rw>> +string CertificateThumbprint
43+
<<rw>> +string CertificateDiskPath
44+
<<rw>> +string CertificatePassword
45+
<<rw>> +string Base64EncodedValue
46+
<<rw>> +string ClientSecret
47+
<<rw>> +string ManagedIdentityClientId
48+
<<rw>> +string SignedAssertionFileDiskPath
49+
<<rw>> +AuthorizationHeaderProviderOptions DecryptKeysAuthenticationOptions
50+
<<rw>> +string TokenExchangeAuthority
51+
<<rw>> +X509Certificate2 Certificate
52+
<<rw>> +object CachedValue
53+
<<rw>> +bool Skip
54+
<<ro>> +CredentialType CredentialType
55+
<<rw>> +string TokenExchangeUrl
56+
<<rw>> +string CustomSignedAssertionProviderName
57+
<<rw>> +Dictionary<string, Object> CustomSignedAssertionProviderData
58+
<<rw>> +string Algorithm
59+
}
5560
class CredentialSource { <<enum>>
5661
Certificate = 0
5762
KeyVault = 1
@@ -73,64 +78,67 @@ classDiagram
7378
DecryptKeys = 3
7479
}
7580
class IdentityApplicationOptions {
76-
&lt;&lt;rw&gt;&gt; +string Authority
77-
&lt;&lt;rw&gt;&gt; +string ClientId
78-
&lt;&lt;rw&gt;&gt; +bool EnablePiiLogging
79-
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraQueryParameters
80-
&lt;&lt;rw&gt;&gt; +IEnumerable&lt;CredentialDescription&gt; ClientCredentials
81-
&lt;&lt;rw&gt;&gt; +string Audience
82-
&lt;&lt;rw&gt;&gt; +IEnumerable&lt;string&gt; Audiences
83-
&lt;&lt;rw&gt;&gt; +IEnumerable&lt;CredentialDescription&gt; TokenDecryptionCredentials
84-
&lt;&lt;rw&gt;&gt; +bool AllowWebApiToBeAuthorizedByACL
81+
&lt;&lt;rw&gt;&gt; +string Authority
82+
&lt;&lt;rw&gt;&gt; +string ClientId
83+
&lt;&lt;rw&gt;&gt; +bool EnablePiiLogging
84+
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraQueryParameters
85+
&lt;&lt;rw&gt;&gt; +IEnumerable&lt;CredentialDescription&gt; ClientCredentials
86+
&lt;&lt;rw&gt;&gt; +string Audience
87+
&lt;&lt;rw&gt;&gt; +IEnumerable&lt;string&gt; Audiences
88+
&lt;&lt;rw&gt;&gt; +IEnumerable&lt;CredentialDescription&gt; TokenDecryptionCredentials
89+
&lt;&lt;rw&gt;&gt; +bool AllowWebApiToBeAuthorizedByACL
8590
}
8691
class MicrosoftEntraApplicationOptions {
87-
&lt;&lt;rw&gt;&gt; +string Instance
88-
&lt;&lt;rw&gt;&gt; +string TenantId
89-
&lt;&lt;rw&gt;&gt; +string Authority
90-
&lt;&lt;rw&gt;&gt; +string AppHomeTenantId
91-
&lt;&lt;rw&gt;&gt; +string AzureRegion
92-
&lt;&lt;rw&gt;&gt; +IEnumerable&lt;string&gt; ClientCapabilities
93-
&lt;&lt;rw&gt;&gt; +bool SendX5C
92+
&lt;&lt;rw&gt;&gt; +string Name
93+
&lt;&lt;rw&gt;&gt; +string Instance
94+
&lt;&lt;rw&gt;&gt; +string TenantId
95+
&lt;&lt;rw&gt;&gt; +string Authority
96+
&lt;&lt;rw&gt;&gt; +string AppHomeTenantId
97+
&lt;&lt;rw&gt;&gt; +string AzureRegion
98+
&lt;&lt;rw&gt;&gt; +IEnumerable&lt;string&gt; ClientCapabilities
99+
&lt;&lt;rw&gt;&gt; +bool SendX5C
94100
}
95101
class MicrosoftIdentityApplicationOptions {
96-
&lt;&lt;rw&gt;&gt; +bool WithSpaAuthCode
97-
&lt;&lt;rw&gt;&gt; +string Domain
98-
&lt;&lt;rw&gt;&gt; +string EditProfilePolicyId
99-
&lt;&lt;rw&gt;&gt; +string SignUpSignInPolicyId
100-
&lt;&lt;rw&gt;&gt; +string ResetPasswordPolicyId
101-
&lt;&lt;ro&gt;&gt; +string DefaultUserFlow
102-
&lt;&lt;rw&gt;&gt; +string ResetPasswordPath
103-
&lt;&lt;rw&gt;&gt; +string ErrorPath
102+
&lt;&lt;rw&gt;&gt; +bool WithSpaAuthCode
103+
&lt;&lt;rw&gt;&gt; +string Domain
104+
&lt;&lt;rw&gt;&gt; +string EditProfilePolicyId
105+
&lt;&lt;rw&gt;&gt; +string SignUpSignInPolicyId
106+
&lt;&lt;rw&gt;&gt; +string ResetPasswordPolicyId
107+
&lt;&lt;ro&gt;&gt; +string DefaultUserFlow
108+
&lt;&lt;rw&gt;&gt; +string ResetPasswordPath
109+
&lt;&lt;rw&gt;&gt; +string ErrorPath
104110
}
105111
}
106112
107-
namespace TokenAcquisition {
113+
namespace TokenAcquisition {
108114
class AcquireTokenOptions {
109-
+AcquireTokenOptions Clone()
110-
&lt;&lt;rw&gt;&gt; +string AuthenticationOptionsName
111-
&lt;&lt;rw&gt;&gt; +Nullable&lt;Guid&gt; CorrelationId
112-
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraQueryParameters
113-
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, Object&gt; ExtraParameters
114-
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraHeadersParameters
115-
&lt;&lt;rw&gt;&gt; +string Claims
116-
&lt;&lt;rw&gt;&gt; +string FmiPath
117-
&lt;&lt;rw&gt;&gt; +bool ForceRefresh
118-
&lt;&lt;rw&gt;&gt; +string PopPublicKey
119-
&lt;&lt;rw&gt;&gt; +string PopClaim
120-
&lt;&lt;rw&gt;&gt; +ManagedIdentityOptions ManagedIdentity
121-
&lt;&lt;rw&gt;&gt; +string LongRunningWebApiSessionKey
122-
&lt;&lt;ro&gt;&gt; +string LongRunningWebApiSessionKeyAuto
123-
&lt;&lt;rw&gt;&gt; +string Tenant
124-
&lt;&lt;rw&gt;&gt; +string UserFlow
115+
+AcquireTokenOptions Clone()
116+
&lt;&lt;rw&gt;&gt; +string AuthenticationOptionsName
117+
&lt;&lt;rw&gt;&gt; +Nullable&lt;Guid&gt; CorrelationId
118+
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraQueryParameters
119+
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, Object&gt; ExtraParameters
120+
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraHeaderParameters
121+
&lt;&lt;rw&gt;&gt; +string Claims
122+
&lt;&lt;rw&gt;&gt; +string FmiPath
123+
&lt;&lt;rw&gt;&gt; +bool ForceRefresh
124+
&lt;&lt;rw&gt;&gt; +string PopPublicKey
125+
&lt;&lt;rw&gt;&gt; +string PopClaim
126+
&lt;&lt;rw&gt;&gt; +ManagedIdentityOptions ManagedIdentity
127+
&lt;&lt;rw&gt;&gt; +string LongRunningWebApiSessionKey
128+
&lt;&lt;ro&gt;&gt; +string LongRunningWebApiSessionKeyAuto
129+
&lt;&lt;rw&gt;&gt; +string Tenant
130+
&lt;&lt;rw&gt;&gt; +string UserFlow
125131
}
126132
class AcquireTokenResult {
127-
&lt;&lt;rw&gt;&gt; +string AccessToken
128-
&lt;&lt;rw&gt;&gt; +DateTimeOffset ExpiresOn
129-
&lt;&lt;rw&gt;&gt; +string TenantId
130-
&lt;&lt;rw&gt;&gt; +string IdToken
131-
&lt;&lt;rw&gt;&gt; +IEnumerable&lt;string&gt; Scopes
132-
&lt;&lt;rw&gt;&gt; +Guid CorrelationId
133-
&lt;&lt;rw&gt;&gt; +string TokenType
133+
&lt;&lt;rw&gt;&gt; +string AccessToken
134+
&lt;&lt;rw&gt;&gt; +DateTimeOffset ExpiresOn
135+
&lt;&lt;rw&gt;&gt; +string TenantId
136+
&lt;&lt;rw&gt;&gt; +string IdToken
137+
&lt;&lt;rw&gt;&gt; +IEnumerable&lt;string&gt; Scopes
138+
&lt;&lt;rw&gt;&gt; +Guid CorrelationId
139+
&lt;&lt;rw&gt;&gt; +string TokenType
140+
&lt;&lt;rw&gt;&gt; +IReadOnlyDictionary&lt;string, string&gt; AdditionalResponseParameters
141+
&lt;&lt;rw&gt;&gt; +X509Certificate2 BindingCertificate
134142
}
135143
class ITokenAcquirer { <<interface>>
136144
+Task&lt;AcquireTokenResult&gt; GetTokenForUserAsync(IEnumerable&lt;string&gt; scopes, AcquireTokenOptions tokenAcquisitionOptions, ClaimsPrincipal user, CancellationToken cancellationToken)
@@ -151,31 +159,38 @@ classDiagram
151159
+AuthorizationHeaderProviderOptions Clone()
152160
#AuthorizationHeaderProviderOptions CloneInternal()
153161
+string GetApiUrl()
154-
&lt;&lt;rw&gt;&gt; +string BaseUrl
155-
&lt;&lt;rw&gt;&gt; +string RelativePath
156-
&lt;&lt;rw&gt;&gt; +string HttpMethod
157-
&lt;&lt;rw&gt;&gt; +Action&lt;HttpRequestMessage&gt; CustomizeHttpRequestMessage
158-
&lt;&lt;rw&gt;&gt; +AcquireTokenOptions AcquireTokenOptions
159-
&lt;&lt;rw&gt;&gt; +string ProtocolScheme
160-
&lt;&lt;rw&gt;&gt; +bool RequestAppToken
162+
&lt;&lt;rw&gt;&gt; +string BaseUrl
163+
&lt;&lt;rw&gt;&gt; +string RelativePath
164+
&lt;&lt;rw&gt;&gt; +string HttpMethod
165+
&lt;&lt;rw&gt;&gt; +Action&lt;HttpRequestMessage&gt; CustomizeHttpRequestMessage
166+
&lt;&lt;rw&gt;&gt; +AcquireTokenOptions AcquireTokenOptions
167+
&lt;&lt;rw&gt;&gt; +string ProtocolScheme
168+
&lt;&lt;rw&gt;&gt; +bool RequestAppToken
161169
}
162170
class DownstreamApiOptions {
163171
+DownstreamApiOptions Clone()
164172
#AuthorizationHeaderProviderOptions CloneInternal()
165-
&lt;&lt;rw&gt;&gt; +IEnumerable&lt;string&gt; Scopes
166-
&lt;&lt;rw&gt;&gt; +Func&lt;Object, HttpContent&gt; Serializer
167-
&lt;&lt;rw&gt;&gt; +Func&lt;HttpContent, Object&gt; Deserializer
168-
&lt;&lt;rw&gt;&gt; +string AcceptHeader
169-
&lt;&lt;rw&gt;&gt; +string ContentType
170-
&lt;&lt;rw&gt;&gt; +string ExtraQueryParameters
171-
&lt;&lt;rw&gt;&gt; +string ExtraHeadersParameters
173+
&lt;&lt;rw&gt;&gt; +IEnumerable&lt;string&gt; Scopes
174+
&lt;&lt;rw&gt;&gt; +Func&lt;object?,HttpContent?&gt; Serializer
175+
&lt;&lt;rw&gt;&gt; +Func&lt;HttpContent?,object?&gt; Deserializer
176+
&lt;&lt;rw&gt;&gt; +string AcceptHeader
177+
&lt;&lt;rw&gt;&gt; +string ContentType
178+
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraQueryParameters
179+
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraHeaderParameters
172180
}
173181
class DownstreamApiOptionsReadOnlyHttpMethod {
174182
+DownstreamApiOptionsReadOnlyHttpMethod Clone()
175183
#AuthorizationHeaderProviderOptions CloneInternal()
176-
&lt;&lt;rw&gt;&gt; +string HttpMethod
184+
&lt;&lt;ro&gt;&gt; +string HttpMethod
177185
}
178186
187+
class IAuthorizationHeaderProvider { <<interface>> }
188+
class IAuthorizationHeaderProvider_TResult_ { <<interface>> }
189+
class IDownstreamApi { <<interface>>
190+
+CallApiAsync(...)
191+
+CallApiForUserAsync(...)
192+
+CallApiForAppAsync(...)
193+
+Generic overloads() ... }
179194
}
180195
181196
@@ -199,6 +214,11 @@ classDiagram
199214
ITokenAcquirer --> AcquireTokenResult : returns
200215
```
201216

217+
Note:
218+
- for `AuthorizationHeaderProviderOptions` "Defaults: ProtocolScheme=Bearer, HttpMethod=Get"
219+
- for `DownstreamApiOptions` "Defaults: AcceptHeader=application/json, ContentType=application/json
220+
- for `IdentityApplicationOptions` "Effective audiences = Audience ∪ Audiences"
221+
202222
### Application options and credentials
203223

204224
The application options are typically the options that you find in configuration files like the appsettings.json
@@ -230,6 +250,7 @@ classDiagram
230250
&lt;&lt;rw&gt;&gt; +string TokenExchangeUrl
231251
&lt;&lt;rw&gt;&gt; +string CustomSignedAssertionProviderName
232252
&lt;&lt;rw&gt;&gt; +Dictionary&lt;string, Object&gt; CustomSignedAssertionProviderData
253+
&lt;&lt;rw&gt;&gt; +string Algorithm
233254
}
234255
class CredentialSource { <<enum>>
235256
Certificate = 0
@@ -263,6 +284,7 @@ classDiagram
263284
&lt;&lt;rw&gt;&gt; +bool AllowWebApiToBeAuthorizedByACL
264285
}
265286
class MicrosoftEntraApplicationOptions {
287+
&lt;&lt;rw&gt;&gt; +string Name
266288
&lt;&lt;rw&gt;&gt; +string Instance
267289
&lt;&lt;rw&gt;&gt; +string TenantId
268290
&lt;&lt;rw&gt;&gt; +string Authority
@@ -348,7 +370,7 @@ classDiagram
348370
&lt;&lt;rw&gt;&gt; +Nullable&lt;Guid&gt; CorrelationId
349371
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraQueryParameters
350372
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, Object&gt; ExtraParameters
351-
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraHeadersParameters
373+
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraHeaderParameters
352374
&lt;&lt;rw&gt;&gt; +string Claims
353375
&lt;&lt;rw&gt;&gt; +string FmiPath
354376
&lt;&lt;rw&gt;&gt; +bool ForceRefresh
@@ -368,6 +390,8 @@ classDiagram
368390
&lt;&lt;rw&gt;&gt; +IEnumerable&lt;string&gt; Scopes
369391
&lt;&lt;rw&gt;&gt; +Guid CorrelationId
370392
&lt;&lt;rw&gt;&gt; +string TokenType
393+
&lt;&lt;rw&gt;&gt; +IReadOnlyDictionary&lt;string, string&gt; AdditionalResponseParameters
394+
&lt;&lt;rw&gt;&gt; +X509Certificate2 BindingCertificate
371395
}
372396
class ITokenAcquirer { <<interface>>
373397
+Task&lt;AcquireTokenResult&gt; GetTokenForUserAsync(IEnumerable&lt;string&gt; scopes, AcquireTokenOptions tokenAcquisitionOptions, ClaimsPrincipal user, CancellationToken cancellationToken)
@@ -422,12 +446,12 @@ It's also possible (and recommended) to use higher level APIs:
422446
&lt;&lt;rw&gt;&gt; +string AcceptHeader
423447
&lt;&lt;rw&gt;&gt; +string ContentType
424448
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraQueryParameters
425-
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraHeadersParameters
449+
&lt;&lt;rw&gt;&gt; +IDictionary&lt;string, string&gt; ExtraHeaderParameters
426450
}
427451
class DownstreamApiOptionsReadOnlyHttpMethod {
428452
+DownstreamApiOptionsReadOnlyHttpMethod Clone()
429453
#AuthorizationHeaderProviderOptions CloneInternal()
430-
&lt;&lt;rw&gt;&gt; +string HttpMethod
454+
&lt;&lt;ro&gt;&gt; +string HttpMethod
431455
}
432456
class IAuthorizationHeaderProvider { <<interface>>
433457
+Task&lt;string&gt; CreateAuthorizationHeaderForUserAsync(IEnumerable&lt;string&gt; scopes, AuthorizationHeaderProviderOptions authorizationHeaderProviderOptions, ClaimsPrincipal claimsPrincipal, CancellationToken cancellationToken)
@@ -496,10 +520,36 @@ It's also possible (and recommended) to use higher level APIs:
496520
AcquireTokenOptions --> "ManagedIdentity" ManagedIdentityOptions : Has
497521
IDownstreamApi ..> DownstreamApiOptions : Uses
498522
IAuthorizationHeaderProvider ..> AuthorizationHeaderProviderOptions : Uses
523+
499524
```
500525

501526

527+
### Extensibility
528+
Credential loading extensibility points.
502529

530+
```mermaid
531+
classDiagram
532+
class CredentialSourceLoaderParameters {
533+
+string ClientId
534+
+string Authority
535+
}
536+
class ICredentialSourceLoader { <<interface>>
537+
+Task LoadIfNeededAsync(CredentialDescription, CredentialSourceLoaderParameters?)
538+
+CredentialSource CredentialSource
539+
}
540+
class ICustomSignedAssertionProvider { <<interface>>
541+
+string Name
542+
}
543+
class ICredentialsLoader { <<interface>>
544+
+IDictionary&lt;CredentialSource, ICredentialSourceLoader&gt; CredentialSourceLoaders
545+
+Task LoadCredentialsIfNeededAsync(CredentialDescription, CredentialSourceLoaderParameters?)
546+
+Task &lt;CredentialDescription?&gt; LoadFirstValidCredentialsAsync(IEnumerable&lt;CredentialDescription&gt;, CredentialSourceLoaderParameters?)
547+
+void ResetCredentials(IEnumerable<CredentialDescription>)
548+
}
549+
ICredentialSourceLoader <|-- ICustomSignedAssertionProvider : Inherits
550+
ICredentialsLoader --> ICredentialSourceLoader : Uses
551+
ICredentialSourceLoader --> CredentialSourceLoaderParameters : Uses
552+
```
503553

504554
## Contributing
505555

0 commit comments

Comments
 (0)