DEV Community: Joao Marcos Costa Salles

Passwords are not necessary, a Oauth/OIDC approach

Joao Marcos Costa Salles — Tue, 30 Jun 2026 21:19:57 +0000

Intro

It is possible to skip the burden of password management, security, encryption and password rotations.
When using OAuth 2.0 with OIDC (OpenID Connect), the user can log in with third-party accounts like
Google, GitHub, X and others — an easier way to sign in.

In this document, I will explain an approach using OAuth 2.0 with a React frontend and a Kotlin Spring Boot
backend to validate the third-party credentials and generate our own.

The flow at a glance

sequenceDiagram
  Frontend->>Frontend: loads script and initialize with CLIENT_ID
  Frontend->>+Google Identity Services: modal login
  Google Identity Services-->>Frontend: credentials

  Frontend->>+Our API Authentication Service: credentials
  Our API Authentication Service->>+Google Identity Services: validate credentials
  Google Identity Services-->>-Our API Authentication Service: confirmation
  Our API Authentication Service-->>-Frontend: ours generated tokens

OAuth 2.0

OAuth 2.0 is an authorization framework: it lets a user grant an application access to a resource without sharing a password with that application. On its own OAuth 2.0 says nothing about "who the user is", that is OpenID Connect (OIDC), a thin identity layer
on top of OAuth 2.0 that adds the ID token: a signed JWT asserting an authenticated identity (email, subject, issuer, audience, expiry).
Google Identity Services implements OIDC, so the "credential" the browser receives is an OIDC ID token. We use it purely as
proof of identity, then mint our own tokens for authorization inside our API.

OpenID Connect

OpenID Connect (OIDC) is a thin authentication layer standardized on top of OAuth 2.0. Where OAuth 2.0 only answers "is this app allowed to access something?", OIDC answers "who
is this user, and has the provider authenticated them?" It does this by adding the ID token — a JWT, signed by the identity provider, whose standard claims describe the authenticated user: sub (a stable user id), iss (who issued it), aud (which app it was issued for), exp/iat (validity window), and identity claims like email and email_verified.
OIDC also standardizes discovery (a /.well-known/openid-configuration document) and a JWKS endpoint publishing the provider's public signing keys, so any backend can verify an ID token's signature offline without calling the provider on every
login(we calling it on every login).
Google Identity Services is an OIDC provider, so the credential our frontend receives is an OIDC ID token, and our API trusts it only after validating those standard claims (issuer, audience, signature, expiry, email_verified) against Google's published keys.

Key OAuth 2.0 / OIDC concepts used here

ID token (the credential) — a JWT signed by Google. Its trust comes from Google's signature, not from the channel it travelled on.
Issuer (iss) — who minted the token. We trust only a configured allow-list (https://accounts.google.com).
Audience (aud) — who the token was minted for. It must equal our Google CLIENT_ID, otherwise a token issued for some other app could be replayed against us.
JWKS / OIDC discovery — Google publishes its public signing keys at a well-known URL.( it is possible to cache the result to prevent rework)
Signature, expiry, and claim checks — standard JWT validation: the token must be unexpired, correctly signed, and carry a email_verified: true claim.

Why we don't just keep using the Google token

The provider's ID token proves the user is who they say they are, but it is the wrong credential to trust on our APIs. The main reasons are:

It is issued for Google's lifecycle, not ours — we cannot control its TTL, claims, or revocation.
It carries Google's notion of the user, not ours — it knows nothing about the user's authorizations, roles and other controls related to our system.
It is short-lived and not designed to be replayed against our backend on every call.

So we follow the standard pattern: verify the external credential once, then issuefirst-party tokens scoped to our domain. From that point on, our API only ever trusts our own tokens.

Implementation

1. Frontend obtains the Google credential

The SPA loads Google Identity Services, initializes it with our CLIENT_ID, and shows the Google sign-in modal. Google returns an OIDC credential (ID token JWT) to the page.

First, create an account on https://console.cloud.google.com, create a project and an OAuth 2.0 client, and get the Client ID. You will also need to configure the authorized JavaScript origins.
To test locally, I added http://localhost:4200, for example.

Create a component to call the scripts and handle the authentication response.

<Suspense fallback={<p>Loading sign-in…</p>}>
  <AuthApp onAuthenticated={onAuthenticated} />
</Suspense>

Now we add a component to handle future providers; for now we are only use Google.

//auth/src/AuthApp.tsx
import { useCallback, useEffect, useRef, useState } from 'react';
import { providers } from './auth/providers';
import type { AuthHandlers, AuthProvider, AuthResult } from './auth/types';

export interface AuthAppProps {
  /** Called with the provider result (incl. the Google-signed ID token). */
  onAuthenticated?: (result: AuthResult) => void;
}

// Mounts one provider's sign-in UI into a container div. Google renders its
// official button here; the effect runs once per provider, reading the latest
// handlers via a ref so changing callbacks doesn't re-mount the button.
function ProviderSlot({
  provider,
  handlers,
}: {
  provider: AuthProvider;
  handlers: AuthHandlers;
}) {
  const ref = useRef<HTMLDivElement>(null);
  const handlersRef = useRef(handlers);
  handlersRef.current = handlers;

  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    const cleanup = provider.mount(el, {
      onResult: (r) => handlersRef.current.onResult(r),
      onError: (e) => handlersRef.current.onError(e),
    });
    return () => {
      if (typeof cleanup === 'function') cleanup();
      el.replaceChildren();
    };
  }, [provider]);

  return <div ref={ref} />;
}

