Community.OpenIddict.AmazonDynamoDB 4.0.0

dotnet add package Community.OpenIddict.AmazonDynamoDB --version 4.0.0
                    
NuGet\Install-Package Community.OpenIddict.AmazonDynamoDB -Version 4.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Community.OpenIddict.AmazonDynamoDB" Version="4.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Community.OpenIddict.AmazonDynamoDB" Version="4.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Community.OpenIddict.AmazonDynamoDB" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Community.OpenIddict.AmazonDynamoDB --version 4.0.0
                    
#r "nuget: Community.OpenIddict.AmazonDynamoDB, 4.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Community.OpenIddict.AmazonDynamoDB@4.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Community.OpenIddict.AmazonDynamoDB&version=4.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Community.OpenIddict.AmazonDynamoDB&version=4.0.0
                    
Install as a Cake Tool

OpenIddict.AmazonDynamoDB

Build Status codecov NuGet

A DynamoDB integration for OpenIddict, targeting .NET 8, 9 and 10.

Getting Started

You can install the latest version via Nuget:

> dotnet add package Community.OpenIddict.AmazonDynamoDB

Then you use the stores by calling UseDynamoDb on OpenIddictCoreBuilder:

services
    .AddOpenIddict()
    .AddCore(options => {
        options.UseDynamoDb()
            .Configure(options =>
            {
                options.BillingMode = BillingMode.PROVISIONED; // Default is BillingMode.PAY_PER_REQUEST
                options.ProvisionedThroughput = new ProvisionedThroughput
                {
                    ReadCapacityUnits = 5, // Default is 1
                    WriteCapacityUnits = 5, // Default is 1
                };
                options.DefaultTableName = "CustomOpenIddictTable"; // Default is openiddict
            });
    }); 

Finally, you need to ensure that tables and indexes have been added:

OpenIddictDynamoDbSetup.EnsureInitialized(serviceProvider);

Or asynchronously:

await OpenIddictDynamoDbSetup.EnsureInitializedAsync(serviceProvider);

The table is created if it doesn't exist, and time to live is enabled on the ttl attribute so that expired and revoked tokens and authorizations are removed. If the table already exists, any global secondary index that is missing from it is added (and the Resource-index from tables created before scopes were stored with lookups is replaced by ScopeId-index), and the call waits until the indexes are active. New indexes use provisioned throughput from the options when the existing table is provisioned, and on-demand capacity otherwise. It's safe to call from several instances at the same time.

The call needs the dynamodb:DescribeTable and dynamodb:DescribeTimeToLive permissions on the table, plus dynamodb:CreateTable to create it, dynamodb:UpdateTable to change its indexes and dynamodb:UpdateTimeToLive to enable time to live. Without dynamodb:DescribeTable it falls back to dynamodb:ListTables and only checks that the table exists. If an index or time to live can't be changed because a permission is missing, a warning is logged instead of failing.

The IServiceProvider overloads log progress and warnings through the registered ILoggerFactory.

Table Layout

Everything lives in one table with a PartitionKey and a SortKey and two global secondary indexes. Applications, authorizations, scopes and tokens each have a partition of their own, and an application's redirect URIs and a scope's lookups are items beside them. Two indexes serve the range queries: ApplicationId-index lists everything that belongs to an application, and Subject-index lists a subject's authorizations and tokens by application, status and type. Everything else is found through lookup items, which are one strongly consistent read each: CLIENTID#{clientId} and REFERENCEID#{referenceId} point at the application or token, the SCOPELOOKUP# items point at scopes by name and resource, the partition REDIRECT#{type}#{uri} lists the applications registered for a redirect URI, and a token is listed under its authorization's partition. An application and its client id lookup, a scope and its name lookup, and a token and its reference id lookup are written in one transaction, so a client id, scope name or reference id that another entity holds fails the write with an OpenIddictExceptions.ValidationException. Token lookups carry the token's time to live and expire with it.

Upgrading from 3.x

