openiddict / openiddict-documentation Goto Github PK

Things to document:

• The entities were renamed to include the name of the store (e.g for the Mongo DB stores, OpenIddictApplication was renamed to OpenIddictMongoDbApplication).

• A new Requirements property was introduced in the application entity.

• The Subject property on the authorization/token entities is no longer required (which was needed for device flow support, where the user is not known until the authorization is granted).

• Encrypted JWT is the new token format for all token types.

• The validation handler now natively supports JWT tokens and introspection.

We'll want to include this setup script as part of the documentation:

using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using MongoDB.Driver;
using OpenIddict.MongoDb;
using OpenIddict.MongoDb.Models;

namespace MongoDbSetup
{
    public static class Program
    {
        public static async Task Main(string[] args)
        {
            var services = new ServiceCollection();
            services.AddOpenIddict()
                .AddCore(options => options.UseMongoDb());

            services.AddSingleton(new MongoClient("mongodb://localhost:27017").GetDatabase("openiddict"));

            var provider = services.BuildServiceProvider();
            var context = provider.GetRequiredService<IOpenIddictMongoDbContext>();
            var options = provider.GetRequiredService<IOptionsMonitor<OpenIddictMongoDbOptions>>().CurrentValue;
            var database = await context.GetDatabaseAsync(CancellationToken.None);

            var applications = database.GetCollection<OpenIddictMongoDbApplication>(options.ApplicationsCollectionName);
            await applications.Indexes.CreateManyAsync(new[]
            {
                new CreateIndexModel<OpenIddictMongoDbApplication>(
                    Builders<OpenIddictMongoDbApplication>.IndexKeys.Ascending(application => application.ClientId),
                    new CreateIndexOptions
                    {
                        Unique = true
                    }),

                new CreateIndexModel<OpenIddictMongoDbApplication>(
                    Builders<OpenIddictMongoDbApplication>.IndexKeys.Ascending(application => application.PostLogoutRedirectUris),
                    new CreateIndexOptions
                    {
                        Background = true
                    }),

                new CreateIndexModel<OpenIddictMongoDbApplication>(
                    Builders<OpenIddictMongoDbApplication>.IndexKeys.Ascending(application => application.RedirectUris),
                    new CreateIndexOptions
                    {
                        Background = true
                    })
            });

            var authorizations = database.GetCollection<OpenIddictMongoDbAuthorization>(options.AuthorizationsCollectionName);
            await authorizations.Indexes.CreateOneAsync(new CreateIndexModel<OpenIddictMongoDbAuthorization>(
                Builders<OpenIddictMongoDbAuthorization>.IndexKeys
                    .Ascending(authorization => authorization.ApplicationId)
                    .Ascending(authorization => authorization.Scopes)
                    .Ascending(authorization => authorization.Status)
                    .Ascending(authorization => authorization.Subject)
                    .Ascending(authorization => authorization.Type),
                new CreateIndexOptions
                {
                    Background = true
                }));

            var scopes = database.GetCollection<OpenIddictMongoDbScope>(options.ScopesCollectionName);
            await scopes.Indexes.CreateOneAsync(new CreateIndexModel<OpenIddictMongoDbScope>(
                Builders<OpenIddictMongoDbScope>.IndexKeys.Ascending(scope => scope.Name),
                new CreateIndexOptions
                {
                    Unique = true
                }));

            var tokens = database.GetCollection<OpenIddictMongoDbToken>(options.TokensCollectionName);
            await tokens.Indexes.CreateManyAsync(new[]
            {
                new CreateIndexModel<OpenIddictMongoDbToken>(
                    Builders<OpenIddictMongoDbToken>.IndexKeys.Ascending(token => token.ReferenceId),
                    new CreateIndexOptions<OpenIddictMongoDbToken>
                    {
                        // Note: partial filter expressions are not supported on Azure Cosmos DB.
                        // As a workaround, the expression and the unique constraint can be removed.
                        PartialFilterExpression = Builders<OpenIddictMongoDbToken>.Filter.Exists(token => token.ReferenceId),
                        Unique = true
                    }),

                new CreateIndexModel<OpenIddictMongoDbToken>(
                    Builders<OpenIddictMongoDbToken>.IndexKeys
                        .Ascending(token => token.ApplicationId)
                        .Ascending(token => token.Status)
                        .Ascending(token => token.Subject)
                        .Ascending(token => token.Type),
                    new CreateIndexOptions
                    {
                        Background = true
                    })
            });
        }
    }
}

