Authorization Server Installation

Introduction

The first step to install MibAuthorizationServer is to prepare the database that will be used by the server. This can be easily done through the MibMigrator tool currently available inside the MibDlls folder.

Then one just need to extract the MibAuthorization package into IIS “www” folder, convert its folder to an app through IIS manager and add various config files and options.

The following sessions will explain this procedure in depth.

AuthorizationServerOverview.md — how the server works: architecture, OpenIddict engine, schemes, keys, endpoints, database mapping and code map.
AuthorizationServerAuthenticationFlows.md — sequence diagrams for each flow (interactive login + authorization code, ROPC, client credentials, refresh, protected-resource validation, logout).
AuthorizationServerConfiguration.md — registering clients and configuring token lifetimes / keys.
TokenValidationAcrossInstances.md — the rootUrl rule for multi-instance deployments (tokens only validate on instances sharing one issuer) and what the password grant returns.

OAuth/OIDC engine: OpenIddict (since MEDIAIBOX-11999)

As of MIB 6.0 the Authorization Server's OAuth/OIDC engine runs on OpenIddict 5.8.0 (.NET 8). It previously ran on IdentityServer4 (v3.1.4), which is end-of-life; IdentityServer4 has been fully removed (packages, code path and DI wiring).

The migration is parity-first, so most of this guide is unchanged: same database tables, same endpoints (/oauth/token, /oauth/authorize, /connect/*, /.well-known/openid-configuration + …/jwks), same grant types (authorization_code, password/ROPC, client_credentials, refresh_token), RS512 signing, and reference (opaque) access tokens. Client rows in API_CLIENTS (ids, secrets — still plain text — and REDIRECT_URI) keep working as-is.

Upgrade ToDo (what's needed to bring up this version)

Run the MibAuthorizationServer database migration so the new table AUTH_ENC_CREDENTIALS exists (migration 202606101200000_Mib_AddEncryptionCredentials). All other tables are untouched. See Migration: Generating Database.
Let the encryption key persist. OpenIddict 5.x encrypts refresh tokens and authorization codes as JWE (AES-256) even with access-token encryption disabled, so a stable key is mandatory. It is auto-bootstrapped on first start and stored in AUTH_ENC_CREDENTIALS — do not wipe that table between restarts, and in multi-instance deployments all instances must share the same database. Sharing the database is necessary but not sufficient: all instances must also present the same rootUrl, or they will not validate each other's tokens — see TokenValidationAcrossInstances.md. An ephemeral key would invalidate every live refresh token/code on each restart.
useNewLoginUI must be true with the React Auth UI deployed. The legacy IdentityServer4 MVC login/consent path (including ~/consent) was removed; consent for first-party clients is now automatic/inline.
Token lifetimes moved to MibIdentityConfig.mibconfig. The MibAuthorizationServerConfig keys accessTokenMinutes, refreshTokenHours and authorizationCodeSeconds are no longer read. Re-apply any custom values in MibIdentityConfig (see the appendix sample and AuthorizationServerConfiguration.md). No action if you used defaults.
Plan a one-time forced re-login. Grants minted by IdentityServer4 in AUTH_GRANTS are not readable by OpenIddict, so going live invalidates all existing access/refresh tokens — users and integrations must authenticate once. There is no compatibility shim. Deploy in a low-traffic window and expect a transient spike of invalid_grant/invalid_client and of logins in ADM_USER_LOGIN_HISTORY (normal).
No in-app rollback flag. Earlier phases shipped both engines behind a useOpenIddict flag; this version is OpenIddict-only. Rollback means redeploying the previous (IdentityServer4) version — the schema is shared and additive, so a downgrade is possible, but tokens minted by OpenIddict in the meantime become invalid.

Prerequisites

IIS installed with MVC .NET support
MibPackages and MibDlls downloaded
Knowledge about MibConfigs
Database available to bootstrap

Migration: Generating Database

Every migration can be run through a neat utility provided by MIB, the MibMigrator which is available in the MibDlls package. All possible migrations are also provided in the same package to ease its use.

Three different configuration files are required:

MibLogConfig
MibDatabaseConfig
MibConfigurableObjectConfig

Where the third one can just be a dummy configuration file as no mapping is required. Configuration files samples can be seen in the appendix.

It is necessary to bootstrap every database used by MIB projects by running at least the MibClient2 migration before the main migration. Here is a sample CLI command with parameters to do just that (change paths for your environment):

> C:\MibDlls\MibMigrator\Migrator\mibmigrator.exe -assembly="C:\MibDlls\MibMigrator\MibClient2Migrations\MibClient2.MibDatabaseMigrations.dll" -configPath="C:\TestData\auth_migration\config"

After this migration, MibAuthorizationServer migration must be run with the same configuration files, and a sample command can be seen here:

> C:\MibDlls\MibMigrator\Migrator\mibmigrator.exe -assembly="C:\MibDlls\MibMigrator\MibAuthorizationServerMigrations\MibAuthorizationServer.MibDatabaseMigrations.dll" -⁠configPath="C:\TestData\auth_migration\config"

Important

The MibAuthorizationServer migration set includes 202606101200000_Mib_AddEncryptionCredentials, which creates the AUTH_ENC_CREDENTIALS table required by OpenIddict (token/code encryption key). Running the migration is mandatory when upgrading from an IdentityServer4-based deployment. The key itself is generated automatically on the server's first start and must persist across restarts.

Installing and enabling MibAuthorizationServer

After Migration:

If not downloaded, download MibPackages as we need the package file MibAuthorizationServer.zip
Extract it to “C:\inetpub\wwwroot%NAME%”, where %NAME can be any chosen name, such as MibAuth. In the remainder of this documentation %NAME% will be assumed as MibAuth.
Open “IIS Manager”, search for the folder in which the package was extracted, right click it and the chose “Convert to app”.

Before effectively being able to use the server, it must be configured by creating a “config” folder inside “C:\inetpub\wwwroot\MibAuth”, in which the configuration files and the dictionary folder will reside. Samples in the appendix.

Minimally required configuration files:

MibLogConfig
MibAuthorizationServerConfig
MibDatabaseConfig
MibCryptoConfig

Additional recommended configuration files:

MibTranslationConfig

It is important to correctly set the “clientSecret” field in MibAuthorizationServerConfig, which can be found by running the following command in the database:

SELECT OAUTH_CLIENT_SECRET FROM API_CLIENTS WHERE NAME = 'AuthPortal'

After adding the configuration files MibAuthorizationServer should be accessible through the set URL and the default user (“administrator”) should be enabled.

Deploying under a URL sub-path

When MibAuthorizationServer is served under a path prefix — for example as an IIS application named MibAuth, or behind a reverse proxy with location /MibAuth/ — you must set customUrlBase to that prefix (e.g. /MibAuth). This single value drives both the ASP.NET PathBase and the OAuth/OIDC endpoint registration, so the authorize, token, userinfo, introspection, revocation and end-session endpoints are recognized at /MibAuth/... in addition to their bare paths.

Important

If customUrlBase is not set on a sub-path deployment, interactive login dead-ends at /home/error: OpenIddict does not recognize the prefixed authorize path (/MibAuth/oauth/authorize), so the request is not treated as an authorization request and the controller falls through to the error page. Keep customUrlBase consistent with rootUrl (which already includes the path).

customUrlBase can be set, in order of precedence, via:

the customUrlBase key in MibAuthorizationServerConfig.mibconfig (see the sample below);
the environment variable MIBAUTHORIZATIONSERVERCONFIG_DEFAULT_CUSTOMURLBASE;
the CustomSettings:CustomUrlBase key in appsettings.json.

The bare paths (/oauth/authorize, /connect/token, …) remain registered as well, so same-origin browsers and internal service-to-service callers that reach the server directly (without the prefix) keep working.

Note

Leave customUrlBase empty when the server is hosted at the host root, with no sub-path (e.g. local development at http://localhost:8601/). In that case only the bare endpoint paths are registered.

Appendix: Sample configuration files

Most important fields are marked in bold.

MibConfigurableObjectConfig.mibconfig

<?xml version="1.0" encoding="utf-8" ?>
<mibConfig>
</mibConfig>

MibAuthorizationServerConfig.mibconfig

<?xml version="1.0" encoding="utf-8" ?>
<mibConfig>
  <default>
    <rootUrl>https://server/authPath</rootUrl>
    <!-- Set customUrlBase to the URL sub-path when deployed behind a reverse
         proxy / as an IIS app (e.g. /authPath). Omit when hosted at the host
         root. Drives the ASP.NET PathBase AND the OAuth endpoint registration. -->
    <customUrlBase>/authPath</customUrlBase>
    <tokenEndpoint>/oauth/token</tokenEndpoint>
    <authorizeEndpoint>/oauth/authorize</authorizeEndpoint>
    <loginEndpoint>/authPath/login</loginEndpoint>
    <logoutEndpoint>/authPath/logout</logoutEndpoint>
    <useNewLoginUi>true</useNewLoginUi>
    <frontendAppRootUrl>https://frontend.authserver/</frontendAppRootUrl>
    <allowInsecureHttp>false</allowInsecureHttp>
    <!-- DEPRECATED since MEDIAIBOX-11999 (OpenIddict): these three keys are
         no longer read. Configure token lifetimes in MibIdentityConfig.mibconfig. -->
    <authorizationCodeSeconds>30</authorizationCodeSeconds>
    <accessTokenMinutes>60</accessTokenMinutes>
    <refreshTokenHours>24</refreshTokenHours>
    <clientId>AuthPortal</clientId>
    <clientSecret>clientSecretFromDatabase</clientSecret>
    <workflowAssembly>MibAuthorizationServer.Workflow.MibServer</workflowAssembly>
    <workflowFactory>MibAuthorizationServer.Workflow.MibServer.MibDomainFactory</workflowFactory>
    <cookieName>mib_auth_server</cookieName>
    <mibjscompressionmode></mibjscompressionmode>
    <mibcsscompressionmode></mibcsscompressionmode>
    <mibJsCompressionDisableModifyDate></mibJsCompressionDisableModifyDate>
    <mibCssCompressionDisableModifyDate></mibCssCompressionDisableModifyDate>
    <language>en-us</language>
   </default>
</mibConfig>

MibIdentityConfig.mibconfig

Holds the OpenIddict token lifetimes and refresh-token model (see AuthorizationServerConfiguration.md). All keys are optional and default to IdentityServer4-parity values; include the file only if you need to override them.

<?xml version="1.0" encoding="utf-8" ?>
<mibConfig>
  <default>
    <AccessTokenLifetime>3600</AccessTokenLifetime>
    <absoluteRefreshTokenLifetime>2592000</absoluteRefreshTokenLifetime>
    <slidingRefreshTokenLifetime>1296000</slidingRefreshTokenLifetime>
    <authorizationCodeLifetime>300</authorizationCodeLifetime>
    <slidingRefreshTokenExpiration>false</slidingRefreshTokenExpiration>
    <reuseRefreshToken>false</reuseRefreshToken>
    <tokenCleanUpServiceEnabled>false</tokenCleanUpServiceEnabled>
  </default>
</mibConfig>

MibCryptoConfig.mibconfig

<?xml version="1.0" encoding="utf-8" ?>
<mibConfig>
  <default>
    <AESKey>setAesKey</AESKey>
    <DESKey>setDesKey</DESKey>
  </default>
</mibConfig>

MibDatabaseConfig.mibconfig

<?xml version="1.0" encoding="utf-8" ?>
<mibConfig>
  <default>
    <type>serverType</type>
    <server>serverAddress</server>
    <database>databaseName</database>
    <username>databaseUsername</username>
    <password>databasePassword</password>
  </default>
</mibConfig>

MibTranslationConfig.mibconfig

<?xml version="1.0" encoding="utf-8" ?>
<mibConfig>
  <default>
    <debugInvalidKeys>true</debugInvalidKeys>
    <debugAllKeys>false</debugAllKeys>
  </default>
  <en-us>
    <description>English</description>
    <dictionary>Dictionary\en-US.mibconfig</dictionary>
    <imageUrl></imageUrl>
  </en-us>
  <pt-br>
    <dictionary>Dictionary\pt-BR.mibconfig</dictionary>
    <imageUrl></imageUrl>
  </pt-br>
</mibConfig>

MibLogConfig.mibconfig

<?xml version="1.0" encoding="utf-8" ?>
<mibConfig>
  <default>
    <mibTrace>true</mibTrace>
    <fileLogTag>MibLog</fileLogTag>
    <fileLogPath>logFilePath</fileLogPath>
    <eventViewerLog>Application</eventViewerLog>
    <eventViewerSource>applicationName</eventViewerSource>
    <databaseAlias>default</databaseAlias>
    <databaseTable>MibLogs</databaseTable>
    <databaseField>Message</databaseField>
  </default>
  <verbose>
    <mibTrace>true</mibTrace>
    <trace>true</trace>
    <file>true</file>
    <database>false</database>
    <eventViewer>false</eventViewer>
    <custom>false</custom>
  </verbose>
  <log>
    <mibTrace>true</mibTrace>
    <trace>true</trace>
    <file>true</file>
    <database>false</database>
    <eventViewer>false</eventViewer>
    <custom>false</custom>
  </log>
  <errorLog>
    <mibTrace>true</mibTrace>
    <trace>true</trace>
    <file>true</file>
    <database>false</database>
    <eventViewer>false</eventViewer>
    <custom>false</custom>
  </errorLog>
  <exception>
    <mibTrace>true</mibTrace>
    <trace>true</trace>
    <file>true</file>
    <database>false</database>
    <eventViewer>false</eventViewer>
    <custom>false</custom>
  </exception>
</mibConfig>

As of Mib version 6.0.87, the new Login UI for Mib Authorization Server is available. To ensure proper integration and a smooth migration, follow the steps and recommendations below. The old UI will be permanently disabled in MIB 7.0.

Update your MibAuthorizationServerConfig and environment variables as needed:

`UseNewLoginUi`

Purpose: Enables the new Login UI (set to false to use the old UI)
Default: false
Required: No

Example (disable new UI):

MIBAUTHORIZATIONSERVERCONFIG_DEFAULT_USENEWLOGINUI=false

`FrontendAppRootUrl`

Purpose: Specifies the URL where the SPA (Single Page Application) for the Auth UI is served
Default: (empty)
Required: Yes

Note

The Auth UI app is served by default under the base path /auth. Set this value accordingly.

Example:

MIBAUTHORIZATIONSERVERCONFIG_DEFAULT_FRONTENDAPPROOTURL=http://localhost:8040/auth/

`CorsAllowCredentials`

Purpose: Allows credentials in cross-origin HTTP requests
Default: false
Required: No

Note

Only enable this if your backend and frontend are served from different origins. This is generally not recommended for production.

Example:

MIBAUTHORIZATIONSERVERCONFIG_DEFAULT_CORSALLOWCREDENTIALS=true

`CorsOrigins`

Purpose: Specifies allowed origins for CORS
Default: (empty)
Required: No

Note

Only set this if your backend and frontend are on different origins. Not recommended for production.

Example (allowing CORS from both Auth and CMS apps):

MIBAUTHORIZATIONSERVERCONFIG_DEFAULT_CORSORIGINS=http://frontend.authserver.com,http://frontend.cms.com.br

Docker Compose Example for Auth UI

To run the new Auth UI using Docker Compose, use the following example. Make sure to authenticate to the private registry using your GitHub token (the same used for the CMS React app image).

version: '3.8'
services:
  authreact:
    container_name: react_auth
    image: ghcr.io/agilecontent/mib-auth-frontend:latest
    restart: unless-stopped
    environment:
      - AUTH_URL=http://localhost:8601/
      - BASE_PATH=/auth
    ports:
      - 8081:8081
    networks:
      - default
networks:
  default:
    driver: bridge

Releases: https://github.com/agilecontent/MibFrontEnd/pkgs/container/mib-auth-frontend

Variables

The following environment variables are used to configure the Auth UI container:

AUTH_URL: The base URL where the Mib Authorization Server API is accessible. This should point to your deployed authorization server instance.
BASE_PATH: The base path under which the Auth UI is served. By default, this is /auth.

Example:

AUTH_URL="https://samples.mediaibox.com.br/MibAuth/"
BASE_PATH="/auth/"

Switching Back to the Old UI

Warning

No longer supported since MEDIAIBOX-11999 (OpenIddict). The legacy IdentityServer4 MVC login/consent path (including the ~/consent page) was removed with the engine migration. useNewLoginUI=false is therefore not a viable fallback on this version — keep useNewLoginUI=true and deploy the React Auth UI. The line below is kept only for historical reference for pre-migration (IdentityServer4) deployments.

MIBAUTHORIZATIONSERVERCONFIG_DEFAULT_USENEWLOGINUI=false

UI Customization

You can customize the colors and logo of the Auth UI using configuration keys in the Mib Authorization Server. For details, see the Auth UI - Theme configuration.

Recommendations for Production Environment

Serve both MibAuthorizationServer and the React Auth UI from the same origin (identical scheme, domain, and port) to avoid CORS issues and maximize security. If this is not possible, then make sure to be strict when configuring the allowed CorsOrigins and enable CorsAllowCredentials.
Always use HTTPS for all communications between the Auth UI and the Authorization Server to protect sensitive data.
Regularly monitor and update both the Auth UI and backend to ensure you receive the latest security patches and feature improvements.

Recommendations for Development Environment

You may serve the Auth UI and Authorization Server from different origins for development convenience.
Enable CorsAllowCredentials and configure CorsOrigins as needed to support cross-origin requests during development.
Use self-signed certificates or HTTP for local testing, but always validate your setup with HTTPS before moving to production.
Document any non-default configurations clearly for your team.

Table of Contents

Authorization Server Installation

Introduction

Related documentation

OAuth/OIDC engine: OpenIddict (since MEDIAIBOX-11999)

Upgrade ToDo (what's needed to bring up this version)

Prerequisites

Migration: Generating Database

Important

Installing and enabling MibAuthorizationServer

Deploying under a URL sub-path

Important

Note

Appendix: Sample configuration files

MibConfigurableObjectConfig.mibconfig

MibAuthorizationServerConfig.mibconfig

MibIdentityConfig.mibconfig

MibCryptoConfig.mibconfig

MibDatabaseConfig.mibconfig

MibTranslationConfig.mibconfig

MibLogConfig.mibconfig

Migrating to the New Login UI

Service Configuration for the New Login UI

UseNewLoginUi

FrontendAppRootUrl

Note

CorsAllowCredentials

Note

CorsOrigins

Note

Docker Compose Example for Auth UI

Variables

Switching Back to the Old UI

Warning

UI Customization

Recommendations for Production Environment

Recommendations for Development Environment

`UseNewLoginUi`

`FrontendAppRootUrl`

`CorsAllowCredentials`

`CorsOrigins`