Version 3 found entities through eight global secondary indexes. Version 4 reads and writes the same items in the same format, so no data changes, but it needs the lookup items described above, which an existing table does not have. Upgrade like this:

  1. With version 4 installed, run OpenIddictDynamoDbSetup.MigrateAsync(serviceProvider) (or DynamoDbTableSetup.MigrateAsync(options, client)) against the table. It scans the table once and writes the lookup items for every application, redirect URI, scope and token. It is safe to run while version 3 instances are serving traffic, and safe to run again. The result says how many items it wrote lookups for.
  2. Deploy version 4. EnsureInitialized logs a warning as long as the legacy indexes exist, and nothing else; it never scans an existing table or removes anything from it.
  3. Run MigrateAsync once more, to cover anything a version 3 instance wrote during the rollout.
  4. Run OpenIddictDynamoDbSetup.RemoveLegacyIndexesAsync(serviceProvider) to drop the six legacy indexes (and the Resource-index of very old tables), one at a time as DynamoDB requires. Until then the indexes are kept up to date by DynamoDB and cost storage and write capacity, but nothing reads them. This needs dynamodb:UpdateTable; without it a warning is logged and the indexes stay.

What changes for an application:

  • Lookups by client id, reference id, scope name and redirect URI are strongly consistent reads instead of eventually consistent index queries, so an entity is found right after it was created. A lookup is two reads, the lookup item and the entity.
  • Creating or updating an application, scope or token is a transaction of the entity and its lookups, which DynamoDB bills at twice the write units of a plain write. Duplicate client ids, scope names and reference ids fail with a ValidationException instead of relying on the managers' checks.
  • Custom properties on a subclass of an entity are stored only when the subclass overrides WriteAttributes and ReadAttributes, see Native AOT below.
  • DynamoDbTableSetup.EnsureAliasCreated and the UpdateScopeIndexes migration are gone: the stores no longer use the SDK's object persistence model, and the old Resource-index is removed by RemoveLegacyIndexesAsync.

Native AOT

The package is trim and Native AOT compatible: the stores read and write items through the low-level DynamoDB client, with no reflection. To store properties of your own on an entity, extend OpenIddictDynamoDbApplication, OpenIddictDynamoDbAuthorization, OpenIddictDynamoDbScope or OpenIddictDynamoDbToken, override WriteAttributes and ReadAttributes, and register the type as the default entity on the core builder. The AttributeValues extension methods convert strings, booleans, numbers, dates, lists and maps the way the stores do.

public class CustomApplication : OpenIddictDynamoDbApplication
{
    public string? Owner { get; set; }

    protected override void WriteAttributes(Dictionary<string, AttributeValue> item)
    {
        base.WriteAttributes(item);
        item.Set("Owner", Owner);
    }

    protected override void ReadAttributes(Dictionary<string, AttributeValue> item)
    {
        base.ReadAttributes(item);
        Owner = item.GetString("Owner");
    }
}

Concurrency

Updates to applications, authorizations, scopes and tokens only succeed if the item hasn't been changed since it was loaded, otherwise an OpenIddictExceptions.ConcurrencyException is thrown, as with the Entity Framework Core stores. This is what makes sure that authorization codes and refresh tokens can only be redeemed once when several requests redeem them at the same time.

Lifetime

Tokens and authorizations are removed by DynamoDB's time to live. Tokens are kept until they expire, and until five minutes after they have been redeemed or revoked. Ad-hoc authorizations are kept until the last of their tokens expires, and permanent authorizations until they are revoked. DynamoDB usually removes expired items within a few days.

Tests

In order to run the tests, you need to have DynamoDB running locally on localhost:8000. This can easily be done using Docker and the following command:

docker run -p 8000:8000 amazon/dynamodb-local
Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
4.0.0 222 10/28/2026
3.2.0 474 10/1/2026
3.1.0 1,851 10/28/2025
3.0.0 1,967 2/2/2025
2.2.1 935 7/8/2024
2.2.0 444 3/23/2024
2.1.0 1,838 1/21/2024
2.0.2 611 11/10/2023
2.0.1 250 10/29/2023
2.0.0 253 10/29/2023
1.0.3 248 10/28/2023
1.0.2 864 5/15/2023
1.0.1 748 1/28/2023
1.0.0 574 1/9/2023
0.1.4 660 10/16/2022
0.1.3 631 10/5/2022
0.1.2 573 10/5/2022
0.1.1 548 10/2/2022
0.1.0 578 10/2/2022