export function AuthApp({ onAuthenticated }: AuthAppProps) {
  const [error, setError] = useState<string | null>(null);

  const onResult = useCallback(
          (result: AuthResult) => {
            setError(null);
            onAuthenticated?.(result);
          },
          [onAuthenticated],
  );
  const onError = useCallback((e: Error) => setError(e.message), []);

  return (
          <div style={{ display: 'grid', gap: 12, maxWidth: 320 }}>
            <h2 style={{ margin: 0 }}>Sign in</h2>
            {providers.map((provider) => (
                    <ProviderSlot
                            key={provider.id}
                            provider={provider}
                            handlers={{ onResult, onError }}
                    />
            ))}
            {error && <p style={{ color: 'crimson', margin: 0 }}>{error}</p>}
          </div>
  );
}

export default AuthApp;

//auth/src/auth/providers.ts
import { googleProvider } from './google';
import type { AuthProvider } from './types';

// The client-side sign-in providers shown in the auth widget. Google is first.
// Add another provider by implementing its `mount` and appending it here.
export const providers: AuthProvider[] = [googleProvider];

//auth/src/auth/google.ts

const GSI_SRC = 'https://accounts.google.com/gsi/client';
const CLIENT_ID = import.meta.env.VITE_GOOGLE_CLIENT_ID ?? '';

let gsiPromise: Promise<void> | null = null;

// Inject the Google Identity Services script once and resolve when ready.
function loadGsi(): Promise<void> {
  gsiPromise ??= new Promise<void>((resolve, reject) => {
    if (typeof window !== 'undefined' && 'google' in window) {
      resolve();
      return;
    }
    const script = document.createElement('script');
    script.src = GSI_SRC;
    script.async = true;
    script.defer = true;
    script.onload = () => resolve();
    script.onerror = () => reject(new Error('Failed to load Google Identity Services'));
    document.head.appendChild(script);
  });
  return gsiPromise;
}

// Decode the JWT payload for DISPLAY ONLY — the signature is NOT verified here.
// The backend must verify the token before trusting any of these claims.
function decodeIdToken(jwt: string): GoogleIdTokenClaims | undefined {
  try {
    const payload = jwt.split('.')[1];
    const b64 = payload.replace(/-/g, '+').replace(/_/g, '/');
    const json = decodeURIComponent(
            atob(b64)
                    .split('')
                    .map((c) => '%' + c.charCodeAt(0).toString(16).padStart(2, '0'))
                    .join(''),
    );
    return JSON.parse(json) as GoogleIdTokenClaims;
  } catch {
    return undefined;
  }
}

