## Documentation

- About
- Read First
  - What is IdentityServer
  - Installation Scenarios
- Migrations
- Bootstrapping
- Configuration & Integration
  - AdminUI Settings
  - Configuring AdminUI
  - Configuring AdminUI (NuGet)
  - Integrating with Identity Server
  - Integrating with Identity Server Custom Schema
  - Integrating with Quickstarts
  - Enabling Logging
- Installation
  - IIS
  - Azure
    - Install in Azure
    - Create Azure Web App
  - Docker
  - NuGet
- Custom Database Connections
- Custom Identity Store
  - Overview
  - Partial Implementation
  - Full Implementation
  - Tenancy With Entity Framework
  - NoSql Implementation (MongoDB)
- Custom CSP
- Users
  - Searching for Users
  - Adding Users
  - Editing Users
  - Deleting Users
  - Merge Users
  - Set User Password
  - Session Management
  - User Reports
  - Bulk User Import
- Roles
  - Creating Roles
  - Managing Roles
  - Managing Users in a Role
  - Managing Role Claims
- Claim Types
- Clients
  - Searching for Clients
  - Adding Clients
  - Adding a SAML Client
  - Adding a WS-Fed Client
  - Editing Clients
  - Deleting Clients
  - Clone Client
- Import and Export
  - Exporting Clients
  - Importing Clients
  - Importing Client Configuration with Secrets
  - Importing SAML Clients with Certificates
  - Import and Export Via the API
- Dynamic Authentication Providers
  - What is Dynamic Authentication
  - Enabling or disabling Dynamic Authentication
  - Add a Dynamic Provider
    - First Steps
    - Adding OIDC Provider
    - Adding SAML Provider
  - Edit a Dynamic Provider
    - Accessing edit view
    - Editing a OIDC Provider
    - Editing a SAML Provider
  - Deleting a Provider
  - Searching for Provider
- Resources
  - Searching for Resources
  - Creating Resources
  - Editing resources
- Webhooks
  - Webhooks
  - Endpoint Configuration
- MCP
  - Overview
  - Default Server Prompt Instructions
- User Settings Endpoints
- Access Policy
- Keys
- Auditing
- FAQs
- Troubleshooting
  - Unable to start AdminUI
  - Unable to contact IdentityServer
  - Unable to contact API
  - Unable to log in

### Migrations

- -Migrating IdentityServer and ASP.NET Identity Core to AdminUI
- -AdminUI Migrations
- -Migration Arguments
- -Schema Checker
- -Schema Check Arguments
- -Docker Migrations
- -TargetIdentityServer4
- -Running Migrations with a Custom Database Schema
- -Setup Steps

## Migrating IdentityServer and ASP.NET Identity Core to AdminUI

If you have an existing IdentityServer or ASP.NET Identity Core setup, then you will need to run script-based migrations on their respective databases before being able to apply the AdminUI migrations. The scripts are only available for SqlServer and would need to be modified to run for PostgreSql or MySql.

Before running the migration scripts, you will need to back up your databases, as there is no rollback script available from this point.

To migrate your ASP.NET Identity Core schema to then be able to run further migrations you can use the script found here: Migration script.

This script should work with ASP.NET Identity Core 8.0, 7.0, 6.0, 5.0, and 3.1.

This requires you to have all AspNetUserClaims records to have a ClaimType value and will add columns and tables to your database. Once the script has finished running you can apply the Identity migration from the AdminUI Migrations section.

To migrate your IdentityServer schema to then be able to run further migrations you can use the script found here: Migration script.

The Identity Server schema migration script will work with all versions of Identity Server. If you are migrating to earlier versions of AdminUI and IdentityServer you may need to consult the below table for modifications you may need to make to the migration history section if you want to use the AdminUI migration tool when upgrading to future versions.

Version | Support | Migration History
--- | --- | ---
Duende IdentityServer v4 | yes | Comment out migration history after '20200702080430_V3toV4SqlServerOperationalDbMigration' line 104
Duende IdentityServer v5 | yes | Comment out migration history after '20210602110024_PersistedGrantConsumeTimeSqlServerOperationalMigration' line 108
Duende IdentityServer v6 | yes | Comment out migration history after '20230620153729_Duende63ConfigurationUpdate' line 113
Duende IdentityServer v7 | yes | -- Nothing to do --
Open.IdentityServer v1 | yes | -- Nothing to do --

Once the script has finished running you can apply the Configuration, ExtendedConfiguration and Operational migrations from the AdminUI Migrations section.

## AdminUI Migrations

AdminUI comes with a tool to run all the necessary migrations. Alongside its own migrations, AdminUI can optionally run and maintain your IdentityServer and our Identity migrations, or you can handle them yourself. If you own SAML2P or WS-Fed, and wish to use its respective features within AdminUI, you will need to run their migrations.

By navigating to your AdminUI install directory and locating the IdentityExpress.Manager.UI.Duende.dll you can you run the dll using

    dotnet IdentityExpress.Manager.UI.Duende.dll -migrate <migration-to-run>

AdminUI has a number of different migrations that need to be run, you can run one individually or choose to run them all at once.

The different migrations options are:

Migration Type | Description
--- | ---
All | Runs all the migrations (Recommended for Demo users)
IdentityServerOnly | Runs AdminUI migrations along with the IdentityServer migrations (Migrations: Configuration, Operational, ExtendedConfiguration, Audit, Saml, WsFed and DataProtection)
IdentityOnly | Runs AdminUI migrations along with the Identity migrations (Migrations: Identity, ExtendedConfiguration, Audit, Saml, WsFed and DataProtection)
AdminUI | Runs only AdminUI migrations (Migrations: ExtendedConfiguration, Audit, Saml, WsFed and DataProtection)
Configuration | IdentityServer4 Configuration Migration
ExtendedConfiguration | AdminUI IdentityServer4 extension
Operational | IdentityServer4 Operational migration
Identity | ASP Identity Migration
Audit | RSK AdminUI Audit Migration
Saml | SAML2P Component migration
WsFed | Ws-Federation Component migration
DataProtection | DataProtection Key Migration (used if protecting cookies with a Database)

A help function may be accessed by adding -help

Supported DbProviders

- `SqlServer`
- `MySql`
- `PostgreSql`

You may also specify a connection string and which database provider you are you using with -connectionstring and -dbprovider. The connection string must be valid and surrounded by quotes. If no connectionstring and dbprovider are given, the migration tool will look in AdminUI's appsettings.json for the values.

### Migration Arguments

- `-dbProvider` Allows you to override the configured dbProvider when running migrations, with the value provided following the argument
- `-connectionString` Allows you to override the configured database connection string with a value provided following the argument
- `-timeout` Allows you to customise the command timeout value used when running migrations

## Schema Checker

AdminUI also comes with a tool that you can use to compare the expected IdentityServer database schema with your own IdentityServer schema.

By navigating to your AdminUI install directory and locating the IdentityExpress.Manager.UI.Duende.dll you can you run the dll using

    dotnet IdentityExpress.Manager.UI.Duende.dll -schema <schema-to-check>

The different schema options are:

Migration Type | Description
--- | ---
Configuration | IdentityServer4 Configuration Migration
Operational | IdentityServer4 Operational migration
Identity | ASP Identity Migration
Audit | RSK AdminUI Audit Migration
DataProtection | DataProtection Key Migration (used if protecting cookies with a Database)

A help function may be accessed by adding -help

Supported DbProviders

- `SqlServer`
- `MySql`
- `PostgreSql`

After performing the schema check on the specified schema, a JSON encoded response object will be returned in the console. The object contains the following values: 'IsValid', 'Exists', 'ErrorMessages', 'SchemaType'.

If the response object's 'Exists' value is true, then the schema checker has identified that there are tables present in your database that relate to the schema it is checking.

The response object's 'IsValid' relates to if your database contains all the necessary tables and columns required for the schema you are checking. 'IsValid' is true when all tables and columns exist for a schema, and also when no tables and columns exist for a schema.

The 'ErrorMessages' section of the response object will contain information relating to any missing tables or columns in your database when compared to the schema you are checking.

You may also specify a connection string and which database provider you are you using with -connectionstring and -dbprovider. The connection string must be valid and surrounded by quotes. If no connectionstring and dbprovider are given, the migration tool will look in AdminUI's appsettings.json for the values.

### Schema Check Arguments

- `-dbProvider` Allows you to override the configured dbProvider when running migrations, with the value provided following the argument
- `-connectionString` Allows you to override the configured database connection string with a value provided following the argument

## Docker Migrations

If the container is not running and you would like to run migrations use the following command

    docker run -e "DbProvider=<YourProvider>" -e "IdentityConnectionString=<YourConnectionString>" -e IdentityServerConnectionString="<YourConnectionString>" --entrypoint dotnet rocksolidknowledge/adminui IdentityExpress.Manager.UI.Duende.dll -migrate all

Note - The full list of configuration options is avaliable here

If the container is already running the steps to run migrations are as follows:

- Find the container ID by running the “docker container ps” command
- Once found, you can exec the command as follows:

    docker exec <container-id> dotnet IdentityExpress.Manager.UI.Duende.dll -migrate all

Note - This will use the environment variables already passed into the container.

You will see the output of the migrations in your command line window.

## TargetIdentityServer4

Make sure to back up your database before running any migrations against it as there is no way to easily revert changes once they have been applied.

The value of the `TargetIdentityServer4` flag in AdminUI's configuration will determine what kind of database the AdminUI migrations will create/update.

If set to `true`, the AdminUI migration tool will perform IdentityServer4 migrations.

If set to `false`, the AdminUI migration tool will perform Duende IdentityServer migrations.

If you have performed the AdminUI migrations while targeting IdentityServer4 but wish to upgrade your database to target IdentityServer Duende, you can update the `TargetIdentityServer4` flag to `false` and run the migrations again. The AdminUI migration tool will then update your database to be in line with the latest Duende IdentityServer schema.

## Running Migrations with a Custom Database Schema

AdminUI supports running migrations with a custom database schema in SqlServer and PostgreSql. The schema configuration must be set at the database level rather than in the application configuration.

### Setup Steps

To configure a custom schema:

1. Create the database and custom schema

Create your database and define the custom schema within it.

#### PostgreSql

1. Add the custom schema to your connections string using `Search Path`

   Example: `"Server=localhost; Port=5433; Uid=MyUserName;Pwd=Password123!;Database=MyDatabase;Search Path=MyCustomSchema;"`

#### SqlServer

1. Configure a database user

Create a database user and assign the custom schema as the user's default schema.

1. Update your connection string

Use the configured user in your AdminUI database connection string.

When using SQL Server, be aware of the following limitation:

- Users with `sysadmin` role cannot use custom default schemas

If your database user is assigned the `sysadmin` fixed server role, SQL Server will ignore the default schema setting and always use `dbo`. This is a SQL Server limitation, not an AdminUI restriction.

To use a custom schema, ensure your database user does not have the `sysadmin` role. Instead, grant only the specific permissions required for running migrations and operating AdminUI.

For more information, see Microsoft's ALTER USER documentation.

Previous Next