Index of every page on this site: llms.txt
All skills
acedergren avatar

/oracle-idcs-better-auth-setup

@641a79b
Run it yourself

Use when the user asks to "connect Better Auth to OCI IAM", "configure identity domain OIDC", "fix IDCS callback URL", "set trusted origins", or "bootstrap Oracle auth provider".

Use this Skill: https://skilld.dev/gh/acedergren/agentic-tools/oracle-idcs-better-auth-setup

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈52 tokens for metadata: the name and description. ≈1.1k when used: this file.

Description uses 2.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈210 characters, or 2.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Oracle IDCS + Better Auth Setup

Do NOT load this skill when

Do not load this skill for unrelated general programming, non-Oracle cloud work, or questions covered by a narrower sibling skill.

When to Use

Load this skill for: the user asks to "connect Better Auth to OCI IAM", "configure identity domain OIDC", "fix IDCS callback URL", "set trusted origins", or "bootstrap Oracle auth provider".

Prefer this skill only for its named domain. For broader OCI architecture triage, start with oci/best-practices as the router.

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 the groups claim 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: oci/fastify-better-auth-bridge

Is the problem in post-login membership, groups, or org_members writes?
├── Yes → Switch to: oci/oracle-idcs-org-provisioning

Is the user unsure which layer the bug is in?
├── Yes → Use this skill to verify setup checklist first

Foundation 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.js

Arguments

  • $ARGUMENTS: Optional setup focus
    • Example: /oci/oracle-idcs-better-auth-setup callback-url
    • Example: /oci/oracle-idcs-better-auth-setup trusted-origins
    • If empty: audit the full shared auth setup flow

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert7mo5 checks · Risk SAFE
  • Gen Agent Trust Hub7mo

    The skill provides a structured workflow and local validation scripts for configuring Oracle IDCS with Better Auth. It follows security best practices for secret management by utilizing environment variables and contains no malicious code, obfuscation, or unauthorized data access patterns.

  • Socket7mo

    No alerts

  • Snyk7mo

    Risk: LOW · No issues

  • Runlayer8mo

    5/5 files flagged

  • ZeroLeaks7mo

    1 finding · Score: 82/100

Signed by skilld at 641a79b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 2 months ago
version
2.0.0
aliases
[
  "oci-identity-better-auth-setup",
  "idcs-better-auth"
]
domains
[
  "oracle",
  "identity",
  "auth"
]
Other metadata
keywords
[
  "OCI IAM Identity Domains",
  "identity domain",
  "IDCS",
  "OIDC",
  "Better Auth",
  "Fastify",
  "Next.js",
  "callback URL",
  "trusted origins"
]

README badge

README badge for acedergren/agentic-tools/oracle-idcs-better-auth-setup