Two SSO Integration Methods: Agent (SDK) Inside the App vs. Gateway in Front of the App

Status: Draft (2026-10-26), reflects actual measurements. There are three sets of measurements. 1. We read the publicly readable metadata from Keycloak in the TT Lab cluster (/.well-known/openid-configuration, JWKS). Host and realm names and version numbers have been redacted. 2. We spun up a new Keycloak for practice (dev mode, a practice environment separate from production) on a laptop, generated a practice realm, client, and user with random values, and ran Authorization Code + PKCE using only Python standard libraries. We did not log in with a real user account. 3. We sent a JWT created with a practice key to a local gateway (agentgateway) for validation. The private part of the practice key was not included in the article. Specifications were verified by opening the original documents on the same day. Writing rule: Measurement data is the baseline; unmeasured items are marked as [Unmeasured], unverified items as [Not Verified], and guesses as [Estimated].

Table of Contents

• 1. Passes in One Place, Verification Where?
• 2. OAuth 2.0, OIDC, SAML: What Problems Do They Solve?
• 3. Authorization Code + PKCE: Keeping Tokens Out of the Browser
  • Three Random Values: state, nonce, and PKCE
  • Measurement: A Round with Local Keycloak
• 4. Three Tokens and JWT Signature Verification
  • JWT Has Three Pieces
  • A Valid Signature Is Not the End
  • Public Metadata of Clustered IdP
• 5. Agent (SDK) Method: What the Library Inside the App Does
  • Available Libraries and the Retirement of the Keycloak Adapter
• 6. Gateway Method: Verification Handled in Front of the App
  • Measurement: Which Tokens Does the Gateway Filter Out?
  • Pros and Cons of Both Methods
• 7. Logout and Session Synchronization
  • Measurement: Logged Out, But the Access Token Lives for 5 More Minutes
• 8. Common Pitfalls
• 9. Which Side to Choose
• 10. Conclusion
• References

1. Passes in One Place, Verification Where?

Think of a company building. Passes are issued at a single security office. This is the IdP(Identity Provider, e.g., Keycloak). There are two ways to verify a pass.

• Install a reader on the door of every office. The office (application) reads the pass itself and directly knows who entered and what privileges they have. This is the agent (SDK) method. A library inside the app process handles login redirection, callbacks, sessions, token refreshes, and logouts.
• Station a guard at the building entrance. The entrance (gateway) checks the pass and lets people through with a note attached saying "Who this person is." The office only reads the note. This is the gateway (proxy) method. Tools like oauth2-proxy, Envoy's JWT filter, and agentgateway handle this work in front of the app.

Both methods use the same protocol (OIDC) . The only difference is which process executes that protocol. Therefore, we will first look at the protocol (Sections 2–4), compare doing it inside the app (Section 5) versus in front of the app (Section 6), and then move on to logout (Section 7) and pitfalls (Section 8).

2. OAuth 2.0, OIDC, SAML: What Problems Do They Solve?

It is important to note that OAuth 2.0 alone cannot handle "login." This is because an access token is meant for APIs, not a document proving to the app "who logged in." OIDC fills that gap with the ID token. OIDC Core §2 requires the ID token to include iss·sub·aud·exp·iat .

The shape of the SAML SP-initiated flow is similar. The SP (app) compresses AuthnRequest and sends it via redirect, the IdP logs the user in, and then passes a signed Response via HTML form POST to the app's ACS address (OASIS SAML 2.0 Technical Overview §5.1.2, §4.6). This article focuses on OIDC, which is mainly used in new integrations. We could not directly quote the normative documents of SAML (core and bindings PDFs) in the main text, so we verified them via the overview document.

3. Authorization Code + PKCE: Keeping Tokens Out of the Browser

