---
title: "New and Improved Authentication Strategy"
description: "We recently added a new authentication strategy to the wallet which leverages our own waltid-ktor-authnz library"
stack: "Community Stack (open source) — version 0.21.0"
stack_version: "0.21.0"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/community-stack/wallet/authentication/new-auth
generated: 2026-07-20
---
# New and Improved Authentication Strategy

We recently added a new authentication strategy to the wallet which leverages our own [`waltid-ktor-authnz` library](https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/auth/waltid-ktor-authnz)

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:

```json
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:

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

OIDC Auth Flow:

```json
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

```json
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](https://www.keycloak.org/).

Instructions on how to setup and configure the keycloak instance for OIDC based authentication can be found [here](https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/auth/waltid-ktor-authnz/docs/oidc.md).

## Using the new authentication methods

### Email/Password Auth

```bash
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)

```bash
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:

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