SeguridadArquitecturaChile

I built a public sandbox for Chile's Open Finance System, and Keycloak alone did not get there

Chile has an open finance regulation and no public sandbox to test it against. I built a complete unofficial one, faithful to the Technical Annex: participant directory, bank, authorization server and requesting application, with mandatory PAR, an encrypted request object, mTLS and RAR reaching the token. Keycloak 26 covers much of it through configuration, but the consent model Chile picked does not exist in the product: it had to be written from scratch.

Efrain Garay 26 August 2026 26 August 2026

That covers a good part of the technical annex. The encrypted request object works too: the sandbox sends it as JWE(JWS) with PS256 inside and RSA-OAEP with A256GCM outside, and Keycloak decrypts it, verifies the signature and processes it.

The order there matters and is not interchangeable. You sign first and encrypt second, because the other way around the signature would cover ciphertext and prove nothing about the content.

Where discovery cannot describe the server

The first problem is neither a security flaw nor a violation. It is that the discovery document cannot describe what a particular client is going to get.

Both columns come from the same server. The left one from its .well-known/openid-configuration, the right one from sending it the request that document claims to allow.

The cause is structural, and worth stating before accusing anyone: those fields describe the whole server, while the requirement lives in the client policy. RFC 9126 §4.5 itself contemplates requiring PAR per client, and discovery has nowhere to express that. I tried setting the fields as realm attributes and the API answered 204 without changing anything.

So the server is not lying: the format gives it no way to tell a truth that depends on who is asking.

The practical problem is still real, because there are clients generated by reading that file. A library reading require_pushed_authorization_requests: false will try the direct path, get a 400, and whoever uses it will go looking for the bug in their own code.

The real gap: RAR goes in and does not come out

Keycloak accepts authorization_details inside the request object. It validates it, stores it in the session and does not emit it in the token.

The result is a token that authorizes without saying what for. The resource server receives a generic permission and the consent is lost exactly where it was supposed to matter. There is no stock mapper for this, and no experimental feature covering it.

Finding the cause took four failed attempts. I tried passing the data through the claims parameter, disabling the lightweight token, nesting the structure, sending it loose in the PAR. They all failed the same way: the mapper ran and found nothing.

The answer showed up by logging session notes from inside the mapper. Keycloak prefixes request-object claims when it stores them. What I spent two hours looking for as authorization_details had been there the whole time, under this name:

private static final String PREFIJO = "client_request_param_";
// The data was there. Looking for it under its bare name finds nothing,
// and the mapper walks past without complaining.
String crudo = ctx.getClientSession().getNote(PREFIJO + claim);

A second finding fell out of that, and it explains another lost afternoon: Keycloak drops request-object parameters it does not recognize. Sending a loose consent_id is pointless because it never reaches the other side. The consent identifier has to be pulled out of the RAR itself, which does survive, and which is where the regulation puts it anyway.

There is a formatting detail that also cost time. The value has to be emitted as an array of objects and not as a string:

// authorization_details is an array. Putting it in as a string produces a
// token where the receiver has to parse JSON inside the JSON again.
private Object comoJson(String crudo) {
  String t = crudo.trim();
  if (t.startsWith("[") || t.startsWith("{")) {
    return JsonSerialization.readValue(t, Object.class);
  }
  return crudo;
}

The authorization server cannot show the consent

This is where the default architecture breaks, and not because of a product limitation.

The regulation requires showing the end customer what is requested, over which accounts and for how long before they authorize. The authorization server holds none of those three. The institution providing the information does, because it created the consent and knows the accounts. Keycloak’s generic screen can list scopes, and a scope called accounts tells nobody anything.

The second factor has the same problem: the emailed code comes from the bank, with the bank’s branding, to the address the customer registered.

The way out was a custom authenticator that breaks off the flow, redirects to the bank with the consent identifier and a return URL, and resumes when the customer comes back:

String vuelta = ctx.getActionUrl(ctx.generateAccessCode()).toString();
ctx.challenge(Response.status(302).location(URI.create(destino)).build());