The core of the flow is that only a short-lived code passes through the browser, while tokens are directly exchanged between the app and IdP via a backchannel. This is because the browser address bar, history, referrers, and browser extensions are all leak points. The old implicit flow gave tokens directly to the browser in the address #fragment , and OAuth Security BCP (RFC 9700, 2025-01) §2.1.2 now states that implicit should not be used. The same document also prohibits the password grant where the app receives the password and passes it to the IdP (§2.4).

Three Random Values: state, nonce, and PKCE

A single login request is accompanied by three random values, each serving a different purpose.

The calculation for PKCE (RFC 7636) is a single line. The app creates a 43–128 character random value code_verifier (§4.1), and sends only its hash code_challenge = BASE64URL(SHA256(code_verifier)) in the login request (§4.2, S256). When exchanging the code for tokens, the original verifier must be provided, so anyone who merely stole the code can do nothing.

import base64, hashlib, secrets
b64u = lambda b: base64.urlsafe_b64encode(b).rstrip(b"=").decode()
verifier = b64u(secrets.token_bytes(32))                       # 43자
challenge = b64u(hashlib.sha256(verifier.encode()).digest())
print(b64u(hashlib.sha256(b"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk").digest()))

The last line is the example verifier from Appendix B of RFC 7636. Running it locally resulted in E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM , which matched the appendix's expected value (2026-10-26). RFC 9700 §2.1.1 states that public clients (SPAs and mobile apps that cannot keep secrets) must use PKCE, and recommends it even for confidential server apps.

Measurement: A Round with Local Keycloak

We created a confidential client in the practice Keycloak, enforced PKCE with S256, and registered exactly one redirect URI. Then, mimicking the browser role with Python urllib , we faithfully stepped through steps ③–⑨ of the diagram above.

Having iss attached to the callback is thanks to the IdP having authorization_response_iss_parameter_supported enabled. This prevents mix-up attacks where an app using multiple IdPs gets confused about "which IdP sent this code."

One thing was stronger than expected: When trying to reuse the same code, even the session for the token already obtained with that code was terminated. Immediately after the code reuse attempt, introspecting the access token for that session returned active: false, and refreshing with the refresh token returned 400 "Session doesn't have required client." Since the code being used twice is a signal that someone may have intercepted the code, this behavior ensures that even previously issued tokens are no longer trusted. This is precisely the handling recommended by RFC 6749 §4.1.2. However, that access token was still valid for entities performing only signature verification(similar to the issue in Section 7).

4. Three Tokens and JWT Signature Verification

Access and ID tokens together consume over a third of a single cookie's capacity (typically a 4KB limit). This is why gateways that place tokens into cookies must split them across multiple cookies or use a server-side session store.

JWT Has Three Pieces

JWT (RFC 7519) is a compact format of JWS (RFC 7515) formatted as BASE64URL(헤더).BASE64URL(페이로드).BASE64URL(서명) . Base64url is not encryption. Anyone can decode and read it, so secrets should never be placed in a token. The header of the measured token was {"alg":"RS256","typ":"JWT","kid":"…"} , and kid is the identifier used to select which key to verify with from the IdP's public key list (JWKS, RFC 7517).

RS256 verification ultimately boils down to a single exponentiation. Raising signature s to the public key (n, e) via s^e mod n should yield the PKCS#1 v1.5 format00 01 FF … FF 00 + DigestInfo + SHA-256(헤더.페이로드). We wrote it out directly using standard libraries for understanding (please use verified libraries in production code).

def rs256_ok(token, jwk):
    h64, p64, s64 = token.split(".")
    n = int.from_bytes(ub64(jwk["n"]), "big"); e = int.from_bytes(ub64(jwk["e"]), "big")
    k = (n.bit_length() + 7) // 8
    em = pow(int.from_bytes(ub64(s64), "big"), e, n).to_bytes(k, "big")
    di = bytes.fromhex("3031300d060960864801650304020105000420") + hashlib.sha256(f"{h64}.{p64}".encode()).digest()
    return em == b"\x00\x01" + b"\xff" * (k - 3 - len(di)) + b"\x00" + di

