---
name: osdu-preshipping-setup
description: Provision users and service principals for OSDU/ADME preshipping environments. Use when setting up preshipping access, enabling preshipping for users or OIDs, bulk-provisioning for preshipping testing, or configuring pre-production OSDU environments.
---

# OSDU Preshipping Setup

Bulk provisioning for OSDU/ADME preshipping environments. Adds users or service principals to all required entitlement groups for preshipping testing.

## Prerequisites

Verify environment variables are set:

```bash
echo "ADME_HOST: ${ADME_HOST:-NOT SET}"
echo "ADME_DATA_PARTITION: ${ADME_DATA_PARTITION:-NOT SET}"
echo "ADME_CLIENT: ${ADME_CLIENT:-NOT SET}"
echo "ADME_SECRET: ${ADME_SECRET:+SET}"
echo "ADME_TENANT_ID: ${ADME_TENANT_ID:-NOT SET}"
```

Test configuration:

```bash
uv run ${CLAUDE_PLUGIN_ROOT}/skills/osdu-preshipping/scripts/preshipping.py check
```

## Quick Reference

### Add User to Preshipping

```bash
# Add user to all preshipping groups
uv run ${CLAUDE_PLUGIN_ROOT}/skills/osdu-preshipping/scripts/preshipping.py add --user "user@example.com"

# Add service principal by OID
uv run ${CLAUDE_PLUGIN_ROOT}/skills/osdu-preshipping/scripts/preshipping.py add --oid "32e97796-eabc-4b0b-b1fb-3a65c71a0d09"

# Add multiple OIDs
uv run ${CLAUDE_PLUGIN_ROOT}/skills/osdu-preshipping/scripts/preshipping.py add \
  --oid "32e97796-eabc-4b0b-b1fb-3a65c71a0d09" \
  --oid "f15486aa-d6f8-470c-86fa-f4b437d5f0d9"

# Preview without making changes
uv run ${CLAUDE_PLUGIN_ROOT}/skills/osdu-preshipping/scripts/preshipping.py add --user "user@example.com" --dry-run
```

### Remove User from Preshipping

```bash
# Remove user from all preshipping groups
uv run ${CLAUDE_PLUGIN_ROOT}/skills/osdu-preshipping/scripts/preshipping.py remove --user "user@example.com"

# Remove service principal by OID
uv run ${CLAUDE_PLUGIN_ROOT}/skills/osdu-preshipping/scripts/preshipping.py remove --oid "32e97796-eabc-4b0b-b1fb-3a65c71a0d09"

# Preview without making changes
uv run ${CLAUDE_PLUGIN_ROOT}/skills/osdu-preshipping/scripts/preshipping.py remove --user "user@example.com" --dry-run
```

### View Configuration

```bash
# List all preshipping groups
uv run ${CLAUDE_PLUGIN_ROOT}/skills/osdu-preshipping/scripts/preshipping.py list-groups

# Check connectivity and auth
uv run ${CLAUDE_PLUGIN_ROOT}/skills/osdu-preshipping/scripts/preshipping.py check
```

## What Gets Provisioned

When you add a user/OID to preshipping, they are added as **OWNER** to all groups defined in the preshipping configuration. This includes:

| Category | Groups |
|----------|--------|
| Data Lake | `users@`, `users.datalake.ops@`, `users.datalake.admin@` |
| SDMS | `service.edsdms.user@`, `data.sdms.*` |
| Seismic | `seismic.default.*`, `seistore.system.admin@` |
| Secrets | `service.secret.admin@`, `service.secret.viewer@`, `service.secret.editor@` |
| Search | `service.search.admin@`, `service.search.user@` |
| Wellbore | `data.wellbore.owner@` |
| Reservoir | `service.reservoir-dms.*` |
| Delivery | `service.delivery.viewer@` |

For the complete list, see [reference/groups.md](reference/groups.md) or run `list-groups`.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ADME_HOST` | Yes | ADME instance hostname |
| `ADME_DATA_PARTITION` | Yes | Data partition ID (e.g., `opendes`) |
| `ADME_CLIENT` | Yes | App registration client ID |
| `ADME_SECRET` | Yes | App registration secret |
| `ADME_TENANT_ID` | Yes | Azure AD tenant ID |
| `ADME_DOMAIN` | No | Entitlements domain (default from config) |

## Output Formats

| Format | Flag | Use Case |
|--------|------|----------|
| Table | (default) | Human readable with colors |
| JSON | `--json` | Automation and processing |

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| 401 Unauthorized | Invalid/expired token | Check ADME_SECRET |
| 403 Forbidden | Missing permissions | Verify app has entitlements API access |
| 409 Conflict | Already in group | Not an error, skipped |
| Missing env vars | Not configured | Set required ADME_* variables |

## Reference Files

- [reference/groups.md](reference/groups.md) - Complete group list with descriptions
- [scripts/preshipping.py](scripts/preshipping.py) - Provisioning script