And on the way back, the part that makes this an authorization rather than a formality:

if (!"autorizado".equals(resultado)) {
  // Letting it through would be authorizing without consent.
  ctx.getEvent().error("consent_denied");
  ctx.failureChallenge(AuthenticationFlowError.ACCESS_DENIED, ...);
  return;
}

Placing that authenticator in the flow has its own trap. Making it required at the top level makes Keycloak ignore every alternative and fail with a message about needing a user. Putting it inside the forms subflow works, unless there is a cookie session, in which case it is skipped entirely. The only way to guarantee the screen always appears is to ask for prompt=login from the request object.

Six failures that produce no error

This is the pattern that cost me the most time and the reason this post exists. None of these problems produces a message pointing at its cause.

The last one showed up testing with a real person instead of an automated browser. The flow leaves the authorization server for the bank, the person reads the detail, requests a code, opens their email and comes back. That goes past a minute nearly every time. On screen it looks like a broken callback, and only the server log says expired_code.

There was a seventh, which was mine and not Keycloak’s: the bank’s “authorization complete” screen offered two ways forward at once, a link and a timer. The action URL is single use, so the second visit came back as an error after the good one and covered the correct screen. The authorization worked and the interface said it had failed. I fixed it by removing the screen and returning a 302 from the server.

mTLS behind a proxy deserves its own warning

Keycloak reads the client certificate from a header and its nginx provider accepts only URL-encoded PEM. Caddy 2.11 offers PEM with newlines, which an HTTP header will not take and which produces a 502, or base64 DER, which Keycloak does not understand.

There is a third option documented in several places, certificate_pem_urlencoded, which does not exist in Caddy. I confirmed it by searching the binary. When you use it, Caddy passes the literal unresolved and Keycloak reports that no client certificate is available, which looks like an mTLS fault and is not one.

The fix was a tiny bridge that re-encodes, taking care that + comes out as %2B: Java’s decoder turns it into a space and verification fails with an error that also never mentions the cause.

What it cost

The 639 lines of Java are the number that hurts most, because they are the ones configuration cannot avoid: they have to be maintained against an internal API Keycloak itself warns may change without notice, and recompiled against the exact server version because a jar from another one will not load.

But the number that surprises is the other one. The Grant Management API is 531 lines of a service that did not exist anywhere, and the PAR adapter another 214. That is not filling a gap in the product: it is implementing the consent model the regulation chose.

The error a question found

Someone asked me where the regulation says the bank must expose a URL to create the consent before the PAR. I went looking for the clause and there is none.

In the whole Chilean specification there is not a single POST /consents. The only consent endpoints are grant management ones:

And the order is the opposite of what I had built. Quoting the RAR specification:

The requesting party sends the Pushed Auth Request (/par) with one or more objects inside authorization_details. The Authorization Server verifies coherence between the API scope and the declared actions; if everything is valid, it returns the signed request_uri.

It then defines a grant response carrying grantId, status: AwaitingAuthorisation and creationDateTime. Which means: the PAR carrying the RAR is the creation of the consent. There is no separate call, and the identifier is minted by the authorization server, which belongs to the bank.

What I had built was the Open Banking Brasil model. It is the reflex of anyone who has seen open finance before, and in Chile it is wrong.

What fixing it cost

Redoing it moved three things I thought were settled.

The requesting app writes the RAR. The regulation explicitly forbids the bank from altering the content of the request, so asking the bank for the authorization_details was letting it do the drafting. Now it is written by whoever is asking, who is the one who knows what service they intend to provide.

And it names no accounts. Here I hit a contradiction inside the regulation itself. The RAR table marks identifier as mandatory, but the payment initiation specification says of the same field: “Optional. If not informed, the End User will select the account in the Financial Institution’s interface during authorization.” And the general rule lets the bank offer that selection. I followed the operational behaviour, because requiring the identifier would force the requesting app to name accounts it does not know yet, and the only way to learn them would be reading them before consent.