Measurement: The access, ID, and logout tokens issued by the practice IdP all passed this function using the 2048-bit RSA key from JWKS, and modifying even a single bit in the payload caused a failure.

A valid signature is not the end of the line

A signature only proves "created by the IdP." Whether "the token came to me, right now, with this login" must be verified separately through claims. OIDC Core §3.1.3.7 lists 13 steps for ID token validation, and the core is steps 4–7 in the diagram. iss text must match, aud must contain my client_id, exp must not have passed, and nonce must be the value I sent. JWT Best Current Practice (RFC 8725) states that callers should determine the list of algorithms that the library will accept (§3.1), and MUST aud validate alg: none (§3.9).

Two pitfalls were observed in the measured tokens.

1. The aud of the Keycloak access token was account by default. This is not the name of my API. To properly validate aud on the API side, you must attach an audience mapper to the IdP so that the API name is included. If you skip validating aud on the API to save time, tokens issued by the same IdP to other apps could be used to call your API.
2. The JWT access token standard (RFC 9068) specifies that the header typ should be at+jwt , but the measured token was JWT .(Claim typ was Bearer). If a resource server strictly checks typ per RFC 9068 §4, it will reject this token. You need to decide which side to align with before integration.

exp includes a clock skew tolerance (leeway). RFC 7519 §4.1.4 allows "a small leeway, typically no more than a few minutes." When the measured ID token was checked with a clock set to 1 second after expiration, it failed exp without leeway, but passed with a 60-second leeway. The default leeway for Spring Security resource servers is 60 seconds (official documentation), and the gateway in Section 6 also measured at about 60 seconds.

Cluster IdP Public Metadata

The Discovery document and JWKS were read from Keycloak in the TT Lab cluster (2026-10-26). Both are public information open without authentication, and the values below are the lists Keycloak provides by default for each realm.

The key takeaway here is that the Discovery document is a list of what the server "can do," not what is "allowed" for clients. Even if implicit, password, and plain are in this list, they can and should be disabled per client. The default stance is to enable only the standard flow (code) for each client while disabling implicit and direct access (password) flows.

5. Agent (SDK) Approach: What libraries inside the app do

The OIDC library inside the app handles all of Sections 3–4 above. Listed out, it is longer than you might think.

1. Reads the Discovery document at startup, fetches the JWKS, and caches it. Re-fetches (with rate limits) if an unknown kid arrives.
2. If a request comes to a protected route without a session, it generates state, nonce, and verifier, stores them in server-side session, and redirects to the IdP.
3. Verifies the state in the callback, obtains tokens using the code and verifier, and validates the ID token.
4. Issues an app session cookie (HttpOnly, Secure, SameSite). Tokens are kept on the server.
5. Refreshes the access token using the refresh token before it expires. Forces a re-login upon failure.
6. Logout: Clears the app session and redirects to the IdP's end_session_endpoint (RP-Initiated Logout). Also opens an endpoint to receive backchannel logout requests sent by the IdP (Section 7).
7. If providing an API (Resource Server), checks the signature, iss, aud, and exp of incoming Bearer tokens.

A local implementation simulating this process in Python was about 150 lines of code, and even that omitted session storage, key rotation, and concurrency. This is why you use a verified library instead of writing it yourself.

Available libraries and the retirement of Keycloak adapters

In the past, Keycloak provided language-specific adaptersdirectly. Most of these have now disappeared. Following the official blog, the timeline is as follows:

The meaning of this trend is clear: OIDC has become standardized to the point where the IdP company no longer needs to maintain SDKs for every language. For Java, Spring Security is the representative choice.

# 로그인(oauth2Login) — 앱이 OIDC 클라이언트가 된다
spring.security.oauth2.client.provider.idp.issuer-uri: https://<IdP>/realms/<렐름>
spring.security.oauth2.client.registration.idp: { client-id: <앱>, client-secret: <비밀>, scope: [openid, profile] }
# 토큰 검사(oauth2ResourceServer) — API 가 Bearer 를 검증한다
spring.security.oauth2.resourceserver.jwt.issuer-uri: https://<IdP>/realms/<렐름>

