OIDC: Error scenarios blogpost by dutow · Pull Request #1106 · percona/community

dutow · 2026-02-23T09:29:51Z

No description provided.

ImTheKai · 2026-02-26T07:33:04Z

+In this blog post we follow the same example, but instead of the success story, we explore how OAuth keeps our PostgreSQL servers secure.
+
+We won't focus on complex attack vectors, like the examples in the [second blog post](/blog/2025/11/17/oidc-in-postgresql-how-it-works-and-staying-secure/) in the OIDC series.
+Instead of social engineering, we'll look at practical errors, misconfigurations, honest mistakes: understanding the error messages and fixing problems.


Instead of social engineering, we'll look at practical errors, misconfigurations, and honest mistakes - understanding error messages and how to fix them.

ImTheKai · 2026-02-26T07:34:08Z

+
+### We succeeded with a FATAL error?
+
+However, before we start using all these additional items, let's go back to the end of the keycloak story, where in the end we succeeded with logging in.


Just wordsmithing idea and Keycloak uppercase instead:

let's go back to the end of the Keycloak story, where we succeeded in logging in.

ImTheKai · 2026-02-26T07:36:14Z

+FATAL: OAuth bearer authentication failed for user "testuser"
+```
+
+But if somebody is observant enough, this message is logged before we even went to the device authentication website of Keycloak, and entered the authentication code.


Mixing times/tenses here:

this message is logged before we even go to the device authentication website of Keycloak and enter the authentication code.

ImTheKai · 2026-02-26T07:37:17Z

+The main reason for this is that developers can trust the backend, controlled by administrators, while they can't trust the frontend, potentially used by malicious users.
+
+But are we validating user input in this case?
+Why does the user even have to specify the issuer, since the server already knows it, it's in there in the HBA configuration?


Would drop the not needed "in there in"

...already knows it, it's in the HBA configuration?

ImTheKai · 2026-02-26T07:38:15Z

+Since in the above situation the issuer is different, we never get to the point of signature validation.
+
+To do that, somebody has to tamper with the token.
+For example an attacker realizes that we require a specific scope, and since JWTs contain everything in clear text, decides to edit the `scp` claim and insert `pgscope` into it.


Missing comma:

For example, an attacker realizes that we require a specific scope

ImTheKai · 2026-02-26T07:39:32Z

+Another interesting scenario you might wonder about is token lifetime:
+in OAuth, tokens have a limited period in which they are valid.
+
+PostgreSQL currently has no facilities to enforce token lifetime when a connection is active -- once somebody is logged in, they stay logged in until they disconnect for some reason --, but validators are expected to validate that tokens are still valid at least during authentication.


This -- and especially --, seem awkward and AIish

"PostgreSQL currently has no facilities to enforce token lifetime when a connection is active - once somebody is logged in, they stay logged in until they disconnect for some reason - but validators are expected..."

ImTheKai · 2026-02-26T07:40:40Z

+However, it doesn't do that for other flows -- the Token Endpoint rejects unknown scopes with an error and doesn't provide an access token.
+
+On the client side, the error is the same as before -- no details about what's missing.
+Which is clearly fine in this situation, as this is clearly a configuration error, something the administrators have to figure out and fix.


clearly once in a single sentence should be enough :D

"Which is fine in this situation, as this is clearly a configuration error..."

ImTheKai · 2026-02-26T07:41:24Z

+kcmap           testuser2@example.com    testuser2
+```
+
+In this new setup, we transformed the configuration problem to a permission issue:


The preposition is incorrect, this should be "into a permission issue"

ImTheKai · 2026-02-26T07:42:23Z

+testuser2 will be able to log in, testuser won't.
+
+The error message on the client side is unchanged, it still doesn't say "permission denied" or "scope mismatch", or anything like that.
+At this point this can be debatable, but it is still mainly a task for administrators, and not the user:


Something is either debatable or not, the "At this point seems redudant to me"

"This is debatable, but it is still..."

Andriciuc · 2026-03-16T16:25:36Z

+* Instead of one scope, we have two: `pgscope`, `pgscope2`
+* Instead of one realm, we have two - containing exactly the same setup: `pgrealm` and `wrongrealm`
+
+We also have a role now, simply called `pgrole`.


A role named pgrole is also defined.

The pgtest2 client and pgscope2 scope both require the pgrole role. Only testuser2 is assigned this role; testuser does not have it.

Andriciuc · 2026-03-17T09:56:17Z

+| testuser    |   OK   | denied  |   OK    | denied   |
+| testuser2   |   OK   |   OK    |   OK    |   OK     |
+
+### We succeeded with a FATAL error?


Success despite a FATAL error

Andriciuc · 2026-03-17T09:56:28Z

+
+However, before we start using all these additional items, let's go back to the end of the Keycloak story, where we succeeded in logging in.
+Or did we?
+While `psql` logged us in, if anybody checked the server error log, we could see the following there:


If you check the server log, you may notice the following message:

Andriciuc · 2026-03-17T09:56:59Z

+As for PostgreSQL 18, unfortunately, we have to live with this.
+This also means that we can't rely on simply looking for OAuth authentication errors in the server log, because all OAuth authentication failures will result in exactly the same message, no matter if they are logged because of this harmless situation or because of a real authentication issue.
+
+A workaround is to rely on the validators instead: since the server is unaware of the exact error situation anyway -- it delegates validation to the validator -- these plugins will print out much more detailed *log messages*.


