RouteKit Classic ASP - MVC Starter

A clean starting point for building Classic ASP applications with the RouteKit MVC framework.

Quick Setup

1. Copy this folder to your IIS server
2. Point your IIS site root to the public/ folder
3. Update public/web.config:
   • Set ConnectionString to your database path
   • Set ErrorLogPath if you want file logging
4. Ensure the IIS URL Rewrite module is installed
5. Browse to http://localhost/ — you should see the welcome page

Keycloak Authentication

The core Keycloak helper is loaded automatically from core/lib.Keycloak.asp. It uses Keycloak's OpenID Connect authorization-code flow to redirect users to Keycloak, exchange the callback code for tokens, and fetch user profile data from the userinfo endpoint.

Configure public/web.config

Update these appSettings before enabling login:

<add key="KeycloakBaseUrl" value="https://keycloak.example.com" />
<add key="KeycloakRealm" value="your-realm" />
<add key="KeycloakClientId" value="your-client-id" />
<add key="KeycloakClientSecret" value="" />
<add key="KeycloakRedirectUri" value="http://localhost/auth/callback" />
<add key="KeycloakLogoutRedirectUri" value="http://localhost/" />
<add key="KeycloakScope" value="openid profile email" />
<add key="KeycloakPendingLoginCookieMinutes" value="15" />
<add key="KeycloakAllowedClockSkewSeconds" value="300" />
<add key="KeycloakHttpResolveTimeoutMs" value="5000" />
<add key="KeycloakHttpConnectTimeoutMs" value="5000" />
<add key="KeycloakHttpSendTimeoutMs" value="15000" />
<add key="KeycloakHttpReceiveTimeoutMs" value="15000" />
<add key="KeycloakEnableLogging" value="false" />
<add key="KeycloakLogPath" value="C:\YourApp\logs\keycloak.log" />

• KeycloakBaseUrl: Base URL of the Keycloak server, without /realms/....
• KeycloakRealm: Realm that owns the application client.
• KeycloakClientId: Client ID configured in Keycloak.
• KeycloakClientSecret: Secret for confidential clients. Leave blank for public clients.
• KeycloakRedirectUri: Absolute callback URL in this ASP app.
• KeycloakLogoutRedirectUri: Absolute URL to return to after Keycloak logout.
• KeycloakScope: OIDC scopes to request. The default is openid profile email.
• KeycloakPendingLoginCookieMinutes: How long the temporary login state and nonce cookie should survive during the redirect round-trip.
• KeycloakAllowedClockSkewSeconds: Grace period for exp, nbf, and iat validation when checking the ID token claims.
• KeycloakHttp*TimeoutMs: Outbound HTTP timeouts for the token and userinfo requests.
• KeycloakEnableLogging / KeycloakLogPath: Optional diagnostic logging for Keycloak request and token-validation failures.

Keep KeycloakClientSecret out of source control and inject it per environment. Use HTTPS callback and logout URLs outside local development.

Configure the Keycloak client

In Keycloak, create or update a client for this app:

• Client protocol: OpenID Connect.
• Access type/client authentication: use a confidential client if you set KeycloakClientSecret; otherwise use a public client.
• Valid redirect URIs: include the exact KeycloakRedirectUri, for example http://localhost/auth/callback.
• Valid post logout redirect URIs: include the exact KeycloakLogoutRedirectUri.
• Web origins: include the app origin, for example http://localhost, or configure according to your environment policy.

Use the helper in controllers

Add routes in public/Default.asp for login, callback, and logout actions. In those controller actions, call the helper functions:

' Login action
Call KeycloakLogin()

' Callback action
If KeycloakHandleCallback() Then
    Response.Redirect KeycloakConsumePostLoginRedirectPath("/")
Else
    Response.Write H(KeycloakAuth().ErrorMessage)
End If

' Logout action
Call KeycloakLogout("")

After login, use the current user and token helpers anywhere after core autoload:

If KeycloakIsLoggedIn() Then
    Dim user
    Set user = KeycloakCurrentUser()

    If Not user Is Nothing Then
        Response.Write H(user.Item("preferred_username"))
    End If
End If

Dim accessToken
accessToken = KeycloakAccessToken()

To protect a controller action and return the user to the original page after sign-in:

If Not KeycloakRequireLogin("") Then Exit Sub

If Not KeycloakHasRealmRole("admin") Then
    Response.Status = "403 Forbidden"
    Response.Write "Forbidden"
    Exit Sub
End If

Available helper functions:

• KeycloakLogin(): Redirects to Keycloak and stores temporary login state for the redirect round-trip.
• KeycloakHandleCallback(): Validates callback state and nonce, exchanges the code, stores tokens, and fetches user info.
• KeycloakIsLoggedIn(): Returns True when an access token is in Session.
• KeycloakCurrentUser(): Returns the cached userinfo dictionary, or ID token claims when userinfo is unavailable.
• KeycloakUserInfo(): Calls Keycloak's userinfo endpoint with the current access token.
• KeycloakAccessToken(), KeycloakRefreshToken(), KeycloakIdToken(): Return stored tokens.
• KeycloakTokenClaims(token): Decodes JWT payload claims into a dictionary.
• KeycloakRequireLogin(returnToPath): Redirects unauthenticated users to login and preserves a safe relative return path.
• KeycloakConsumePostLoginRedirectPath(fallbackPath): Returns the stored post-login destination, then clears it from Session.
• KeycloakHasRealmRole(roleName): Returns True when the stored ID token includes the named realm role.
• KeycloakHasClientRole(clientId, roleName): Returns True when the stored ID token includes the named client role.
• KeycloakLogoutUrl(postLogoutRedirectUri): Builds a Keycloak logout URL.
• KeycloakLogout(postLogoutRedirectUri): Clears Session values and redirects to Keycloak logout.

Session values

The helper stores tokens and user info in Session using the Keycloak_ prefix. Use HTTPS in production so tokens are protected in transit, and configure IIS session settings according to your application's security requirements.

Project Structure

MVC-Starter/
  public/              # IIS ROOT - point your IIS site here
    Default.asp        # Front controller (entry point)
    web.config         # IIS config, routes, connection strings
  core/                # Framework core (do not modify)
    autoload_core.asp  # Loads all core libraries
    router.wsc         # Route matching engine
    mvc.asp            # MVC dispatcher
    lib.*.asp          # Core libraries
  app/
    controllers/       # Your controllers go here
    views/             # Your views go here
      shared/          # Shared layout (header, footer)
    models/            # POBOs go here
    repositories/      # Repository classes go here
  db/
    migrations/        # Database migrations
    webdata.accdb      # Access database
  scripts/             # Code generators
    generateController.vbs
    generateMigration.vbs
    GenerateRepo.vbs
    runMigrations.vbs

Adding a New Feature

1. Generate a migration

cscript //nologo scripts\generateMigration.vbs create_my_table

2. Generate POBO and Repository

cscript //nologo scripts\GenerateRepo.vbs /table:my_table /pk:id

Move generated files to app/models/ and app/repositories/.

3. Generate a controller

cscript //nologo scripts\generateController.vbs MyController "Index;Show(id);Create;Store"

Move generated file to app/controllers/.

4. Wire it up

• Register in core/lib.ControllerRegistry.asp
• Include in app/controllers/autoload_controllers.asp
• Add routes in public/Default.asp
• Create views in app/views/MyController/

Included Controllers

• HomeController - Welcome page at /
• ErrorController - 404 handler at /404

Requirements

• Windows Server with IIS
• Classic ASP enabled
• IIS URL Rewrite module
• Microsoft Access Database Engine (for .accdb support)

Testing

This repo now includes a dev-only aspunit harness under tests/. It is intentionally separate from the production app rooted at public/.

• Configure a separate IIS application rooted at tests/
• Ensure Classic ASP parent paths are enabled for that IIS app
• If you change tests/web.config, refresh the nested test-folder copies with cscript //nologo tests\sync-webconfigs.vbs
• Open run-all.asp inside that IIS app to execute the test suite
• See TESTING.md for setup, manifest registration, and extension guidance