export const googleProvider: AuthProvider = {
  id: 'google',
  label: 'Continue with Google',
  mount(container, { onResult, onError }) {
    if (!CLIENT_ID) {
      onError(new Error('VITE_GOOGLE_CLIENT_ID is not set'));
      return;
    }
    let cancelled = false;
    loadGsi()
            .then(() => {
              if (cancelled) return;
              google.accounts.id.initialize({
                client_id: CLIENT_ID,
                ux_mode: 'popup',
                auto_select: false,
                callback: (resp) => {
                  onResult({
                    provider: 'google',
                    credential: resp.credential,
                    profile: decodeIdToken(resp.credential),
                  });
                },
              });
              google.accounts.id.renderButton(container, {
                type: 'standard',
                theme: 'outline',
                size: 'large',
                text: 'continue_with',
                shape: 'rectangular',
                logo_alignment: 'left',
              });
            })
            .catch((e) => onError(e instanceof Error ? e : new Error(String(e))));

    return () => {
      cancelled = true;
    };
  },
};

2. Credential exchange — `POST /validate/oauth`

The frontend posts the credential to our API:

{ "provider": "google", "credential": "<google-id-token>", "profile": { ... } }

We need an endpoint that is called after the frontend OAuth2 flow. There we validate the credential
the provider generated, then issue our own:

//com/weImpact/auth/controller/AuthController.kt
@PostMapping("/validate/oauth")
fun validateOAuth(@RequestBody req: OAuthLoginRequest, response: HttpServletResponse): TokenResponse {
  val email = try {
    validator.validate(req.credential)
  } catch (e: JwtException) {
    throw unauthorized()
  }

  // validate if the email exists
  val user = users.findByEmail(email) ?: throw unauthorized()
  // issue ours credentials
  return issueFor(user, response)
}

validator.validate performs full OIDC verification:

//com/weImpact/auth/security/OAuthCredentialValidator.kt
class OAuthCredentialValidator(
  trustedIssuers: List<String>,
  private val googleClientId: String,
  decoderForIssuer: (String) -> JwtDecoder = { JwtDecoders.fromIssuerLocation(it) },
) {
  private val decoders: Map<String, JwtDecoder> =
    trustedIssuers.associate { it.trim() to decoderForIssuer(it.trim()) }

  private val log = LoggerFactory.getLogger(OAuthCredentialValidator::class.java)

  fun validate(credential: String): String {
    val issuer = runCatching { SignedJWT.parse(credential).jwtClaimsSet.issuer }
      .getOrNull() ?: throw BadJwtException("missing or malformed iss")
    val decoder = decoders[issuer] ?: throw BadJwtException("untrusted issuer: $issuer")

    val jwt = decoder.decode(credential)
    if (googleClientId !in jwt.audience.orEmpty()) throw BadJwtException("unexpected audience")
    val email = jwt.getClaimAsString("email") ?: throw BadJwtException("missing email claim")
    if (jwt.getClaim<Any>("email_verified") != true) throw BadJwtException("email not verified")
    return email
  }
}

Parse the iss claim and reject it unless it is a trusted issuer.
Require the audience to contain our Google CLIENT_ID.
Require an email claim and email_verified: true.
Return the verified email.