issuer-uri It automatically fetches the JWKS address from the Discovery document using spring-boot-starter-security-oauth2-client·…-resource-server (on the first request), and the default clock leeway is 60 seconds (Spring Security documentation). In Spring Boot 4.x, the starter name changes to memoryand the old name is slated for removal. Authorized clients (tokens) of logged-in users are stored in OAuth2AuthorizedClientService by default. Only anonymous requests are stored in the session. If you scale out your app to multiple instances, this storage must be changed to a shared store.

Products like Argo CD, Grafana, Harbor, and Gitea have OIDC clients built-in , so you only need to enter the IdP address and client secret in the settings. This is also the agent approach; the only difference is whether you included the library or the product came with it.

6. Gateway Approach: Handling it at the entry point in front of apps

If you cannot modify the app (e.g., a dashboard built by someone else) or if there are multiple services in different languages, it is better to handle it once at the entry point. Gateways generally serve two functions:

• Proxy that also handles login: oauth2-proxy is a prime example. It sends the browser to the IdP, receives the callback, and holds the result as a cookie session(stored in cookies by default, configurable to Redis). If you use auth_request merely to ask "can this request be let in?" like nginx's /oauth2/auth , it only returns 200 or 401. Passed requests are forwarded with headers like X-Auth-Request-User·-Email·-Groups or Authorization: Bearer <토큰> attached (official documentation).
• Proxy that only inspects tokens: Inspects requests from clients (other services, CLIs, agents) that already possess a Bearer token, such as Envoy's jwt_authn filter or agentgateway's jwtAuth . Envoy caches remote JWKS for 10 minutes by default (official documentation).

Configurations combining both approaches are also common. A login proxy authenticates via PKCE, filters incoming users using the IdP's group claims, and attaches the token as a Authorization header, after which the subsequent service mesh re-validatesthe same JWT. In this setup, there is one rule: set the proxy's cookie refresh interval shorter than the IdP's access token lifespan, and keep the cookie expiration within the maximum length of the IdP's SSO session . This ensures the proxy obtains a new token before backend JWT validation encounters an expired one, and prevents users whose sessions have ended at the IdP from continuing to enter using only a cookie. In oauth2-proxy's official configuration table, cookie refresh (cookie_refresh) defaults to empty and is disabled if 0, while cookie expiration (cookie_expire) defaults to 168 hours (7 days). If you pass tokens downstream, you must configure both manually to match your IdP settings.

Measurement: Which tokens does the gateway filter out?

A JWT was created using a practice RSA key, and agentgateway with jwtAuth(strict, specifying iss and aud, JWKS file) enabled was run locally to send requests one by one (2026-10-26).

The last line is interesting. Changing the expiration to 10, 30, 55, 58, 62, 65, 90, and 120 seconds in the past showed that up to 58 seconds passed, and rejection started at 62 seconds. Similarly, nbf passed up to 55 seconds in the future, and rejection started at 65 seconds in the future. This means a clock skew tolerance of about 60 seconds is built in by default (not found in documentation, measured). This is why you should not design systems trusting expiration down to the exact second.

Costs were also measured. Calling the same backend directly, through an unauthenticated gateway, and through a JWT-validating gateway were alternated 400 times each (after 50 warm-up requests).

Compared to the overhead of passing through an extra gateway layer (about 1.9ms, including laptop container network round-trips), RS256 validation itself was about 0.08ms . Validation cost is no reason to hesitate in using a gateway.

Pros and Cons of the Two Approaches

In reality, these approaches are mixed. For example, browser logins are handled by a gateway (or BFF), while granular API permissions are handled by a resource server library inside the app.

7. Logout and Session Synchronization

