Oracle Idcs Better Auth Setup
- 10 installs
- 22 repo stars
- Updated May 28, 2026
- acedergren/agentic-tools
oracle-idcs-better-auth-setup is a Claude Code skill that sets up Better Auth with Oracle IDCS / OCI IAM OIDC and routes auth problems to the right sub-skill.
About
oracle-idcs-better-auth-setup is a Claude Code skill for wiring Better Auth to Oracle IDCS / OCI IAM using OIDC. It acts as a router that diagnoses where an auth problem lives (setup, Fastify bridge, or org provisioning) and covers callback URLs, trusted origins, required scopes, and provider bootstrap order. A developer uses it when standing up the shared auth foundation across Fastify and Next.js apps. It bundles env-validation and setup-checklist scripts.
- Router skill for setting up Better Auth with Oracle IDCS / OCI IAM (OIDC)
- Enforces env-first provider bootstrap, correct callback URLs, and required IDCS scopes
- Includes env-validation and setup-checklist scripts and a decision tree to the right sub-skill
Oracle Idcs Better Auth Setup by the numbers
- 10 all-time installs (skills.sh)
- Ranked #3,590 of 4,347 Backend & APIs skills by installs in the Skillselion catalog
- Data as of Jul 28, 2026 (Skillselion catalog sync)
oracle-idcs-better-auth-setup capabilities & compatibility
Free skill; requires Oracle IDCS / OCI IAM credentials and env config for the auth provider.
- Capabilities
- auth setup · oidc config · provider bootstrap · auth diagnosis
- Works with
- oracle
- Use cases
- api development · security audit
- Pricing
- Free
What oracle-idcs-better-auth-setup says it does
Use when setting up Better Auth with Oracle IDCS/OCI IAM, configuring OIDC callback URLs, trusted origins, provider bootstrap order, or sharing an auth model between Fastify and Next.js.
Never skip `urn:opc:idm:__myscopes__` from IDCS scopes — its absence silently removes the `groups` claim from tokens, breaking all role-based logic downstream.
npx skills add https://github.com/acedergren/agentic-tools --skill oracle-idcs-better-auth-setupAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 10 |
|---|---|
| repo stars | ★ 22 |
| Last updated | May 28, 2026 |
| Repository | acedergren/agentic-tools ↗ |
What it does
Set up Better Auth with Oracle IDCS / OCI IAM OIDC, including callback URLs, scopes, trusted origins, and provider bootstrap.
Who is it for?
Standing up the shared Oracle IDCS + Better Auth foundation across Fastify and Next.js apps.
Skip if: Fastify request/session bridge internals or post-login org provisioning, which have their own skills.
When should I use this skill?
Setting up Better Auth with Oracle IDCS/OCI IAM, configuring OIDC callback URLs, trusted origins, or provider bootstrap.
What you get
A working Oracle IDCS + Better Auth foundation with correct callbacks, scopes, trusted origins, and env-first bootstrap.
- OIDC auth configuration
- provider bootstrap logic
- setup verification checklist
By the numbers
- Six-step foundation verification order
- Four required OIDC scopes (openid, email, profile, __myscopes__)
Files
Oracle IDCS + Better Auth Setup
Entry skill for the full auth foundation: Oracle adapter, OIDC config, trusted origins, callback URLs, provider bootstrap, and cross-app consistency.
This is a router, not a deep implementation guide. Use it to diagnose where the problem lives, then hand off to the right skill.
NEVER
- Never mix full-stack setup guidance with Fastify bridge internals or org provisioning internals — each skill owns its domain.
- Never bootstrap providers from DB on cold-start — seed from env first, then reflect into Oracle provider tables for operator visibility.
- Never write provider bootstrap that overwrites existing operator-managed rows — idempotent create-if-missing only.
- Never skip
urn:opc:idm:__myscopes__from IDCS scopes — its absence silently removes thegroupsclaim from tokens, breaking all role-based logic downstream. - Never trust that OAuth success means local session success — wrong callback URL produces OAuth success followed by local session failure, a misleading failure mode.
Decision Tree: Which Skill Owns This?
Is the problem in the auth foundation (setup, config, bootstrap)?
├── Yes → Stay in this skill
Is the problem in runtime request/session handling in Fastify?
├── Yes → Switch to: fastify-better-auth-bridge
Is the problem in post-login membership, groups, or org_members writes?
├── Yes → Switch to: oracle-idcs-org-provisioning
Is the user unsure which layer the bug is in?
├── Yes → Use this skill to verify setup checklist firstFoundation Verification Order
When diagnosing setup issues, verify in this exact order (later items depend on earlier ones):
1. Oracle adapter and Better Auth tables exist in DB 2. IDCS confidential application uses the correct callback URL 3. Scopes include openid,email,profile,urn:opc:idm:__myscopes__ 4. Trusted origins and cookie attributes match the deployed app topology 5. Env config can cold-start auth before DB-managed provider settings are edited 6. Env-to-DB bootstrap is idempotent and never overwrites existing provider rows
Non-Obvious Setup Rules
Env-first bootstrap: Auth must be functional from env vars alone before provider rows exist in DB. Provider rows are for operator visibility, not for cold-start. If you invert this, auth breaks on first deploy before any DB seed runs.
Shared building blocks: Oracle adapter, cookie rules, IDCS profile mapper, and session hook behavior must be shared across Fastify and Next.js apps. Diverging these two causes subtle token/session inconsistencies that are hard to trace.
Naming stability: When the codebase already uses IDCS and OCI_IAM_* env var naming, keep it. Mixing naming schemes (e.g., introducing ORACLE_* vars) breaks scripts and makes the env matrix confusing.
Callback URL failure mode: A wrong callback URL looks like OAuth flow succeeds (IDCS redirects back) but local session creation fails immediately after. Check this before debugging anything else if login appears to "complete" but the user isn't authenticated.
Common Gotchas
| Symptom | Likely Cause |
|---|---|
No groups claim in token | Missing urn:opc:idm:__myscopes__ scope |
| OAuth succeeds, session fails | Wrong callback URL in IDCS app config |
| Provider rows wiped on deploy | Bootstrap logic not idempotent |
| Auth works locally, fails in prod | Trusted origins missing prod domain |
Scripts
# Validate all required env vars are set
node scripts/validate-idcs-env.js
# Print full setup checklist with current state
node scripts/print-auth-checklist.jsArguments
$ARGUMENTS: Optional setup focus- Example:
/oracle-idcs-better-auth-setup callback-url - Example:
/oracle-idcs-better-auth-setup trusted-origins - If empty: audit the full shared auth setup flow
BETTER_AUTH_SECRET=replace-me
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_TRUSTED_ORIGINS=http://localhost:3000,http://localhost:3001,http://localhost:5173
OCI_IAM_CLIENT_ID=replace-me
OCI_IAM_CLIENT_SECRET=replace-me
OCI_IAM_DISCOVERY_URL=https://idcs-<tenant>.identity.oraclecloud.com/.well-known/openid-configuration
OCI_IAM_IDP_NAME=
OCI_IAM_ADMIN_GROUPS=PortalAdmins,OCI_Administrators,Administrators
OCI_IAM_OPERATOR_GROUPS=
OCI_IAM_DEFAULT_ORG_ID=
OCI_IAM_TENANT_ORG_MAP=
.env
#!/usr/bin/env node
const steps = [
'Verify Oracle adapter and auth tables exist before editing app wrappers.',
'Configure OCI IDCS confidential app with the Better Auth callback URL.',
'Include scopes: openid,email,profile,urn:opc:idm:__myscopes__.',
'Seed mutable OAuth config from env for cold-start availability.',
'Share Oracle adapter, cookie config, and IDCS profile mapping across apps.',
'Keep nextCookies() last in the Next.js Better Auth plugin list.',
'Bootstrap OCI_IAM_* env vars into Oracle provider tables without overwriting existing rows.',
'Only then debug Fastify session resolution and org membership behavior.',
];
console.log('Oracle IDCS + Better Auth checklist');
console.log('');
steps.forEach((step, index) => console.log(`${index + 1}. ${step}`));
#!/usr/bin/env node
const required = [
'BETTER_AUTH_SECRET',
'BETTER_AUTH_URL',
'OCI_IAM_CLIENT_ID',
'OCI_IAM_CLIENT_SECRET',
'OCI_IAM_DISCOVERY_URL',
];
const missing = required.filter((key) => !process.env[key]);
console.log('Oracle IDCS + Better Auth env validation');
console.log('');
for (const key of required) {
console.log(`${process.env[key] ? '✓' : '✗'} ${key}`);
}
console.log('');
const callback = `${process.env.BETTER_AUTH_URL || '<BETTER_AUTH_URL>'}/api/auth/oauth2/callback/oci-iam`;
console.log(`Expected callback URL: ${callback}`);
console.log('Expected scopes: openid,email,profile,urn:opc:idm:__myscopes__');
if (missing.length > 0) {
console.error('');
console.error(`Missing required variables: ${missing.join(', ')}`);
process.exit(1);
}
console.log('');
console.log('Environment looks complete enough for first-pass setup.');
Related skills
Lark Openapi ExplorerInstantly explore, test, and generate calls against the full Lark (Feishu) OpenAPI surface without leaving their agent workflow.493k
Lark EventConsume real-time events from Lark/Feishu as structured NDJSON streams inside AI agent workflows.387k16kLark Openapi ExplorerWhen an existing Lark/Feishu skill or CLI command cannot fulfill a specific requirement and they need to discover and invoke the exact native OpenAPI endpoint.386k16k
Just ScrapeQuickly search, crawl, extract structured JSON, or monitor web pages without writing custom scraping code.245k41Lark AppsQuery the current visibility and permission scope of a Lark (Feishu) app without writing HTTP client code.235k16k
Design An InterfaceGenerate multiple radically different interface or API designs in parallel before committing to one.188k198kFAQ
Why is the groups claim missing from my token?
The IDCS scopes are missing urn:opc:idm:__myscopes__, whose absence silently removes the groups claim and breaks all role-based logic downstream.
OAuth succeeds but my user is not authenticated. Why?
A wrong callback URL makes IDCS redirect back successfully while local session creation fails immediately after; check the callback URL first.