This is a placeholder,

Some description why I need all these flows, and the downsides, e.g. Password Flow is not good for anything basically cause it does not allow standard way to do two factor authentication.

Implicit is the only way for JS apps.

Code flow for other "native" apps such as iOS apps / Android apps.

Confirm you've already contributed to this project or that you sponsor it

• I confirm I'm a sponsor or a contributor

Describe the solution you'd like

openiddict/openiddict-core#1396 introduced a new web integration package for the OpenIddict client that aims at offering an alternative to https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers, for which many of the providers were provided by the community.

To increase the number of contributions, we'll need to document this process.
A few things that should likely be included:

• Does the provider offer multiple environments? (e.g production, development, staging). If so, the provider MUST have multiple <Environment /> nodes with the corresponding configuration.
• Does the provider expose a configuration document for the supported environments? If so, the provider MUST use discovery instead of static configuration for all environments that support it.
• If static configuration is used, does the provider support PKCE?
• If static configuration is used, does the provider require using client_secret_basic?
• Does the provider require custom code to accommodate to non-standard behaviors?

Additional context

No response

We're still on DocFX 2.24, which is a bit old now. We should migrate to 2.54, which is the latest version.

openiddict/openiddict-core#1202 (comment)

Confirm you've already contributed to this project or that you sponsor it

• I confirm I'm a sponsor or a contributor

Describe the solution you'd like

Using web providers such as Github is barely documented. In the Contributing a new Web provider, it quickly mentions how to test it's hard to know what to do just for that. On Github it seems like no projects use the web providers (sourcegraph).

Here are the questions I've asked myself when reading trying to use web providers with open iddict:

• The AddClient method confused me. I supposed our OIDC server is now a OIDC client too
• Is the UseSystemNetHttp needed? What happens if I don't specifiy it?
• Are the certificates used are different than the ones used by the server?
• Once I registered the Github provider, how can I challenge it? Does automatically use identity_provider?
• A bit of an edge case but when I also use Steam auth (Open ID 2.0), can I use identity_provider=steam?

Additional context

No response

OpenIddict RC2 will include schema changes and will require updating columns in the applications and authorizations tables. That can be simplified using a tiny script that should be included in the how-to:

private async Task UpdateOpenIddictTablesAsync(IServiceProvider services)
{
    using (var scope = services.GetRequiredService<IServiceScopeFactory>().CreateScope())
    {
        var context = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
        await context.Database.EnsureCreatedAsync();

        foreach (var application in context.Set<OpenIddictApplication>())
        {
            // Convert the space-separated PostLogoutRedirectUris values to JSON.
            if (!string.IsNullOrEmpty(application.PostLogoutRedirectUris) && application.PostLogoutRedirectUris[0] != '[')
            {
                application.PostLogoutRedirectUris = new JArray(application.PostLogoutRedirectUris.Split(
                    new[] { " " }, StringSplitOptions.RemoveEmptyEntries)).ToString(Formatting.None);
            }

            // Convert the space-separated RedirectUris values to JSON.
            if (!string.IsNullOrEmpty(application.RedirectUris) && application.RedirectUris[0] != '[')
            {
                application.RedirectUris = new JArray(application.RedirectUris.Split(
                    new[] { " " }, StringSplitOptions.RemoveEmptyEntries)).ToString(Formatting.None);
            }

            if (string.IsNullOrEmpty(application.Permissions))
            {
                application.Permissions = new JArray(OpenIddictConstants.Permissions.Wildcard).ToString(Formatting.None);
            }
        }

        foreach (var authorization in context.Set<OpenIddictAuthorization>())
        {
            // Convert the space-separated Scopes to JSON.
            if (!string.IsNullOrEmpty(authorization.Scopes) && authorization.Scopes[0] != '[')
            {
                authorization.Scopes = new JArray(authorization.Scopes.Split(
                    new[] { " " }, StringSplitOptions.RemoveEmptyEntries)).ToString(Formatting.None);
            }
        }

        await context.SaveChangesAsync();
    }
}