The reason SSO logout is difficult is because sessions are threefold. These include the IdP's SSO session (IdP cookie), the app's session (app cookie), and the already issued tokens held individually. Clearing just one leaves the others intact.

Measurement: Logged out, but the access token lives for 5 more minutes

We registered a back-channel logout URL in the practice IdP's client (a small HTTP server running on a laptop), logged in anew, and requested a logout using the refresh token.

The last line is crucial. Because JWT access tokens are self-contained documents, APIs and gateways that only check signatures are unaware that the IdP has cleared the session. Even after logout, APIs can still be called for the duration of the token's lifetime (5 minutes here). Mitigation involves one of three options: shorten the access token lifetime, use introspection to query the IdP for important APIs (incurring a round-trip cost per request), or receive back-channel notifications and add that sid to a blocklist.

Refresh tokens also present a similar dilemma. In the practice realm's default setting (rotation disabled), reusing an already-used refresh token still returned 200 . When realm settings revokeRefreshToken was enabled (rotation), the old refresh token was rejected with 400 'Maximum allowed refresh token reuse exceeded', and immediately afterward, even the new refresh token was blocked with 'Session doesn't have required client'. This behavior treats reuse as a signal of theft and terminates the entire session. RFC 9700 §2.2.2 requires public clients' refresh tokens to be rotated or bound to the sender.

8. Common Pitfalls

① redirect_uri Mismatch. The IdP compares it strictly as a string against the registered URL (RFC 9700 §2.1, with the exception of native app localhost ports). In our measurements, a single trailing / triggered a 400 error page. The same error occurs if the app perceives its own address as http:// behind a proxy (when TLS is terminated upstream), or if port and path prefixes differ. Wildcard redirect URIs should be avoided because they provide attackers a way to intercept the authorization code.

② iss Mismatch. The token's iss and the app configuration's issuer must match down to the http/https, hostname, and trailing / . This frequently breaks in configurations where the IdP is called via an internal address while the browser uses a public address. Since Keycloak can construct iss using the requested hostname, it is safer to configure a fixed public hostname.

③ Clock Skew. If the clocks of the IdP, gateway, and app server are out of sync, a freshly received token may be considered 'not yet valid' (nbf, iat) or 'expired'. The measured default leeway for both the gateway and Spring was approximately 60 seconds. Sync NTP before increasing the leeway.

④ Storing Tokens in Browser Storage. If an SPA stores access and refresh tokens in localStorage , a single XSS vulnerability exposes everything. 'OAuth 2.0 for Browser-Based Applications', which became RFC 10017 (BCP 212) in August 2026, ranks patterns by security order from BFF (Backend for Frontend) to token-mediating backend to standalone browser, noting that standalone browser usage is vulnerable to all previously discussed attacks. A BFF acts as a server-side client with secrets, storing tokens on the server and issuing only HttpOnly session cookies to the browser. In other words, it is the server-side implementation of the SDK approach in Section 5.

⑤ Ignoring aud. As seen in the Keycloak default aud: account from Section 4, if a token intended for another target is accepted even though it is not meant for your API, tokens from other apps on the same IdP can be used to call your API.

⑥ Secure Cookies and Plaintext HTTP. The IdP's login cookie has Secure attached (measured). Browsers treat localhost·127.0.0.1 as a secure origin and send it, but do not send it over plaintext HTTP addresses on a LAN, causing infinite 'logged in, but back to the login screen' loops. During our measurements, a Python cookie store failed to send the cookie for this exact reason, resulting in a 400 error.

⑦ JWKS Key Rotation. When the IdP rotates keys, tokens with a new kid arrive. Validators that cache keys for too long (Envoy defaults to 10 minutes) may reject them during that window, so the IdP should publish new keys in advance and delay signing with them, while validators should re-fetch JWKS from unknown kid .

⑧ Gateway Bypassing and Header Spoofing. If the app trusts X-Auth-Request-User in a gateway setup, there must be no path to call the app directly from the outside by injecting those headers.

9. Which One to Choose