This flow can validate different issuers. JwtDecoders.fromIssuerLocation gets information from the issuer (OIDC discovery);
the result can be cached to improve performance. It fetches <issuer>/.well-known/openid-configuration
(for example, Google's) over the network,
reads the jwks_uri from it, and builds a decoder wired to that provider's public keys (JWKS).
For Google, that's how it learns Google's signing keys.

3. Creating our credentials

A verified Google identity is not enough to get in. The email must map to a known,
ACTIVE user in our database; otherwise the request is rejected with 401.

For an accepted user we build an AppPrincipal (user id, email, role, institution ids) and
issue two HS256-signed JWTs via TokenService:

Access token — short-lived (~15m). Carries email, role, institutionIds, and token_type=access. Sent to the frontend in the JSON response body and attached as a Bearer token on subsequent API calls.
Refresh token — long-lived (~30d). Carries only token_type=refresh and the user id as subject. Never returned in the response body — it is delivered as an HttpOnly, Secure, SameSite cookie so page JavaScript cannot read it (XSS-safe).

{ "accessToken": "<jwt>", "tokenType": "Bearer", "expiresIn": 900 }

private fun issueFor(user: User, response: HttpServletResponse): TokenResponse {
  if (user.status != UserStatus.ACTIVE) throw unauthorized()
  val institutionIds = memberships.findByUserId(user.id).map { it.institutionId }.toSet()
  val principal = AppPrincipal(user.id, user.email, user.role.name, institutionIds)
  val issued = tokens.issue(principal)
  // Refresh token leaves only as an HttpOnly cookie (unreadable by page JS → XSS-safe),
  // scoped to /refresh so it isn't attached to every request.
  response.addHeader(HttpHeaders.SET_COOKIE, refreshCookie(issued.refreshToken).toString())
  return TokenResponse(issued.accessToken, "Bearer", issued.expiresInSeconds)
}

private fun refreshCookie(token: String): ResponseCookie =
  ResponseCookie.from(REFRESH_COOKIE, token)
    .httpOnly(true)
    .secure(refreshCookieSecure)
    .sameSite(refreshCookieSameSite)
    .path("/")
    .maxAge(refreshTtl)
    .build()

With that we have created the credentials we can use on our business endpoints.
The frontend sends the header Authorization: Bearer <access-token>, and the server can verify its signature,
expiry, user information and roles, all without the need for password management.

References:

Designing an ER Diagram with an AI Pair — Why I Reached for Mermaid Instead of a diagram software

Joao Marcos Costa Salles — Wed, 24 Jun 2026 13:46:06 +0000

Introduction

I recently sat down to model the data for a payments + notification-feed
system: customers, projects, a double-entry ledger, PIX payouts, and a
WhatsApp delivery outbox. The kind of domain where one wrong column breaks an
invariant nobody notices until money goes missing.

My usual instinct would be to open draw.io, drag some boxes
around, and connect them with lines. Instead I did the whole thing
in Mermaid — a text-based diagramming language —
while bouncing the design back and forth with an AI assistant (Claude, in my
case), to be clear, I wrote it on my IDE not on the site.

That choice turned out to matter far more than I expected. The diagram stopped
being a picture of the design and became the design itself. Something the
AI could read, critique, and edit with surgical precision, and something I
could commit next to the code as a living spec.

Here's what I learned, in concrete cases.

erDiagram
    CUSTOMER ||--o{ PAYMENT : has
    PROJECT  ||--o{ PAYMENT : receives
    PAYMENT  ||--o| LEDGER_TRANSACTION : "settles via"
    LEDGER_TRANSACTION ||--|{ LEDGER_ENTRY : "has (sum = 0)"
    ACCOUNT  ||--o{ LEDGER_ENTRY : "posts to"

Case 1: Pin-point corrections on a single column

This is the difference that sold me.

In draw.io, a column lives inside a box, inside a shape, inside a canvas. If
I want an AI to fix one field, I have to describe it in prose, "in the
DELIVERY table, the third attribute, change the type", and then I go click
into the right cell and retype it. The AI can suggest, but it can't touch the
artifact.

With Mermaid, every column is just a line of text:

erDiagram
    DELIVERY {
        uuid id PK
        int feed FK
        uuid user_subscription FK
        string status "pending | sending | sent | failed"
        int attempts "default 0"
        string idempotency_key "unique; reserved for z-api dedup"
        string last_error "nullable"
        timestamp next_attempt_at "nullable; backoff gate"
        timestamp sent_at "nullable"
    }

When I described my retry-and-backoff requirements, the AI didn't hand-wave.
It proposed exact additions: attempts, next_attempt_at as a "backoff
gate", idempotency_key to make fan-out retries safe. I could see the precise
diff. A correction became "change int id PK to uuid id PK" and the model
edited that single token, leaving the other 200 lines untouched.

One specific kind of correction got dramatically easier:

Column semantics. The inline comments ("signed; +credit / -debit", "= SUM(entries)") carry intent. The AI used them to check the design against itself — e.g. confirming that a cached balance column is consistent with the ledger entries that derive it.

You simply cannot have that conversation about a PNG.

Case 2: The diagram doubles as a spec — in the repo, in version control

Because the diagram is plain text, it lives in the project:

docs/design/EntityRelation.md

That unlocks everything text gives you for free:

It diffs. A pull request that adds a BANK_ACCOUNT table or a new status enum value shows up as a readable diff in review, right next to the migration that implements it. A draw.io .drawio blob diffs into noise.
It's the source of truth. I treat the Mermaid file as the contract. The Flyway migrations and JPA entities have to match it; when they drift, the diagram is what we reconcile against. The design doc and the schema stop disagreeing.
It encodes invariants, not just shapes. I dropped comments straight into the diagram for rules the boxes can't express:

  %% Invariant: per LEDGER_TRANSACTION, SUM(LEDGER_ENTRY.amount) = 0.
  %% Money is only ever moved between accounts, never created/destroyed.

Those two lines are arguably the most important part of the whole system,
and they live with the diagram — readable by humans and by the AI that
later helps implement the ledger.

A drawing on a website is an artifact you export. A Mermaid file is an
artifact you own, version, and review like code.

Case 3: AI reasons better over "diagram-as-code" than over a picture

This is the part I underestimated.

When you hand an AI a picture of a diagram, it has to do vision — OCR the
labels, guess which line connects to which box, infer cardinality from tiny
crow's-foot glyphs. It's lossy and it's slow, and it quietly gets things wrong.

When you hand it Mermaid, you're handing it structured text it already
understands natively. The relationships are unambiguous tokens:

erDiagram
    INSTITUTION ||--o{ BANK_ACCOUNT : "pays out to"
    INSTITUTION ||--o{ ACCOUNT : "owns (wallet)"
    BANK_ACCOUNT ||--o{ LEDGER_TRANSACTION : "receives withdrawals"

||--o{ is "one-to-many" — the model doesn't have to squint at a graphic to
recover that; it's right there in the syntax. So the conversation moved up a
level. Instead of "I think this line means a one-to-many?", we discussed actual
design questions:

"Should an institution's wallet be its own table, or just an ACCOUNT with owner_type = 'wallet'?" (We chose the latter — fewer tables, one balance model.)
"A WITHDRAW needs a real-world destination — is the ledger ACCOUNT enough, or do we need a separate BANK_ACCOUNT with PIX fields?" (Separate table: pix_key, pix_key_type, soft-deleted via status = archived so old withdrawals still resolve.)

The AI could propose a whole new entity by appending well-formed Mermaid, and
I could paste it straight back into the file and render it. The feedback loop
was: discuss → it emits code → I render → I correct one line → repeat. No
export, no re-import, no redrawing.

With a draw.io picture, every one of those turns would have required me to be
the hands — translating the AI's prose suggestion back into clicks and drags.
The AI becomes an advisor you transcribe for, instead of a pair that edits with
you.

Conclusion

draw.io is great when the diagram is the deliverable, a polished picture for
a slide deck. But when the diagram is part of designing a system, and
especially when you're designing it alongside an AI, the calculus flips
completely:

Corrections are surgical: one column is one line of text the model can edit directly, not a cell you have to find and retype.
The diagram becomes a spec: it lives in the repo, diffs in review, and carries invariants the schema must uphold.
The AI reasons natively — Mermaid is structured text, not pixels, so the conversation rises from "what does this line mean?" to "is this the right model?".

The diagram stopped being a drawing of my intent and became a machine- and
human-readable statement of it. One my AI pair could read, challenge, and
co-edit token by token. For me, that's the whole game.

If you're modeling a domain with an AI assistant, try writing the ER diagram in
Mermaid first. Commit it next to your migrations. Let the model edit the text,
not describe a picture. You'll feel the difference on the very first
correction.

Creating a modular Kotlin project using gradle.

Joao Marcos Costa Salles — Wed, 27 May 2026 22:58:04 +0000

Introduction

The idea of building a system entirely composed of microservices is always tempting for a developer, whether for the challenge itself or to stay ahead of scaling needs. However, analyzing trade-offs and choosing what best fits our context is also part of our profession.
A very common decision today at the beginning of a project is to build modular projects as a way of anticipating a future need to split out a dedicated service. This approach adds less initial complexity than a microservices architecture, while keeping modules sufficiently independent for a potential future separation if needed.

In this article, I will show hot to set up Gradle to enable modules on a monolithic project.

my-inflation/src/main/kotlin/com/salles/scrapping
├── data        # DTO declarations
├── db
│   ├── tables  # Persistence table declarations
├── domain      # Business logic declarations
├── repositories
├── routes
├── services
└── scrapper    # Feature that could move to another project

To a modular monolith:

my-inflation
├── gradle
│   └── libs.versions.toml
├── myInflation  # Module to list prices and products
│   ├── src
│   └── build.gradle.kts
├── root         # Module to link other modules and set up Ktor
│   ├── src
│   └── build.gradle.kts
├── scrapper     # Module for scraping, which may move in the future
│   ├── src
│   └── build.gradle.kts
├── domain       # Module for domain declarations
│   ├── src
│   └── build.gradle.kts
├── data         # Module for the persistence layer
│   ├── src
│   └── build.gradle.kts
├── build.gradle.kts
└── settings.gradle.kts

Module Declaration

It is necessary to declare the modules in settings.gradle.kts. In my case:

include(":myInflation", ":root", ":scrapper", ":data", ":domain")

If you use the same name as the folder, Gradle will find it automatically. If for some reason you need a different name, you can map it explicitly:

project(":myInflation").projectDir = file("core")

Shared Version Catalog

It is very important to create a libs.versions.toml file in the folder structure shown above. In it, we will maintain the versions of all libraries, ensuring consistency across all modules while gaining the benefits of caching and reducing build size. The file will look like this:

[versions]
kotlin = "2.3.20"
kotlinx-serialization = "1.9.0"

[libraries]
kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization" }

[plugins]
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

Module Dependency Configuration

Configuring dependencies between modules is straightforward. I will configure only the root module here, but other modules may also depend on the domain module, for example, and will need their own declarations.
Inside root/build.gradle.kts, add:

dependencies {
    implementation(project(":domain"))
    implementation(project(":data"))
    implementation(project(":myInflation"))
    implementation(project(":scrapper"))
    // ...
}

Only the root module contains the server runner, so add:

application {
    mainClass = "io.ktor.server.netty.EngineMain"
}

Now we need to define which function should run to start the server. In root/src/main/resources/application.yaml:

ktor:
  application:
    modules:
      - com.salles.root.ApplicationKt.module

Removing Unnecessary Dependencies

Finally, we can trim each module's dependencies. To do so, we will use the dependency-analysis-gradle-plugin to analyze module dependencies.

In libs.versions.toml, add the plugin version:

[versions]
# ...
dependency-analysis = "3.13.0"

[plugins]
# ...
dependency-analysis = { id = "com.autonomousapps.dependency-analysis", version.ref = "dependency-analysis" }

In build.gradle.kts, add:
subprojects {
apply(plugin = "com.autonomousapps.dependency-analysis")
}

To run the analysis:

./gradlew <module>:projectHealth

Check {module}/build/reports/dependency-analysis for the report and change it if it makes sense.

With this, the project is configured for a modular structure. However, simply moving files is not enough — inter-module dependencies will still exist. It is necessary to define business logic that is exclusive to each feature module, but that is outside the scope of this article.

The dependency graph ends up looking like this. Note that scrapper and myInflation are now separated, with not direct dependency between the,:

References:

my-inflation: https://github.com/JoaoSalles/my-inflation-api

DEV Community: Joao Marcos Costa Salles

Passwords are not necessary, a Oauth/OIDC approach

Intro

The flow at a glance

OAuth 2.0

OpenID Connect

Key OAuth 2.0 / OIDC concepts used here

Why we don't just keep using the Google token

Implementation

1. Frontend obtains the Google credential

2. Credential exchange — POST /validate/oauth

3. Creating our credentials

Designing an ER Diagram with an AI Pair — Why I Reached for Mermaid Instead of a diagram software

Introduction

Case 1: Pin-point corrections on a single column

Case 2: The diagram doubles as a spec — in the repo, in version control

Case 3: AI reasons better over "diagram-as-code" than over a picture

Conclusion

Creating a modular Kotlin project using gradle.

Introduction

Module Declaration

Shared Version Catalog

Module Dependency Configuration

Removing Unnecessary Dependencies

2. Credential exchange — `POST /validate/oauth`