# Dynamic Client Registration (DCR)

> Learn how to configure and use Dynamic Client Registration (DCR) to automatically register OAuth clients with IdentityServer

Dynamic Client Registration (DCR) is the process of registering OAuth clients dynamically. It allows OAuth client applications to programmatically register themselves with an authorization server at runtime, rather than requiring manual configuration.

The client provides information about itself and specifies its desired configuration in an HTTP request to the configuration endpoint. If the request is authorized and valid, the endpoint will then create the necessary client configuration and return an HTTP response describing the new client.

DCR eliminates the need for a manual registration process, making it more efficient and less time-consuming to register new clients. It can help automate the onboarding of new applications in large-scale OAuth ecosystems, such as microservices, mobile apps, and partner APIs.

## Installation And Hosting

[Section titled âInstallation And Hostingâ](#installation-and-hosting)

DCR in Duende IdentityServer is provided as a separate NuGet package, [`Duende.IdentityServer.Configuration`](https://www.nuget.org/packages/Duende.IdentityServer.Configuration), which contains the Configuration API and endpoints required to support DCR.

The Configuration API can be installed in a separate host from IdentityServer, or in the same host. In many cases, it is desirable to host the configuration API and IdentityServer separately. This facilitates the ability to restrict access to the configuration API at the network level separately from IdentityServer and keeps IdentityServerâs access to the configuration data read-only. In other cases, you may find that hosting the two systems together better fits your needs.

### Separate Host For Configuration API

[Section titled âSeparate Host For Configuration APIâ](#separate-host-for-configuration-api)

To host the Configuration API separately from IdentityServer, you will need to create a new ASP.NET Core Web application which will host the Configuration API.

1. **Create a new project of type âEmpty Web Applicationâ**

   Terminal

   ```bash
   dotnet new web -n Configuration
   ```

2. **Add the `Duende.IdentityServer.Configuration` package**

   Terminal

   ```bash
   cd Configuration
   dotnet add package Duende.IdentityServer.Configuration
   ```

3. **Configure services to include the Configuration API**

   Program.cs

   ```csharp
   builder.Services.AddIdentityServerConfiguration(opt =>
       opt.LicenseKey = "<license>";
   );
   ```

   Note

   This feature is part of the [Duende IdentityServer Business and Enterprise Edition](https://duendesoftware.com/products/identityserver). Configure the same license key for IdentityServer and the Configuration API.

4. **Add and configure the client configuration store**

   The Configuration API uses the `IClientConfigurationStore` abstraction to persist new clients to the configuration store. Your Configuration API host needs an implementation of this interface.

   You can either use the Entity Framework Core-based implementation, or implement the interface yourself. See [the IClientConfigurationStore reference](/identityserver/reference/stores/) for more details. If you wish to use the built-in implementation, install its NuGet package and add it to the ASP.NET Core service provider.

   Terminal

   ```bash
   dotnet add package Duende.IdentityServer.Configuration.EntityFramework
   ```

   The `AddClientConfigurationStore()` extension method registers the built-in implementation of the `IClientConfigurationStore` interface with the service provider. Make sure to also configure the connection string to the [configuration store](/identityserver/data/ef/#configuration-store-support):

   Program.cs

   ```csharp
   builder.Services.AddIdentityServerConfiguration(opt =>
       opt.LicenseKey = "<license>"
   ).AddClientConfigurationStore();


   var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
   builder.Services.AddConfigurationDbContext<ConfigurationDbContext>(options =>
   {
       options.ConfigureDbContext = builder => builder.UseSqlite(connectionString);
   });
   ```

5. **Map the Configuration API endpoints**

   Program.cs

   ```csharp
   app.MapDynamicClientRegistration()
      .RequireAuthorization("DCR");
   ```

   The `MapDynamicClientRegistration` extension method registers the DCR endpoints and returns an `IEndpointConventionBuilder` which you can use to define authorization requirements for your DCR endpoint.

   See [Authorization](#authorization) for more details about implementing authorization for the DCR endpoint.

### Shared Host For Configuration API and IdentityServer

[Section titled âShared Host For Configuration API and IdentityServerâ](#shared-host-for-configuration-api-and-identityserver)

The Configuration API can be hosted by your Duende IdentityServer host. Youâll need to add the Configuration APIâs services to the service collection, and configure the store implementation.

1. **Add the `Duende.IdentityServer.Configuration` package**

   Terminal

   ```bash
   cd Configuration
   dotnet add package Duende.IdentityServer.Configuration
   ```

2. **Configure services to include the Configuration API**

   Program.cs

   ```csharp
   builder.Services.AddIdentityServerConfiguration(opt =>
       opt.LicenseKey = "<license>";
   );
   ```

   Note

   The Configuration API feature is included in the Duende IdentityServer Business edition license and higher. Use the same license key for IdentityServer and the Configuration API.

3. **Add and configure the client configuration store**

   The Configuration API uses the `IClientConfigurationStore` abstraction to persist new clients to the configuration store. Your Configuration API host needs an implementation of this interface.

   You can either use the Entity Framework Core-based implementation, or implement the interface yourself. See [the IClientConfigurationStore reference](/identityserver/reference/stores/) for more details. If you wish to use the built-in implementation, install its NuGet package and add it to the ASP.NET Core service provider.

   Terminal

   ```bash
   dotnet add package Duende.IdentityServer.Configuration.EntityFramework
   ```

   The `AddClientConfigurationStore()` extension method registers the built-in implementation of the `IClientConfigurationStore` interface with the service provider. Make sure to also configure the connection string to the [configuration store](/identityserver/data/ef/#configuration-store-support) if you havenât already as part of your IdentityServer host:

   Program.cs

   ```csharp
   builder.Services.AddIdentityServerConfiguration(opt =>
       opt.LicenseKey = "<license>"
   ).AddClientConfigurationStore();


   var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
   builder.Services.AddConfigurationDbContext<ConfigurationDbContext>(options =>
   {
       options.ConfigureDbContext = builder => builder.UseSqlite(connectionString);
   });
   ```

4. **Map the Configuration API endpoints**

   Program.cs

   ```csharp
   app.MapDynamicClientRegistration()
      .RequireAuthorization("DCR");
   ```

   The `MapDynamicClientRegistration` extension method registers the DCR endpoints and returns an `IEndpointConventionBuilder` which you can use to define authorization requirements for your DCR endpoint.

   See [Authorization](#authorization) for more details about implementing authorization for the DCR endpoint.

## Authorization

[Section titled âAuthorizationâ](#authorization)

When implementing Dynamic Client Registration (DCR), it is important to consider authentication and authorization for the Configuration API endpoint. While not strictly required, it is recommended that you implement some form of authentication and authorization for the DCR endpoint. You donât want anyone with access to the DCR endpoint to be able to register clients!

The specifications that define DCR allow both open registration, where authentication and authorization are absent and all client software can register with the authorization server, and protected registration, where an initial access token is required to register.

The Configuration API creates standard ASP.NET endpoints that can be protected through traditional ASP.NET authorization. Alternatively, the Dynamic Client Registration `software_statement` parameter can be used to authenticate requests.

### Traditional ASP.NET Authorization

[Section titled âTraditional ASP.NET Authorizationâ](#traditional-aspnet-authorization)

You can authorize access to the Configuration API Endpoints using [authorization policies](https://learn.microsoft.com/en-us/aspnet/core/security/authorization/policies), just like any other endpoint created in an ASP.NET Web application. That authorization policy can use any criteria that an authorization policy might enforce, such as checking for particular claims or scopes.

One possibility is to authenticate the provisioning system, that is, the system making the DCR call, using OAuth. The resulting access token could include a scope that grants access to the Configuration API.

For example, you might protect the Configuration APIs with a JWT-bearer authentication scheme and an authorization policy that requires a particular scope to be present in the JWTs. You could choose any name for the scope that gives access to the Configuration APIs. Letâs use the name `IdentityServer.Configuration` for this example. You would then define the `IdentityServer.Configuration` scope as an [ApiScope](/identityserver/reference/models/api-scope/) in your IdentityServer and allow the appropriate clients to access it.

An automated process running in a CI pipeline could be configured as an OAuth client that uses the client credentials flow and is allowed to request the `IdentityServer.Configuration` scope. It could obtain a token using its client id and secret and then present that token when it calls the Configuration API. You might also have an interactive web application with a user interface that makes calls to the Configuration API. Again, you would define the application as an OAuth client allowed to request the appropriate scope, but this time, youâd use the authorization code flow.

### Software Statement

[Section titled âSoftware Statementâ](#software-statement)

The metadata within requests to the Configuration API can be bundled together into a JWT and sent in the [`software_statement` parameter](https://datatracker.ietf.org/doc/html/rfc7591#section-2.3). If you can establish a trust relationship between the Configuration API and the issuer of the software statement, then that can be used to decide if you want to accept registration requests.

To use a software statement in this way, you would need to design the specific semantics of your software statements. How you will issue them, how you will create the necessary trust relationship between the issuer and your Configuration API, and how the Configuration API will validate the software statements are all aspects to consider.

The configuration API doesnât make any assumptions about the software statement design. By default, it does nothing with the `software_statement` parameter.

To make use of software statements, customize the `DynamicClientRegistrationValidator.ValidateSoftwareStatementAsync` extension point and add your validation logic.

## Calling The Registration Endpoint

[Section titled âCalling The Registration Endpointâ](#calling-the-registration-endpoint)

The registration endpoint is invoked by making an HTTP POST request to the `/connect/dcr` endpoint with a JSON payload containing metadata describing the desired client as described in [RFC 7591](https://datatracker.ietf.org/doc/rfc7591/) and [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html).

The supported metadata properties are listed in the reference section on the [`DynamicClientRegistrationRequest` model](/identityserver/reference/dcr/models/#dynamicclientregistrationrequest). A mixture of standardized and IdentityServer-specific properties are supported. Most standardized properties that are applicable to the client credentials or code flow grants are supported.

Where IdentityServerâs configuration model includes important properties that are not standardized, we have included those properties as extensions. For example, there are no standardized properties describing token lifetimes, so the dynamic client registration endpoint adds `absolute_refresh_token_lifetime`, `access_token_lifetime`, `identity_token_lifetime`, etc.

## Customization

[Section titled âCustomizationâ](#customization)

The behavior of the Configuration API can be customized through the use of several extension points that control the steps that occur when a dynamic client registration request arrives.

First, the incoming request is validated to ensure that it is syntactically valid and semantically correct. The result of the validation process is a model which will either contain error details or a validated `Client` model.

When validation succeeds, the validated request is passed on to the request processor. The request processor is responsible for generating properties of the `Client` that are not specified in the request. For example, the `client_id` is not normally specified in the request and is instead generated by the processor.

When the processor is finished generating values, it passes the final client object to the store and returns an `IDynamicClientRegistrationResponse` indicating success or failure. This response object is finally used by the response generator to generate an HTTP response.

Each of the validation and processing steps might also encounter an error. When that occurs, errors are conveyed using the `DynamicClientRegistrationError` class.

### Validation

[Section titled âValidationâ](#validation)

To customize the validation process, you can implement the `IDynamicClientRegistrationValidator` interface, or extend the default implementation, `DynamicClientRegistrationValidator`. The default implementation includes many virtual methods, allowing you to use most of the base functionality and add your customization in a targeted manner.

Each virtual method is responsible for validating a small number of parameters in the request and setting corresponding values on the client. A context object is passed to each virtual method. It contains the client object that is being built up, the original request, the claims principal that made the request, and a dictionary of additional items that can be used to pass state between customized steps. Each step should update the client in the context and return an `IStepResult` to indicate success or failure.

For more details, see the [reference section on DCR validation](/identityserver/reference/dcr/validation/).

### Processing

[Section titled âProcessingâ](#processing)

The request processor can be customized by implementing the `IDynamicClientRegistrationRequestProcessor` interface, or by extending the default `DynamicClientRegistrationRequestProcessor`. The default request processor contains virtual methods that allow you to override (part of) its functionality.

For more details, see the [reference section on DCR request processing](/identityserver/reference/dcr/processing/).

### Response Generation

[Section titled âResponse Generationâ](#response-generation)

To customize the HTTP responses of the Configuration API, you can implement the `IDynamicClientRegistrationResponseGenerator` interface, or extend the default `DynamicClientRegistrationResponseGenerator`.

For more details, see the [reference section on rDCR esponse generation](/identityserver/reference/dcr/response/).
-----