10. Conclusion

• SSO integration comes down to the question of 'who performs the OIDC flow'. Whether it is an in-app library (agents, SDK) or a proxy in front of the app (gateway), the tasks remain identical: redirects, PKCE, code exchange, signature and claim validation, sessions, renewal, and logout.
• Signatures only verify the issuer. iss·aud·exp·nonce must be checked separately, and the measured Keycloak access token's default aud was not the API name.
• Logouts are threefold. While our measurements showed back-channel notifications arriving in just 66ms, signature-only verifiers allowed access tokens to pass through normally for the remaining 5 minutes.
• Keycloak's language-specific adapters have been deprecated in versions 23 and 25, and standard OIDC support for each platform is now used instead.

Titi's Note: Even if a pass (token) has a stamp (signature), you still need to check separately whether it belongs to 'our ping-pong room' (aud) and is valid for 'today's date' (exp). Also, even after someone is asked to leave, the pass in their hand remains valid until its expiration date, so it's best to issue them with short lifespans.

References

• RFC 6749, OAuth 2.0. §4.1.2 (Recommendation to revoke previously issued tokens upon code reuse). https://www.rfc-editor.org/rfc/rfc6749.html
• RFC 7636, PKCE. §4.1, §4.2, Appendix B. https://www.rfc-editor.org/rfc/rfc7636.html
• RFC 9700, OAuth 2.0 Security Best Current Practice (2025-01). §2.1, §2.1.1, §2.1.2, §2.2.2, §2.4. https://www.rfc-editor.org/rfc/rfc9700.html
• RFC 10017, OAuth 2.0 for Browser-Based Applications (BCP 212, 2026-08). §5, §6. https://www.rfc-editor.org/rfc/rfc10017.html
• RFC 7519 (JWT) §4.1.4, §4.1.5, RFC 7515 (JWS) §3.1, §7.1, RFC 7517 (JWK) §4.5, §5, RFC 8725 (JWT BCP) §3.1, §3.2, §3.9, RFC 7662 (introspection) §2.1, §2.2, RFC 9068 (JWT Access Tokens) §2.1, §4. https://www.rfc-editor.org/
• OpenID Connect Core 1.0 §2, §3.1.2.1, §3.1.3.7 https://openid.net/specs/openid-connect-core-1_0.html · Discovery 1.0 §4 https://openid.net/specs/openid-connect-discovery-1_0.html · Back-Channel Logout 1.0 §2.4, §2.5 https://openid.net/specs/openid-connect-backchannel-1_0.html · Front-Channel Logout https://openid.net/specs/openid-connect-frontchannel-1_0.html · RP-Initiated Logout https://openid.net/specs/openid-connect-rpinitiated-1_0.html
• OASIS, SAML V2.0 Technical Overview §4.6, §5.1.2. https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html
• Keycloak Blog: Adapter Deprecation (2022-02) https://www.keycloak.org/2022/02/adapter-deprecation · Update (2023-03) https://www.keycloak.org/2023/03/adapter-deprecation-update · 23.0.0 https://www.keycloak.org/2023/11/keycloak-2300-released · 25.0.0 https://www.keycloak.org/2024/06/keycloak-2500-released.html · keycloak-js separation (2025-02) https://www.keycloak.org/2025/02/keycloak-js-2620-released
• Spring Security Resource Server JWT (Clock Skew 60 seconds) https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html · OAuth2 Client Core https://docs.spring.io/spring-security/reference/servlet/oauth2/client/core.html · Spring Boot Starters https://docs.spring.io/spring-boot/reference/using/build-systems.html
• oauth2-proxy: Endpoints https://oauth2-proxy.github.io/oauth2-proxy/features/endpoints · Configuration (cookie_refresh and cookie_expire defaults) https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview
• Envoy jwt_authn (cache_duration default 10 minutes) https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/jwt_authn/v3/config.proto
• All original sources were accessed and verified on 2026-10-26.