So the person picks their accounts at the bank, with nothing pre-ticked, which is what the regulation demands when it forbids pre-marked options. And the server prunes the grant to what was granted.

The token carries what was granted, not what was asked. The specification describes the response’s authorization_details as an echo of what was granted, verified and pruned by the authorization server. Emitting the original request would produce a token broader than the consent.

I tested it twice with different choices: ticking two accounts yields exactly those two, ticking a single different one yields only that one.

Keycloak’s third gap, and the largest

Grant Management does not exist in the product. Its discovery document publishes neither grant_management_endpoint nor grant_management_actions_supported; the only field carrying the word is grant_types_supported, which is something else.

So on top of the two providers came a service with the full API, an adapter in front of the PAR that validates the Chilean RAR and mints the grantId, and a Java client so the authenticator can move the grant to Authorised when the person signs.

What reading the regulation line by line turned up

I wrote a checker that reads the requirements and probes the running sandbox, storing what comes back. A point without evidence reports as unverified, never as met.

It found a failure that had been there from the start: the security profile requires PS256 and the realm published only RS256. Anyone verifying signatures the way the regulation describes would have found nothing to verify with. Keycloak signs in RS256 out of the box and you have to tell it in three places: the realm key, the default algorithm and the client attributes.

It also turned up a second contradiction. The security profile says purpose is “an informational field that shall not be used for any restriction”, while the CMF validation rules require its value to come from the published list. I resolved it by validating the value and not using it to decide access: what decides is the grant.

One note on the checker itself: the first version reported “does not comply” whenever the client certificate was missing. Not being able to check something is not the same as failing it, and confusing the two turns a checklist into noise.

When it works and when it does not

Keycloak works if you are building a participant and need something running this week. It enforces most of the profile through configuration, it is free, it self-hosts, and both gaps are named with their file in this post.

Keycloak is not enough on its own. With the providers in place the flow complies and the token carries its RAR and its grantId; without them, it does not. Anyone planning an implementation has to budget that code and its maintenance rather than assume it comes included.

And this is a sandbox for development, never for production. It exists so an implementation can be tested against a system that behaves the way the regulation demands on the wire. It does not replace ATENA, it does not operate, and the missing pieces are exactly the ones separating a demonstration from a participant: regulatory retention, propagation between dashboards, and the full consent lifecycle. That goes in the next implementation, which is another post.

And there is an asymmetry worth saying out loud: the gap sits on the consent side, which is exactly the part the regulation protects. What Keycloak gets right is cryptography and transport. What has to be hand-written is the part that explains to a person what they are authorizing.

What comes next

The next version of the sandbox runs on WSO2 Identity Server, and that is the promise I am closing with. The reason is exactly what this post documents: WSO2 ships Rich Authorization Requests as a product feature, with detail types registered through an API rather than deduced from a prefixed session note, and it documents creating FAPI 2.0 applications from its console.

If that means both custom providers become unnecessary, the result of the comparison is the next post. If they do not, that is a post too.

Sources

• CMF · The rule regulating the Open Finance System, Chile’s Financial Market Commission. General Rule 514 and its scope.
• CMF · Technical Annex of the Open Finance System, which defines the security profile this sandbox implements.
• Open Finance Chile developer portal, with the API specifications and the Postman collection.
• RFC 9126 · OAuth 2.0 Pushed Authorization Requests. The PAR the annex makes mandatory.
• RFC 9396 · OAuth 2.0 Rich Authorization Requests. §10 is the one asking for supported types to be published.
• RFC 8705 · Mutual-TLS Client Authentication and Certificate-Bound Access Tokens. The cnf.x5t#S256 that makes a stolen token useless.
• RFC 7591 · OAuth 2.0 Dynamic Client Registration, the basis for registering against the Directory’s software statement.
• FAPI 2.0 Security Profile, OpenID Foundation.
• WSO2 Identity Server · Rich Authorization Requests, the native support driving the next version.