Configuring an application client for MibAuthorizationServer

The MibAuthorizationServer application's main responsibiliy is to serve as a general purpose authentication tool for other apps. In order to do so, it implements the OAuth 2.0 / OpenID Connect protocols through the OpenIddict library (OpenIddict 5.x on .NET 8), which allows it to authenticate and authorize other Mib applications.

Engine note (MEDIAIBOX-11999): As of MIB 6.0 the OAuth/OIDC engine was migrated from IdentityServer4 (v3.1.4, EOL) to OpenIddict 5.8.0. The migration is parity-first: the same database tables, endpoints, grant types, RS512 signing keys and reference (opaque) access tokens are preserved, so the client configuration below (database entry + environment variables) is unchanged. See AuthorizationServerInstallation.md for the upgrade ToDo and the new AUTH_ENC_CREDENTIALS requirement.

The main grant types implemented by the OAuth authentication service of the MibAuthorizationServer application are Authorization Code, which has higher security and is used in applications such as the MibServer3, and Resource Owner Password Credentials, which is used on APIs such as the MibServerApi, the File Management Microservice and the Authorization Server itself. The client_credentials grant is also supported for service-to-service authentication. For both cases, the configuration of a client consists of two parts: creating an entry in the database and setting up environment variables.

Resource Owner Password

Resource Owner Password grants are used in two scenarios: to authenticate an external API Client (such as MibServerApi), or to authenticate the MibAuthorizationServer itself.

In order to register an API client with this grant type, it is necessary to add an entry to the API_CLIENTS database, present in the default migrations for the AuthorizationServer application. The most important columns are:

OAUTH_CLIENT_ID -> identifies the API client
OAUTH_CLIENT_SECRET -> serves as a confidential password to verify the client
OAUTH_CLIENT_TYPE -> defines the grant type to be used. For the Resource Owner Password grant type, it must be set to 3

After creating the entry in the database, all that is left is to insert the appropriate environment variables for the client application. In this step, there are two possible scenarios for configuration: for MibAuthorizationServer or for other API client applications (such as MibServerApi or MibFileManagementMicroService)

MibAuthorizationServer

The necessary environment variables are the client Id and client Secret, used to authenticate the AuthorizationServer for using the administration pages. They must be the same as the ones configured on the database:

"MIBAUTHORIZATIONSERVERCONFIG_DEFAULT_CLIENTID": "authclientid"
"MIBAUTHORIZATIONSERVERCONFIG_DEFAULT_CLIENTSECRET": "authclientsecret"

Other client APIs

For other APIs, it is necessary to provide the client Id (with the same value of the entry configured in the database), as well as a configuration indicating the base address of the MibAuthorizationServer instance that will be requested for the authentication. The variables are:

"MIBAUTHORIZATIONCLIENTCONFIG_DEFAULT_SERVERURL": "https://www.mibauthorizationserver.com"
"MIBAUTHORIZATIONCLIENTCONFIG_DEFAULT_CLIENTID": "apiClientId"

Authorization code grant

The MibServer3 application implements authentication through the authorization code grant type, which provides greater security by connecting the user directly with the MibAuthorizationServer, allowing for user authentication without exposing the user credentials to the MibServer3 application.

sequenceDiagram
    title Authorization Code Flow
    User->>MibServer3: Request authorization
    MibServer3-->>+MibAuthorizationServer: oauth/authorize <br/>Client Id, Client Secret, Redirect URI
    MibAuthorizationServer-->>User: Request consent for new client
    User-->>MibAuthorizationServer: Consent granted    
    MibAuthorizationServer-->>-MibServer3: Authorization Code    
    MibServer3->>+MibAuthorizationServer: oauth/token <br/>Authorization Code, Redirect URI
    MibAuthorizationServer-->>-MibServer3: Access token, Refresh token

Consent under OpenIddict: for first-party MIB clients consent is automatic / inline at the authorize endpoint (it is granted and persisted to AUTH_GRANTS without showing a consent screen), provided useNewLoginUI=true. The legacy IdentityServer4 MVC consent page (~/consent) no longer exists. The "Request/grant consent" step in the diagram above is therefore transparent to the user.

Configuring a MibServer3 instance through the authorization code is similar to the process for other APIs, consisting of creating an entry to the API_CLIENT table in the MibAuthorizationServer database and adding environment variables to the project's configuration. However, due to the additional security demands of the authorization code grant, there are more parameters needed.

The most important columns are:

