OIDC Unique Sub Auth

With this authentication strategy you can simply provide a valid JWT with a unique subject claim and the wallet-api will create or login a user to the associated wallet account. This way you can use your own authentication flows and just provide the result (valid JWT) to the walt.id system. To verify the JWT provided is coming from your auth server, you need to configure the relevant OIDC endpoints via a config.

Config

In waltid-wallet-api/config/oidc.conf update the value oidcRealm and oidcJwks with your auth server values. Below you find an example using Keycloak:

oidc.conf
enableOidcLogin = true
providerName = keycloak
# Enter the realm URL
oidcRealm = "https://keycloak.walt-test.cloud/realms/waltid-keycloak-ktor"

# JWKS (to verify access keys the user claims to received through OIDC server)
oidcJwks = "${oidcRealm}/protocol/openid-connect/certs"
authorizeUrl = "${oidcRealm}/protocol/openid-connect/auth"
accessTokenUrl = "${oidcRealm}/protocol/openid-connect/token"
logoutUrl = "${oidcRealm}/protocol/openid-connect/logout"
clientId = "waltid_backend_localhost"
clientSecret = "Xp8fJG5RTtj6lYUlqqIG57iovXMvfD5j"

# JWKS is cached: jwksCache = {
cacheSize = 10
cacheExpirationHours = 24
rateLimit: {
bucketSize: 10
refillRateMinutes: 1
}
}

Create / Login

When using the OIDC unique subject authentication strategy, the login endpoint creates a new account if the subject claim in the JWT is not already associated with an account. Otherwise, it simply logs in the user.

CURL

API Reference

curl -X 'POST' \
 'http://0.0.0.0:7001/wallet-api/auth/login' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "oidc-unique-subject",
  "token": "<JWT>"
}'

Body Parameters

{
  "type": "{type}"
  "token": "string"
}
  • type: string - type of the authentication strategy, e.g. oidc-unique-subject
  • token: string - the JWT from your OIDC authentication system holding a unique subject claim.

Example Response
Now a session is automatically created for cookie-based authentication. For Bearer Token Authentication, the token returned must be provided in the header for each request that needs authentication. Refer to the overview section for more details.

{
  "token": "KL-a_dk1qO8moCX4gxaGfb7_TS8RK-JWVKZk9BBP0-s",
  "id": "018045e5-942c-4362-b535-658c4dd581ef",
  "username": "c9234234234234-234234234-203942fasdfs"
}

Logout

CURL

API Reference

Deletes the session/invalidates the token.

curl -X 'POST' \
  'http://0.0.0.0:7001/wallet-api/auth/logout' \
  -H 'accept: */*' \
  -d ''
OIDC ProvidersJWT/OIDC