Learn-skills.dev oracle-idcs-org-provisioning

Use when mapping IDCS claims to org membership after OAuth login succeeds. Covers mapProfileToUser, session.create.before, session.create.after hooks, MERGE INTO upserts, tenant-org mapping, and first-admin bootstrap. Keywords: IDCS groups, org_members, provisioning, session hooks, tenant map, MERGE INTO.

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/acedergren/agentic-tools/oracle-idcs-org-provisioning" ~/.claude/skills/neversight-learn-skills-dev-oracle-idcs-org-provisioning && rm -rf "$T"

manifest: data/skills-md/acedergren/agentic-tools/oracle-idcs-org-provisioning/SKILL.md

source content

Oracle IDCS Org Provisioning

Use when login succeeds but tenant, role, or org membership still has to become real in Oracle.

Do NOT load when

problem is Fastify header bridging or cookie/session forwarding
problem is base OIDC setup, callback URLs, or trusted origins
task is renaming IDCS concepts across an existing codebase

Three-stage flow

Capture IDCS claims during OAuth profile mapping (
```
mapProfileToUser
```
)
Gate session in
```
session.create.before
```
when explicit allow-rules exist
Resolve org and upsert
```
org_members
```
in
```
session.create.after
```

NEVER

Never combine access gating with role mapping — they are separate decisions with separate failure modes
Never
```
SELECT
```
then
```
INSERT
```
into
```
org_members
```
— use atomic
```
MERGE INTO
```
or concurrent logins corrupt membership
Never consume cached claims in
```
before
```
and expect them still available in
```
after
```
— use stash/peek/consume pattern
Never bypass existing membership precedence with a newer fallback — re-login instability follows
Never assume missing
```
groups
```
claim is a provisioning bug — check scope config and IDCS app first

Expert decision trees

Access gate vs. role mapping

These answer different questions:

Access gate (
```
before
```
hook): can this user enter at all? Controlled by DB-configured allow-groups. Fail closed only when explicit allow-groups exist; fail open otherwise.
Role mapping (
```
after
```
hook): which role do they get? Controlled by group→role mapping and env defaults.

Mixing them produces false lockouts: a user passes the access gate but gets the wrong role because the gating logic short-circuited role resolution.

Org resolution precedence

Always use this order — never skip a level for "simplicity":

Existing membership in
```
org_members
```
Tenant-name → org map (DB-configured)
DB-configured default org
Env default org

Changing this order mid-deployment breaks re-login for users who were previously assigned via a higher-precedence rule.

First-admin bootstrap

Fresh installs have zero admin-group config. If an org has no admin yet, promote the first provisioned user to

admin

once. Without this gate, the system is unbootstrappable — no one can configure allow-groups because no one has admin rights.

Claims cache across hook boundary

Hooks run in separate request lifecycles. The claim set from

mapProfileToUser

is not available in

session.create.after

without explicit passing:

```
stash(sub, claims)
```
in profile mapping
```
peek(sub)
```
in
```
before
```
(read without clearing)
```
consume(sub)
```
in
```
after
```
(read and clear)

Using a short-lived in-memory cache keyed by

sub

is the standard pattern. TTL of ~30s is sufficient.

Failure modes by decision point

Situation	Decision
No `groups` claim	Check scope and IDCS app config before touching provisioning code
No explicit DB allow-groups	Fail open — no lockout
DB lookup or write fails	Fail open for login, log it — lockout must never be the default outcome
Org has no admin yet	Promote first provisioned user once

Scripts

# Preview group → role mapping
node scripts/preview-group-role-mapping.js "PortalAdmins,Developers"

# Preview org resolution
node scripts/verify-org-resolution.js --tenant sandbox --map "sandbox:org-123,prod:org-999" --default-org org-000

Arguments

```
$ARGUMENTS
```
: Optional provisioning focus
- ```
tenant-map
```
  — focus on tenant→org resolution
- ```
first-admin
```
  — focus on bootstrap logic
- (empty) — evaluate the full IDCS claim → org membership flow