Add a simple device flow sample. If I figure it, I'll setup a pull request..

Things like sliding expiration, reference tokens, rolling tokens, opaque/JWT tokens should be explained in a dedicated page.

Confirm you've already contributed to this project or that you sponsor it

• I confirm I'm a sponsor or a contributor

Describe the solution you'd like

We're getting close to 4.0 RTM, so we'll need to work on a migration guide listing the major changes between 3.x and 4.x.

Additional context

No response

openiddict/openiddict-core#548

OpenIddict 3.0 returns error_uris containing a link to this repository. We should progressively document all the errors returned by the server and validation stacks.

Example of a link: https://documentation.openiddict.com/errors/ID2093

Confirm you've already contributed to this project or that you sponsor it

• I confirm I'm a sponsor or a contributor

Describe the solution you'd like

Many steps are not specific to OpenIddict (like how to add a certificate to the Windows Certificates Store), but folks who are not familiar with this procedure might be blocked or afraid to do things incorrectly.

Consider adding a how-to guide indicating how to deploy an OpenIddict-based application.

Additional context

openiddict/openiddict-samples#188

Confirm you've already contributed to this project or that you sponsor it

• I confirm I'm a sponsor or a contributor

Describe the solution you'd like

openiddict/openiddict-core#1690 (comment)

Additional context

No response

Hi @PinpointTownes ,

I want to start looking into generating the API documentation for the OpenIddict assemblies. Docfx can generate metadata for the classes in a project from the source code, and then subsequently generate the docs from that.

In the case of OpenIddict, the docs repo (this current repo) lives separately from the actual source code of the project (openiddict/openiddict-core), so for the CI server to build the docs correctly, we will somehow need to be able to reference the source code file from this repo.

Two quick options that comes to mind:

1. Add the openiddict-core repo as a git submodule to this one
2. Update the AppVeyor build script to also check out the openiddict-core repo somewhere

The first option would be most seamless probably to other people who want to contribute to this repo. The second option would mean that when people want to build the docs on their own computer, they need to manually clone the openiddict-core repo as well to the same relative path as the AppVeyor build script does, so docfx can reference those file correctly locally.

I am sure you probably have some other questions and perhaps another suggestion to handle this, so this is just to kick off the discussion

2 goals:

• Describe how to use the correct overloads when using a custom key type or custom entities derived from the default entities.

• Add a few hints about you can create custom stores when opting for custom entities that don't derive from the built-in ones.

(opened on behalf of Weston Weems)

Confirm you've already contributed to this project or that you sponsor it

• I confirm I'm a sponsor or a contributor

Describe the solution you'd like

Enabling the degraded mode has multiple effects that should be listed in the documentation:

// Explicitly disable all the features that are implicitly excluded when the degraded mode is active.
if (options.EnableDegradedMode)
{
    options.DisableAuthorizationStorage = options.DisableTokenStorage = options.DisableRollingRefreshTokens = true;
    options.IgnoreEndpointPermissions = options.IgnoreGrantTypePermissions = true;
    options.IgnoreResponseTypePermissions = options.IgnoreScopePermissions = true;
    options.UseReferenceAccessTokens = options.UseReferenceRefreshTokens = false;
}

https://github.com/openiddict/openiddict-core/blob/186d3d8ddb84d600876e620fe9c236748a7e885b/src/OpenIddict.Server/OpenIddictServerConfiguration.cs#L31-L38

Additional context

No response

The documentation for EF Core can be reused but the "custom key type" will differ as EF 6.x doesn't support generic entities (non-generic custom entities are required for this scenario to work): https://documentation.openiddict.com/integrations/entity-framework-core.html

We should update the home page with at least a description of what OpenIddict consists in, a few links to the samples we have and probably some other things like a contact info or a link to the OpenID Connect specification.

/cc @jerriep

Is your feature request related to a problem?

I have been looking for information related to this process, but it seems to be rather piecemeal between the OpenIddict docs themselves (which are a good jumping off point) and searching for information in StackOverflow/github.

Describe the solution you'd like

I would like there to be some kind of document about the basic process for migrating from ASOS to using OpenIddict. Highlighting the things that are no longer relevant, or what the new versions of the old stuff was.

Additional context

I am trying to go through this process during the process of updating an OpenIdConnect server built on Net Framework and ASOS (a very early version of ASOS) to work on net5.0 and OpenIddict.

I would be happy to contribute to such a document in any way I can as I am going through this process.

In case it is easier to just answer some questions outright rather than creating (and maintaining) this proposed migration document, I'm going to include my current set of questions/problems:

• I am trying to figure out how to migrate a OpenIdConnectServerProvider-derived class that was being used on Net Framework. There's some custom code in there that hooks into the process, and I'm trying to evaluate whether that code just needs to move into a new abstraction that OpenIddict has, or if it can be removed entirely.
  • The most common code that exists in this old class is request validation - we had a custom data layer so we look up the client by the client_id parameter, and then verify the client_secret, and any redirect_uris (including logout redirect_uri).
    • Is this now handled automatically when using the OpenIddict data stores? The current plan was to take the existing data models we have and have them use the new OpenIddict base model(s), where applicable.
    • How would one go about customizing this process? For example, if we have applied encryption/hashing to the client_secret that is being stored at rest, we would need to apply that process to the incoming client_secret in order to properly match.
  • A lot of the usefulness of this derived class was purely for debugging - by overriding the base class methods (and doing nothing), it made it easy to add breakpoints during local debugging.
    • How would something like this be handled in the OpenIddict world? I realize there is the ILogger integration that may be useful in this aspect, but curious if that would be the only tool for such debugging or if the built-in extension points would facilitate this desire.
• How to handle programmatic sign-in/sign-out. Currently this is being done at times in a service which is called from the above Provider implementation, and also during some non-OpenIddict processes such as when a user changes their password or changes some part of their information, such as their email address or name.

openiddict/openiddict-core#457

Our metadata action currently points to the .cs files to work around a limitation in DocFX, that doesn't seem to support MSBuild SDKs (yet OpenIddict uses Arcade).

Sadly this comes with annoying limitations and many references are currently not correctly resolved.

Confirm you've already contributed to this project or that you sponsor it

• I confirm I'm a sponsor or a contributor

Version

4.x

Question

We are deploying our .net core 6 web app to Azure App Service environment.

I followed the guidelines from https://documentation.openiddict.com/configuration/encryption-and-signing-credentials.html#registering-a-certificate-recommended-for-production-ready-scenarios to generate two self-signed RSA certificates, uploaded it to Azure app service and added/set appsetting/configuration WEBSITE_LOAD_CERTIFICATES to *.

In the StartUp.cs, I added these lines:
options.AddEncryptionCertificate("cert-thumbprint-1", StoreName.My, StoreLocation.CurrentUser);
options.AddSigningCertificate("cert-thumbprint-2", StoreName.My, StoreLocation.CurrentUser);

However, there seems to be an issue with options.AddSigningCertificate, because when it is present the site gives error: HTTP Error 500.30 - ASP.NET Core app failed to start

When I remove that line and leave the line "options.AddEncryptionCertificate ...", the error message is: "InvalidOperationException: At least one asymmetric signing key must be registered in the OpenIddict server options.."

Do you have any suggestion on how I should go about adding the signing certificate? I have verified in a separate test web app that both certificates are accessible.

Thank you.
Fely Naval
Computer Packages Inc.