#New and Improved Authentication Strategy

We recently added a new authentication strategy to the wallet which leverages our own waltid-ktor-authnz library

We recommend using this new authentication strategy if possible for all future developlemts. It offers a more production ready solution of our open source wallet backend including authentication methods for:

Email/Password Auth
OIDC Auth

This new version specifically supports more options for token expiration and improved logout functionality.

#Enabling the new authentication strategy

In the config folder, edit the _features.conf file to enable the new authentication strategy and disable the legacy authentication strategy as shown below:

enabledFeatures = [
    ktor-authnz
]

disabledFeatures = [
    auth
]

We then update the new ktor-authnz.conf file in the config folder to configure the authentication strategy. Some interesting options to configure are:

#Auth flows

Username And Password Auth Flow:

authFlow = {
    method: email
    expiration: "7d"
    ok: true # Auth flow ends successfully with this step
}

OIDC Auth Flow:

authFlow = {
    method: oidc,
    config: {
        openIdConfigurationUrl: "http://localhost:8080/realms/master/.well-known/openid-configuration",
        clientId: "waltid_ktor_authnz",
        clientSecret: "fzYFC6oAgbjozv8NoaXuOIfPxmT4XoVM",
        callbackUri: "http://wallet.localhost:7001/wallet-api/auth/account/oidc/callback",
        pkceEnabled: true,
        redirectAfterLogin: "http://wallet.localhost:7001/wallet-api/auth/oidc-callback-frontend"
    },
    success: true
}

Note: the expiry time for the OIDC token is based on the configuration of the OIDC provider itself.

#Token Types

tokenType = STORE_IN_MEMORY

Supported:

STORE_IN_MEMORY: In memory token store (single-instance, no configuration necessary)
STORE_VALKEY: Store in Redis/Valkey/Redict/KeyDB (multi-instance, distributed logout supported) - configure Redis/Valkey/KeyDB instance below
JWT: Tokens as stateless JWT (multi-instance, no logout support as it is stateless!) - configure keys below

#Setting up a keycloak instance for OIDC based authentication

While we support using any OIDC provider, you may decide to run your own. In this case, we recommend using the open source solution Keycloak.

Instructions on how to setup and configure the keycloak instance for OIDC based authentication can be found here.

#Using the new authentication methods

#Email/Password Auth

curl -X POST http://localhost:7001/wallet-api/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com", "password": "password"}'

#OIDC Auth

After completing the authentication configuration above, you should see a new set of endpoints available for the wallet API (auth/account/oidc)

curl -X GET http://localhost:7001/wallet-api/auth/account/oidc/auth

Will return a JSON response which contains a next_step object which your wallet client should use to redirect the user to authenticate with the OIDC provider. The user will be automatically redirected based on the configuration you have set up in the ktor-authnz.conf file.

If the user does not have an account yet, it will be automatically created.

#Logout

This implementation supports logout through the OIDC provider (which will invalidate the session) and through the Wallet API directly using the following endpoint:

curl -X GET http://localhost:7001/wallet-api/auth/account/oidc/logout/frontchannel

Last updated on November 17, 2025

X.509 Certificate Overview