Merge pull request #411 from IdentityModel/joe/readmes

Updated the READMEs
IdentityModel · Feb 23, 2024 · c55c69a · c55c69a
2 parents 49595f9 + 9cc2238
commit c55c69a
Show file tree

Hide file tree

Showing 8 changed files with 143 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,43 @@
-# C#/NetStandard OpenID Connect Client Library for native Applications
-Supported platforms: netstandard14, desktop .NET, UWP, .NET Core, Xamarin iOS & Android. [Nuget.](https://www.nuget.org/packages/IdentityModel.OidcClient/)
+## About IdentityModel.OidcClient
+This repository contains several libraries for building OpenID Connect (OIDC) native
+clients. The core IdentityModel.OidcClient library is a certified OIDC relying party and
+implements [RFC 8252](https://tools.ietf.org/html/rfc8252/), "OAuth 2.0 for native
+Applications". The IdentityModel.OidcClient.IdTokenValidator provides validation of Id
+Tokens based on the Microsoft JWT handler: 
+[IdentityModel.OidcClient.IdentityTokenValidator](https://www.nuget.org/packages/IdentityModel.OidcClient.IdentityTokenValidator),
+and is distributed as a separate package in order to prevent certain dependency problems.
+Finally, IdentityModel.OidcClient.DPoP adds [DPoP](https://datatracker.ietf.org/doc/html/rfc9449) 
+extensions to IdentityModel.OidcClient for sender-constraining tokens.
 
-[Certified](http://openid.net/certification/) OpenID Connect relying party implementation. 
+
+## Samples
+OidcClient targets .NET Standard, making it suitable for .NET and .NET
+Framework. It can be used to build OIDC native clients with a variety of .NET UI tools.
+The [samples repository](https://github.com/IdentityModel/IdentityModel.OidcClient.Samples)
+shows how to use it in 
+- .NET MAUI
+- Console Applications
+- WPF
+- WinForms
+- Xamarin iOS & Android
+- UWP
+
+## Documentation 
+
+More documentation is available
+[here](https://identitymodel.readthedocs.io/en/latest/native/overview.html).
+
+
+## Standards and Certification
+OidcClient is a [certified](http://openid.net/certification/) OpenID Connect
+relying party implementation, 
 
 ![openid_certified](https://cloud.githubusercontent.com/assets/1454075/7611268/4d19de32-f97b-11e4-895b-31b2455a7ca6.png)
 
-See [here](https://identitymodel.readthedocs.io/en/latest/native/overview.html) for documentation and [here](https://github.com/IdentityModel/IdentityModel.OidcClient.Samples) for samples.
+
+## Feedback
+
+IdentityModel.OidcClient is released as open source under the 
+[Apache 2.0 license](https://github.com/IdentityModel/IdentityModel.OidcClient/blob/main/LICENSE). 
+Bug reports and contributions are welcome at 
+[the GitHub repository](https://github.com/IdentityModel/IdentityModel.OidcClient).
diff --git a/src/DPoP/DPoP.csproj b/src/DPoP/DPoP.csproj
@@ -13,7 +13,7 @@
         <Description>DPoP extensions for IdentityModel.OidcClient</Description>
         <Authors>Dominick Baier;Brock Allen</Authors>
         <PackageIcon>icon.jpg</PackageIcon>
-
+        <PackageReadmeFile>README.md</PackageReadmeFile>
         <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
         <GenerateDocumentationFile>true</GenerateDocumentationFile>
 
@@ -36,6 +36,7 @@
 
     <ItemGroup>
         <None Include="../../icon.jpg" Pack="true" Visible="false" PackagePath="" />
+        <None Include="README.md" Pack="true" PackagePath=""/>
     </ItemGroup>
 
     <ItemGroup>

diff --git a/src/DPoP/README.md b/src/DPoP/README.md
@@ -0,0 +1,19 @@
+## About IdentityModel.OidcClient
+IdentityModel.OidcClient.DPoP adds support for DPoP ([RFC
+9449](https://datatracker.ietf.org/doc/html/rfc9449)) to IdentityModel.OidcClient. DPoP
+sender-constrains access and refresh tokens to protect them against replay attacks, and is 
+often used by mobile and other native applications.
+
+## Related Packages
+
+- Library for claims-based identity, OAuth 2.0, and OpenID Connect: [IdentityModel](https://www.nuget.org/packages/IdentityModel)
+- RFC8252 compliant and certified OpenID Connect and OAuth 2.0 client library for native applications: [IdentityModel.OidcClient](https://www.nuget.org/packages/IdentityModel.OidcClient)
+- Id token validator for IdentityModel.OidcClient based on the Microsoft JWT handler: [IdentityModel.OidcClient.IdentityTokenValidator](https://www.nuget.org/packages/IdentityModel.OidcClient.IdentityTokenValidator)
+- Authentication handler for introspection tokens: [IdentityModel.AspNetCore.OAuth2Introspection](https://www.nuget.org/packages/IdentityModel.AspNetCore.OAuth2Introspection)
+
+## Feedback
+
+IdentityModel.OidcClient is released as open source under the 
+[Apache 2.0 license](https://github.com/IdentityModel/IdentityModel.OidcClient/blob/main/LICENSE). 
+Bug reports and contributions are welcome at 
+[the GitHub repository](https://github.com/IdentityModel/IdentityModel.OidcClient).
diff --git a/src/IdentityTokenValidator/IdentityTokenValidator.csproj b/src/IdentityTokenValidator/IdentityTokenValidator.csproj
@@ -11,6 +11,7 @@
         <Authors>Dominick Baier;Brock Allen</Authors>
         <PackageIcon>icon.jpg</PackageIcon>
         <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
+        <PackageReadmeFile>README.md</PackageReadmeFile>
         <GenerateDocumentationFile>true</GenerateDocumentationFile>
 
         <!-- Publish the repository URL in the built .nupkg (in the NuSpec <Repository> element) -->
@@ -31,6 +32,7 @@
 
     <ItemGroup>
         <None Include="../../icon.jpg" Pack="true" Visible="false" PackagePath="" />
+        <None Include="README.md" Pack="true" PackagePath=""/>
     </ItemGroup>
 
     <ItemGroup>

diff --git a/src/IdentityTokenValidator/README.md b/src/IdentityTokenValidator/README.md
@@ -0,0 +1,22 @@
+## About IdentityModel.OidcClient
+IdentityModel.OidcClient.IdentityTokenValidator validates ID tokens using Microsoft's
+[System.IdentityModel.Tokens.Jwt](https://www.nuget.org/packages/System.IdentityModel.Tokens.Jwt/)
+library. It is intended to be used with
+[IdentityModel.OidcClient](https://www.nuget.org/packages/IdentityModel.OidcClient/),
+which provides an abstraction for validation of ID tokens that this package implements.
+Distributing the ID token validator separately allows for greater control of the version
+of the Microsoft JWT handler and prevents certain dependency issues. 
+
+## Related Packages
+
+- Library for claims-based identity, OAuth 2.0, and OpenID Connect: [IdentityModel](https://www.nuget.org/packages/IdentityModel)
+- RFC8252 compliant and certified OpenID Connect and OAuth 2.0 client library for native applications: [IdentityModel.OidcClient](https://www.nuget.org/packages/IdentityModel.OidcClient)
+- Id token validator for IdentityModel.OidcClient based on the Microsoft JWT handler: [IdentityModel.OidcClient.IdentityTokenValidator](https://www.nuget.org/packages/IdentityModel.OidcClient.IdentityTokenValidator)
+- Authentication handler for introspection tokens: [IdentityModel.AspNetCore.OAuth2Introspection](https://www.nuget.org/packages/IdentityModel.AspNetCore.OAuth2Introspection)
+
+## Feedback
+
+IdentityModel.OidcClient.IdentityTokenValidator is released as open source under the 
+[Apache 2.0 license](https://github.com/IdentityModel/IdentityModel.OidcClient/blob/main/LICENSE). 
+Bug reports and contributions are welcome at 
+[the GitHub repository](https://github.com/IdentityModel/IdentityModel.OidcClient).
diff --git a/src/OidcClient/OidcClient.csproj b/src/OidcClient/OidcClient.csproj
@@ -1,19 +1,20 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <PackageId>IdentityModel.OidcClient</PackageId>
     <RootNamespace>IdentityModel.OidcClient</RootNamespace>
     <AssemblyName>IdentityModel.OidcClient</AssemblyName>
 
     <TargetFrameworks>netstandard2.0;net6.0</TargetFrameworks>
     <LangVersion>latest</LangVersion>
 
+    <PackageId>IdentityModel.OidcClient</PackageId>
     <PackageTags>OAuth2;OAuth 2.0;OpenID Connect;Security;Identity;IdentityServer</PackageTags>
     <Description>RFC8252 compliant and certified OpenID Connect and OAuth 2.0 client library for native applications</Description>
     <Authors>Dominick Baier;Brock Allen</Authors>
     <PackageIcon>icon.jpg</PackageIcon>
-
     <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
 
     <!-- Publish the repository URL in the built .nupkg (in the NuSpec <Repository> element) -->
@@ -37,7 +38,8 @@
 
    <ItemGroup>
     <None Include="../../icon.jpg" Pack="true" Visible="false" PackagePath="" />
-  </ItemGroup>
+    <None Include="README.md" Pack="true" PackagePath=""/>
+</ItemGroup>
 
   <ItemGroup>
     <PackageReference Include="IdentityModel" Version="6.2.0" />

diff --git a/src/OidcClient/README.md b/src/OidcClient/README.md
@@ -0,0 +1,52 @@
+## About IdentityModel.OidcClient
+IdentityModel.OidcClient is an OpenID Connect (OIDC) client library that for native
+applications. It provides
+- Types that describe OIDC requests and responses
+- Low level methods to construct protocol state and handle responses
+- Higher level methods for 
+   - Logging in
+   - Logging out
+   - Retrieving userinfo
+   - Refreshing tokens
+
+## Samples
+IdentityModel.OidcClient targets .NET Standard, making it suitable for .NET and .NET
+Framework. It can be used to build OIDC native clients with a variety of .NET UI tools.
+The [samples repository](https://github.com/IdentityModel/IdentityModel.OidcClient.Samples)
+shows how to use it in 
+- .NET MAUI
+- Console Applications
+- WPF
+- WinForms
+- Xamarin iOS & Android
+- UWP
+
+## Documentation 
+
+More documentation is available
+[here](https://identitymodel.readthedocs.io/en/latest/native/overview.html).
+
+
+## Standards and Certification
+IdentityModel.OidcClient is a [certified](http://openid.net/certification/) OpenID Connect
+relying party implementation, and implements [RFC 8252](https://tools.ietf.org/html/rfc8252/),
+"OAuth 2.0 for native Applications".
+
+![openid_certified](https://cloud.githubusercontent.com/assets/1454075/7611268/4d19de32-f97b-11e4-895b-31b2455a7ca6.png)
+
+
+
+
+## Related Packages
+
+- Library for claims-based identity, OAuth 2.0, and OpenID Connect: [IdentityModel](https://www.nuget.org/packages/IdentityModel)
+- Id token validator for IdentityModel.OidcClient based on the Microsoft JWT handler: [IdentityModel.OidcClient.IdentityTokenValidator](https://www.nuget.org/packages/IdentityModel.OidcClient.IdentityTokenValidator)
+- [DPoP](https://datatracker.ietf.org/doc/html/rfc9449) extensions for IdentityModel.OidcClient: [IdentityModel.OidcClient.DPoP ](https://www.nuget.org/packages/IdentityModel.OidcClient.DPoP)
+- Authentication handler for introspection tokens: [IdentityModel.AspNetCore.OAuth2Introspection](https://www.nuget.org/packages/IdentityModel.AspNetCore.OAuth2Introspection)
+
+## Feedback
+
+IdentityModel.OidcClient is released as open source under the 
+[Apache 2.0 license](https://github.com/IdentityModel/IdentityModel.OidcClient/blob/main/LICENSE). 
+Bug reports and contributions are welcome at 
+[the GitHub repository](https://github.com/IdentityModel/IdentityModel.OidcClient).
diff --git a/test/TrimmableAnalysis/TrimmableAnalysis.csproj b/test/TrimmableAnalysis/TrimmableAnalysis.csproj
@@ -6,7 +6,8 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <PublishTrimmed>true</PublishTrimmed>
     <TrimmerSingleWarn>false</TrimmerSingleWarn> 
-    <TreatWarningsAsErrors>true</TreatWarningsAsErrors> 
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <IsPackable>false</IsPackable>
   </PropertyGroup>
 
   <ItemGroup>