Getting Started

Getting Started

This guide walks you through setting up your first OIDC-to-groups mapping rules, from understanding your token to verifying in production.

Step 1: Understand your token

Before writing rules, you need to know what claims your identity provider sends. A typical JWT token payload looks like this:

{
  "sub": "jdoe",
  "email": "jdoe@example.com",
  "department": "Engineering",
  "roles": ["admin", "editor"],
  "organization": "corp.example.com",
  "userType": "INTERNAL",
  "extended_attributes": {
    "domain": "engineering.corp.example.com"
  }
}

How to inspect your token

• From your IdP: Most providers (Keycloak, Azure AD, Okta, Auth0) have a token preview or introspection tool.
• From Nextcloud logs: Enable debug logging in Nextcloud and look for the token payload in the OIDC login flow.
• From browser dev tools: During an OIDC login, the token is visible in the network tab (look for the id_token parameter).

Tip: You don't need to decode the full JWT — you only need the payload (the middle part between the two dots), which is base64-encoded JSON.

Step 2: Plan your mappings

Based on your token, decide which claims should produce which groups. Use this decision table to pick the right rule type:

I want to...	Use this type	Example
Use the claim value directly as a group name	direct	department → Engineering
Add a prefix to each value	prefix	roles with role_ → role_admin, role_editor
Map specific values to specific group names	map	organization: corp.example.com → Staff
Assign groups only when a condition is met	conditional	If userType equals INTERNAL → Internal-Users
Use a string template with the value	template	department with dept_{value} → dept_Engineering

See Rule Types Reference for the full details on each type.

Step 3: Choose the mode

The mode controls how rule-produced groups interact with groups from user_oidc's native mappingGroups claim:

Mode	Behavior
additive (default)	Rule-produced groups are merged with existing groups from mappingGroups
replace	Only rule-produced groups are kept. If rules produce nothing, falls back to existing groups (safety net)

Recommendation: Start with additive — it's safer and lets you layer rule-produced groups on top of existing ones.

Step 4: Configure your rules

You can configure rules via the Admin UI or OCC commands.

Via OCC commands (quick setup)

php occ oidc-groups:set '{
  "version": 1,
  "mode": "additive",
  "rules": [
    {
      "id": "departments",
      "type": "direct",
      "enabled": true,
      "claimPath": "department",
      "config": {}
    },
    {
      "id": "user-roles",
      "type": "prefix",
      "enabled": true,
      "claimPath": "roles",
      "config": { "prefix": "role_" }
    },
    {
      "id": "org-mapping",
      "type": "map",
      "enabled": true,
      "claimPath": "organization",
      "config": {
        "values": {
          "corp.example.com": "Staff",
          "partner.example.com": "Partners"
        },
        "unmappedPolicy": "ignore"
      }
    },
    {
      "id": "internal-flag",
      "type": "conditional",
      "enabled": true,
      "claimPath": "userType",
      "config": {
        "operator": "equals",
        "value": "INTERNAL",
        "groups": ["Internal-Users"]
      }
    }
  ]
}'

Via Admin UI

Navigate to Administration → OIDC Groups Mapping in your Nextcloud admin panel. The UI has 3 tabs:

• Visual Editor — add, edit, reorder, enable/disable, and delete rules
• JSON — raw JSON editor for bulk editing or copy-pasting configurations
• Simulator — paste a sample JWT token and preview which groups each rule produces

Step 5: Test with the Simulator

Before putting rules into production, test them against a sample token.

Via OCC

php occ oidc-groups:test --token '{
  "department": "Engineering",
  "roles": ["admin", "editor"],
  "organization": "corp.example.com",
  "userType": "INTERNAL"
}'

You can also test the merge behavior by passing existing groups:

php occ oidc-groups:test \
  --token '{"department":"Engineering","roles":["admin","editor"],"organization":"corp.example.com","userType":"INTERNAL"}' \
  --existing '["users"]'

Via the Admin UI Simulator

1. Go to Administration → OIDC Groups Mapping
2. Click the Simulator tab
3. Paste your sample token JSON
4. See exactly which groups each rule produces

Step 6: Verify in production

After configuring your rules:

1. Have a test user log in via OIDC
2. Check their group memberships in Users → [user] → Groups
3. Check Nextcloud logs for any oidc_groups_mapping messages

Complete example

Given this token:

{
  "department": "Engineering",
  "roles": ["admin", "editor"],
  "organization": "corp.example.com",
  "userType": "INTERNAL"
}

And the 4 rules from Step 4, the expected output is:

Rule	Claim	Output groups
departments (direct)	department = "Engineering"	Engineering
user-roles (prefix)	roles = ["admin", "editor"]	role_admin, role_editor
org-mapping (map)	organization = "corp.example.com"	Staff
internal-flag (conditional)	userType = "INTERNAL"	Internal-Users

Final group list (additive mode): Engineering, role_admin, role_editor, Staff, Internal-Users

If the user already had groups from user_oidc's mappingGroups (e.g., ["users"]), they would keep those too: users, Engineering, role_admin, role_editor, Staff, Internal-Users.