OAUTH_CLIENT_ID
OAUTH_CLIENT_SECRET
OAUTH_CLIENT_TYPE -> for the Authorization Code grant, must be set to 1
REDIRECT_URI -> defines the address to which the MibAuthorizationServer will redirect the client after authentication. Must be set to the oauth/callback route of the MibServer3 application (for instance, https://www.mibserver3.com/oauth/callback)

The environment variables are also similar to those used for Resource Owner Password authentication:

"MIBAUTHORIZATIONCLIENTCONFIG_DEFAULT_SERVERURL": "http://www.mibauthorizationserver.com",
"MIBAUTHORIZATIONCLIENTCONFIG_DEFAULT_CLIENTID": "mibserver3clientid",
"MIBAUTHORIZATIONCLIENTCONFIG_DEFAULT_CLIENTSECRET": "mibserver3clientsecret",

Note

If the Authorization Server is deployed under a URL sub-path (e.g. https://host/MibAuth/), MIBAUTHORIZATIONCLIENTCONFIG_DEFAULT_SERVERURL must include that prefix so the client calls the prefixed /oauth/authorize and /oauth/token endpoints. The server, in turn, must have customUrlBase set to the same prefix — see Installation › Deploying under a URL sub-path.

Token lifetimes and refresh-token model

Changed in MEDIAIBOX-11999. Token lifetimes are configured in MibIdentityConfig.mibconfig (file MibIdentityConfig), not in MibAuthorizationServerConfig. The legacy MibAuthorizationServerConfig keys accessTokenMinutes, refreshTokenHours and authorizationCodeSeconds are no longer read — if present they are silently ignored.

Key (section `default`)	Default	Meaning
`AccessTokenLifetime`	`3600` (seconds)	Access token lifetime
`absoluteRefreshTokenLifetime`	`2592000` (30 days)	Refresh token lifetime when expiration is absolute
`slidingRefreshTokenLifetime`	`1296000` (15 days)	Refresh token lifetime when expiration is sliding
`authorizationCodeLifetime`	`300` (5 min)	Authorization code lifetime
`slidingRefreshTokenExpiration`	`false`	`false` = absolute expiration, `true` = sliding
`reuseRefreshToken`	`false`	`false` = one-time use (rotating), `true` = reuse
`refreshTokenReuseLeeway`	`30` (seconds)	Grace window during which a redeemed (rotated) refresh token is still accepted, so concurrent refresh requests from a single client are not classified as a replay attack. `0` restores the previous no-leeway behavior, where any concurrent refresh trips replay detection and OpenIddict revokes the whole authorization. Matches OpenIddict's own default of 30s.
`tokenCleanUpServiceEnabled`	`false`	Enables the background job that prunes expired grants from `AUTH_GRANTS`
`tokenCleanUpInterval`	—	Interval of the pruning job (when enabled)

These values default to parity with the previous IdentityServer4 behavior (absolute expiration, one-time-use refresh tokens). The environment-variable form uses the MIBIDENTITYCONFIG_DEFAULT_ prefix, e.g.:

"MIBIDENTITYCONFIG_DEFAULT_ACCESSTOKENLIFETIME": "3600"
"MIBIDENTITYCONFIG_DEFAULT_ABSOLUTEREFRESHTOKENLIFETIME": "2592000"
"MIBIDENTITYCONFIG_DEFAULT_SLIDINGREFRESHTOKENEXPIRATION": "false"
"MIBIDENTITYCONFIG_DEFAULT_REUSEREFRESHTOKEN": "false"
"MIBIDENTITYCONFIG_DEFAULT_REFRESHTOKENREUSELEEWAY": "30"

Restored in MEDIAIBOX-12242. refreshTokenReuseLeeway had been set to 0 during the IS4→OpenIddict cutover, which turned every concurrent refresh from a legitimate client (the CMS FrontEnd fires several parallel XHRs on boot) into a replay verdict that revoked the whole authorization. The default is back to OpenIddict's 30s and is now tunable per environment.

Known non-parity items (documented limitations, not blocking): IdentityServer4's absolute cap on sliding refresh tokens is not enforced natively by OpenIddict (a sliding token extends without an upper bound), and updateAccessTokenClaimsOnRefresh is not honored — the principal is reused on refresh rather than rebuilt.

Signing and token-encryption keys

Table	Purpose
`AUTH_SIGNING_CREDENTIALS`	RS512 signing key (token signature; published via JWKS). Existing table, reused.
`AUTH_VALIDATION_KEYS`	Validation keys. Existing table, reused.
`AUTH_ENC_CREDENTIALS`	New. AES-256 key used by OpenIddict to encrypt (JWE) refresh tokens and authorization codes. Auto-bootstrapped on first start; must persist across restarts.

OpenIddict 5.x encrypts refresh tokens and authorization codes as JWE even with access-token encryption disabled, so a stable, persisted encryption key is mandatory — an ephemeral key would invalidate all live refresh tokens/codes on every restart. See AuthorizationServerInstallation.md.

Table of Contents