openiddict-documentation/guide/migration.md

# What's new in OpenIddict RC2?

The full list of changes can be found [here](https://github.com/openiddict/openiddict-core/milestone/8?closed=1). It includes **bug fixes** (including a bug fix in the refresh token handling) and new features like **application permissions**, that allow limiting the OpenID Connect features (endpoints and flows) an application is able to use.

# Migrate to OpenIddict RC2

**Migrating to OpenIddict RC2 (`1.0.0-rc2-*` and `2.0.0-rc2-*`) requires making changes in your database**: existing properties have been reworked (e.g [to work around a MySQL limitation](https://github.com/openiddict/openiddict-core/issues/497)) and new ones have been added to support the new features. This procedure is quite easy and only requires a few minutes.

> Note: this guide assumes your application uses the OpenIddict Entity Framework Core 2.x stores. If you use a custom store, changes will have to be made manually. A list of added/updated/renamed columns is available at the end of this guide.

## Ensure migrations are correctly enabled for your project

**Before migrating to OpenIddict RC2, make sure migrations are already enabled for your application**. If you have a `Migrations` folder in your application root folder and an `__EFMigrationsHistory` table in your database, you're good to go.

If you don't have these Entity Framework Core artifacts, migrations are likely not enabled. To fix that, add the following entries in your `.csproj`:

```xml
<ItemGroup>
  <PackageReference Include="Microsoft.EntityFrameworkCore.Design"
                    Version="2.0.0" PrivateAssets="All" />
</ItemGroup>

<ItemGroup>
  <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet"
                          Version="2.0.0" />
</ItemGroup>
```

Then, open a new command line and add an initial migration using `dotnet ef migrations add InitialMigration` (**but don't apply it!**).

## Update your packages references

For that, simply update your `.csproj` file to point to the newest OpenIddict packages:

### ASP.NET Core 1.x

```xml
<ItemGroup>
  <PackageReference Include="OpenIddict" Version="1.0.0-rc2-*" />
  <PackageReference Include="OpenIddict.EntityFrameworkCore" Version="1.0.0-rc2-*" />
  <PackageReference Include="OpenIddict.Mvc" Version="1.0.0-rc2-*" />
</ItemGroup>
```

### ASP.NET Core 2.x

```xml
<ItemGroup>
  <PackageReference Include="OpenIddict" Version="2.0.0-rc2-*" />
  <PackageReference Include="OpenIddict.EntityFrameworkCore" Version="2.0.0-rc2-*" />
  <PackageReference Include="OpenIddict.Mvc" Version="2.0.0-rc2-*" />
</ItemGroup>
```

## Add a new migration

1. First, open a new command line and run `dotnet ef migrations add MigrateToOpenIddictRc2`.
2. **If you created an initial migration at step 1, remove it from the `Migrations` folder**.
3. Apply the `MigrateToOpenIddictRc2` migration using `dotnet ef database update MigrateToOpenIddictRc2`.

## Run the migration script to convert columns to the new format

For that, add the following snippet to your `Startup` class:

```csharp
private async Task UpdateOpenIddictTablesAsync(IServiceProvider services)
{
    using (var scope = services.GetRequiredService<IServiceScopeFactory>().CreateScope())
    {
        // Change ApplicationDbContext to match your context name if you've changed it.
        var context = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
        await context.Database.EnsureCreatedAsync();

        // If you use a different entity type or a custom key,
        // change this line (e.g OpenIddictApplication<long>).
        foreach (var application in context.Set<OpenIddictApplication>())
        {
            // Convert the space-separated PostLogoutRedirectUris property to JSON.
            if (!string.IsNullOrEmpty(application.PostLogoutRedirectUris) &&
                 application.PostLogoutRedirectUris[0] != '[')
            {
                var addresses = application.PostLogoutRedirectUris.Split(
                    new[] { " " }, StringSplitOptions.RemoveEmptyEntries);

                application.PostLogoutRedirectUris =
                    new JArray(addresses).ToString(Formatting.None);
            }

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

                application.RedirectUris = new JArray(addresses).ToString(Formatting.None);
            }
        }

        // If you use a different entity type or a custom key,
        // change this line (e.g OpenIddictAuthorization<long>).
        foreach (var authorization in context.Set<OpenIddictAuthorization>())
        {
            // Convert the space-separated Scopes property to JSON.
            if (!string.IsNullOrEmpty(authorization.Scopes) && authorization.Scopes[0] != '[')
            {
                var scopes = authorization.Scopes.Split(
                    new[] { " " }, StringSplitOptions.RemoveEmptyEntries);

                authorization.Scopes = new JArray(scopes).ToString(Formatting.None);
            }
        }

        await context.SaveChangesAsync();
    }
}
```

Then, at the end of the `public void Configure(IApplicationBuilder app)` method, add the following line:

```csharp
public void Configure(IApplicationBuilder app)
{
    app.UseDeveloperExceptionPage();

    app.UseStaticFiles();

    app.UseStatusCodePagesWithReExecute("/error");

    app.UseAuthentication();

    app.UseMvcWithDefaultRoute();

    // Run the migration script synchronously.
    UpdateOpenIddictTablesAsync(app.ApplicationServices).GetAwaiter().GetResult();
}

```

Run your application. Once it's correctly started, stop it and remove the migration script.

## If your authorization server uses introspection, make sure resources are set in the authentication ticket

**Setting an explicit list of resources is now required to allow client applications to introspect a token.**
For that, call `ticket.SetResources()` with the list of the client identifiers allowed to validate the token. E.g:

```csharp
var ticket = new AuthenticationTicket(
    new ClaimsPrincipal(identity),
    new AuthenticationProperties(),
    OpenIdConnectServerDefaults.AuthenticationScheme);

ticket.SetResources("tracking_api", "marketing_api");
```

## Optionally, update your code to grant applications the minimum required permissions

Starting with RC2, OpenIddict includes an optional feature codenamed "app permissions" that allows
controlling and limiting the OAuth2/OpenID Connect features a client application is able to use.

To learn more about this feature, read the [Application permissions documentation](~/features/application-permissions.md).

# List of changes (for applications using custom stores)

## Renamed properties

| Table                    | Old column name | New column name  | Observations                                                               |
|--------------------------|-----------------|------------------|----------------------------------------------------------------------------|
| OpenIddictApplications   | Timestamp       | ConcurrencyToken | The column type was changed to nvarchar to work around a MySQL limitation. |
| OpenIddictAuthorizations | Timestamp       | ConcurrencyToken | The column type was changed to nvarchar to work around a MySQL limitation. |
| OpenIddictScopes         | Timestamp       | ConcurrencyToken | The column type was changed to nvarchar to work around a MySQL limitation. |
| OpenIddictTokens         | Timestamp       | ConcurrencyToken | The column type was changed to nvarchar to work around a MySQL limitation. |
| OpenIddictTokens         | Ciphertext      | Payload          |                                                                            |
| OpenIddictTokens         | Hash            | ReferenceId      |                                                                            |

## Updated properties

| Table                    | Column name            | Observations                                                                |
|--------------------------|------------------------|-----------------------------------------------------------------------------|
| OpenIddictApplications   | PostLogoutRedirectUris | Values are now formatted as JSON arrays instead of space-separated strings. |
| OpenIddictApplications   | RedirectUris           | Values are now formatted as JSON arrays instead of space-separated strings. |
| OpenIddictAuthorizations | Scopes                 | Values are now formatted as JSON arrays instead of space-separated strings. |

## Added properties

| Table                    | Column name | Type          | Nullable |
|--------------------------|-------------|---------------|----------|
| OpenIddictApplications   | ConsentType | nvarchar(max) | Yes      |
| OpenIddictApplications   | Properties  | nvarchar(max) | Yes      |
| OpenIddictApplications   | Permissions | nvarchar(max) | Yes      |
| OpenIddictAuthorizations | Properties  | nvarchar(max) | Yes      |
| OpenIddictScopes         | DisplayName | nvarchar(max) | Yes      |
| OpenIddictScopes         | Properties  | nvarchar(max) | Yes      |
| OpenIddictScopes         | Resources   | nvarchar(max) | Yes      |
| OpenIddictTokens         | Properties  | nvarchar(max) | Yes      |