To get meaningful diagnostic information, rely on validator plugins instead. Since the server...

Andriciuc · 2026-03-17T10:02:42Z

+1. The client sends an empty connection request to the server.
+2. The server confirms that we are using OAuth, and sends back its issuer URL.
+3. The client checks whether the issuer it is planning to use -- or has already used, if it already has a valid token -- matches the one sent by the server.
+    * If not, it aborts the login attempt and prints an error.


If it does not match...

If it does match...

Andriciuc · 2026-03-17T10:14:14Z

+In our example, wrongrealm and pgrealm are exactly the same -- they have users with the same name, scopes with the same names, clients with the same names.
+If there's a misconfiguration, and the server and the client use different realms in a similar setup, everything would seem to work -- the user trying to log in would be able to log in, get a token, psql would send it to the server...
+and then on the server the validator would reject it -- assuming that it is a good validator, like pg_oidc_validator.
+No harm done -- other than disclosing a token to the server that shouldn't have been sent there --, but figuring out what's the problem could take a while.


I think we can rethink this as it's an important part of the blog, something like:

...and then on the server the validator would reject it -- assuming that it is a good validator, like pg_oidc_validator.
Disclosing a token to the wrong server might go unnoticed and take time to diagnose.

Andriciuc · 2026-03-17T12:54:30Z

+
+The client-side issuer check prevents this: psql compares the issuer URL from the server against the `oauth_issuer` it was configured with, and aborts if they don't match.
+
+So while this redundancy, the client having to specify the issuer URL might seem just an annoying extra step, it is there to protect us.


While requiring the client to specify the issuer may seem redundant, it's an important safeguard that prevents tokens from being disclosed to malicious servers.

Andriciuc · 2026-03-17T13:09:16Z

+
+Similarly to the previous situation, testing this without a custom client isn't possible, as psql always asks for a new token during the connection attempt, there is no way to send an earlier token with it.
+
+So as with the previous blog post, please accept that pg_oidc_validator will reject this scenario with the following message in the server log:


As in the previous example, this scenario is rejected by pg_oidc_validator, which logs the following message on the server:

Feels a little more direct

Andriciuc · 2026-03-17T13:10:08Z

+DETAIL:  Connection matched file "<datadir>/pg_hba.conf" line 119: "host    all             all             127.0.0.1/32            oauth issuer=https://keycloak:8443/realms/pgrealm,scope="pgscope email",map=kcmap"
+```
+
+Which should be self explanatory.


Probably shouldn't assume, better if this is left out of the blog.

Andriciuc · 2026-03-17T13:21:54Z

+Similarly to the previous scenarios, this is completely validator specific, we can only showcase our validator.
+
+This scenario also depends on the OAuth flow used and the identity provider.
+**Note:** Keycloak, for example, permits unknown scopes for the device flow -- it simply ignores them and returns the scopes it can.


Keycloak permits unknown scopes in the device flow by ignoring them and returning only the recognized scopes.

Andriciuc · 2026-03-17T13:22:52Z

+Which is fine in this situation, as this is clearly a configuration error, something the administrators have to figure out and fix.
+
+Now let's see the error slightly differently:
+the above example worked with the unmodified keycloak setup, described in the previous blog, but we have an improved test setup for this one.


an added space between the two paragraphs and starting with "The above example.." flows a bit better.

Andriciuc · 2026-03-17T13:24:29Z

+kcmap           testuser2@example.com    testuser2
+```
+
+In this new setup, we transformed the configuration problem into a permission issue:


... into a permission issue where testuser 2 can log in and testuser cannot.

Slightly easier to read

Andriciuc · 2026-03-17T13:30:48Z

+
+While this is not an all-inclusive list, as we can't possibly cover every error scenario in a setup involving several components, it covers the most common scenarios, and should address all possible security problems.
+
+In our next part, we'll focus on a practical, minimal development example:


In our next blog post...

Andriciuc

Added a few comments, everything else LGTM!

ImTheKai reviewed Feb 26, 2026

View reviewed changes

OIDC: Error scenarios blogpost

169a9d8

dutow force-pushed the oidc4 branch from 1595bbd to 169a9d8 Compare March 4, 2026 09:21

Andriciuc reviewed Mar 16, 2026

View reviewed changes

Andriciuc reviewed Mar 17, 2026

View reviewed changes

Andriciuc approved these changes Mar 17, 2026

View reviewed changes


		### We succeeded with a FATAL error?

		However, before we start using all these additional items, let's go back to the end of the keycloak story, where in the end we succeeded with logging in.


		The client-side issuer check prevents this: psql compares the issuer URL from the server against the `oauth_issuer` it was configured with, and aborts if they don't match.

		So while this redundancy, the client having to specify the issuer URL might seem just an annoying extra step, it is there to protect us.


		Similarly to the previous situation, testing this without a custom client isn't possible, as psql always asks for a new token during the connection attempt, there is no way to send an earlier token with it.

		So as with the previous blog post, please accept that pg_oidc_validator will reject this scenario with the following message in the server log:


		While this is not an all-inclusive list, as we can't possibly cover every error scenario in a setup involving several components, it covers the most common scenarios, and should address all possible security problems.

		In our next part, we'll focus on a practical, minimal development example:

Conversation

dutow commented Feb 23, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Success despite a FATAL error

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andriciuc left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants