TRIAL 2026-11-18
  • Kotlin 89.7%
  • Shell 10.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Travis Johnson e6bd45c992 MIT license; README: consume as a Gradle source dependency
Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X3rSFQKNvZAyVWrq8pPxvK
2026-11-18 20:38:09 -06:00
bin misk-oidc: OIDC bearer-JWT authentication for misk services 2026-11-11 12:45:46 -06:00
gradle misk-oidc: OIDC bearer-JWT authentication for misk services 2026-11-11 12:45:46 -06:00
src misk-oidc: OIDC bearer-JWT authentication for misk services 2026-11-11 12:45:46 -06:00
.gitignore MIT license; README: consume as a Gradle source dependency 2026-11-18 20:38:09 -06:00
build.gradle.kts misk-oidc: OIDC bearer-JWT authentication for misk services 2026-11-11 12:45:46 -06:00
gradle.properties misk-oidc: OIDC bearer-JWT authentication for misk services 2026-11-11 12:45:46 -06:00
gradlew misk-oidc: OIDC bearer-JWT authentication for misk services 2026-11-11 12:45:46 -06:00
LICENSE MIT license; README: consume as a Gradle source dependency 2026-11-18 20:38:09 -06:00
README.md MIT license; README: consume as a Gradle source dependency 2026-11-18 20:38:09 -06:00
settings.gradle.kts misk-oidc: OIDC bearer-JWT authentication for misk services 2026-11-11 12:45:46 -06:00

misk-oidc

OIDC bearer-token authentication for misk services. Written against Pocket ID; nothing in it is Pocket ID specific.

install(OidcAuthModule(OidcAuthConfig(issuer = "https://id.example.net", audiences = listOf("my-client-id"))))

@Get("/admin") @Authenticated(capabilities = ["kv-admins"])   // members of the issuer's kv-admins group

OidcAuthModule installs misk's AccessControlModule (without which @Authenticated is not enforced at all) and an authenticator where caller = preferred_username (else sub) and capabilities = the token's groups. Services with their own notion of identity use OidcVerifier directly and map OidcIdentity themselves.

What is checked

  • Signature (RS256/384/512) against the issuer's JWKS, fetched via discovery. none and HS* are rejected. Unknown kid triggers a refetch, at most once per jwks_min_refresh_seconds.
  • iss equals the configured issuer; aud intersects audiences (required, non-empty); exp and nbf with clock_skew_seconds of slack.
  • Not checked: revocation. A token is good until exp.

The token is read from Authorization: Bearer, else X-Auth-Request-Access-Token, else X-Forwarded-Access-Token (token_headers) — the last two are what oauth2-proxy passes a backend. An access token that carries only sub is resolved through the issuer's userinfo endpoint; the result is cached for cache_seconds. Claims in the signed token win over userinfo.

Using it

implementation("tcj:misk-oidc:0.1.0")
testImplementation(testFixtures("tcj:misk-oidc:0.1.0"))   // FakeIdp: an in-process issuer that mints tokens

It is not on Maven Central. Consumers pull it straight from this repository as a Gradle source dependency, in their settings.gradle.kts (version 0.1.0 resolves to the git tag 0.1.0):

sourceControl {
  gitRepository(uri("https://github.com/traviscj/misk-oidc.git")) { producesModule("tcj:misk-oidc") }
}

or, to work on both at once, from a sibling checkout as a composite build:

file("../misk-oidc").takeIf { it.isDirectory }?.let { includeBuild(it) }

Development

. bin/activate-hermit
./gradlew test
OIDC_LIVE_ISSUER=https://id.example.net ./gradlew test --tests '*OidcAuthTest*' -i   # real discovery + JWKS
# add OIDC_LIVE_AUDIENCE=<client id> OIDC_LIVE_TOKEN=<jwt> to verify a real token and print who it is

License

MIT.