OpenMetadata Operations

Guide for administering OpenMetadata platform: users, teams, bots, roles, policies, security configuration, and operational tasks.

When to Use This Skill

• Managing users and team hierarchies
• Creating and configuring bots (service accounts)
• Setting up roles and policies (RBAC/ABAC)
• Configuring SSO and authentication providers
• Managing JWT tokens and API access
• Troubleshooting authentication and authorization issues

This Skill Does NOT Cover

• Building OpenMetadata SDKs (see

  openmetadata-sdk-dev

  )
• Using SDKs/APIs to build integrations (see

  openmetadata-dev

  )
• Deploying OpenMetadata infrastructure (Kubernetes, Docker)
• Database administration for OpenMetadata backend

Team Hierarchy

Team Types

OpenMetadata uses a hierarchical team structure:

Organization (root)
├── Business Unit
│   ├── Division
│   │   ├── Department
│   │   │   └── Group ← Only Groups can own Data Assets
│   │   └── Group
│   └── Department
│       └── Group
└── Business Unit
    └── Group

Create Team

Via UI:

1. Navigate to Settings → Teams
2. Click Add Team
3. Select team type (BusinessUnit, Division, Department, Group)
4. Set parent team
5. Add team name, display name, description

Via API:

curl -X PUT "http://localhost:8585/api/v1/teams" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-engineering",
    "displayName": "Data Engineering",
    "description": "Data platform team",
    "teamType": "Group",
    "parents": [{"id": "parent-team-uuid", "type": "team"}]
  }'

Team Policies

Assign policies to teams for inherited permissions:

curl -X PATCH "http://localhost:8585/api/v1/teams/${TEAM_ID}" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json-patch+json" \
  -d '[
    {
      "op": "add",
      "path": "/policies/-",
      "value": {"id": "policy-uuid", "type": "policy"}
    }
  ]'

User Management

Add User

Via UI:

1. Navigate to Settings → Users
2. Click Add User
3. Enter email, name, select teams
4. Assign roles

Via API:

curl -X PUT "http://localhost:8585/api/v1/users" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "john.doe",
    "email": "john.doe@company.com",
    "displayName": "John Doe",
    "teams": [{"id": "team-uuid", "type": "team"}],
    "roles": [{"id": "role-uuid", "type": "role"}]
  }'

Assign Role to User

curl -X PATCH "http://localhost:8585/api/v1/users/${USER_ID}" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json-patch+json" \
  -d '[
    {
      "op": "add",
      "path": "/roles/-",
      "value": {"id": "data-steward-role-uuid", "type": "role"}
    }
  ]'

Generate User Access Token

Users can generate personal access tokens:

1. Go to Profile → Access Token
2. Click Generate New Token
3. Set expiration (optional)
4. Copy token immediately (shown only once)

Bots (Service Accounts)

What Are Bots?

Bots are service accounts for automated processes:

• Ingestion pipelines
• External integrations
• Scheduled jobs
• CI/CD automation

Built-in Bots

ingestion-bot

automator-bot

Create Custom Bot

Via UI:

1. Navigate to Settings → Integrations → Bots
2. Click Add Bot
3. Enter bot name and description
4. Select or create role
5. Copy generated JWT token

Via API:

# Create bot
curl -X PUT "http://localhost:8585/api/v1/bots" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-cd-bot",
    "displayName": "CI/CD Bot",
    "description": "Bot for CI/CD pipeline metadata updates",
    "botUser": {
      "name": "ci-cd-bot",
      "email": "ci-cd-bot@openmetadata.org",
      "isBot": true
    }
  }'

Get Bot JWT Token

Via UI:

1. Navigate to Settings → Integrations → Bots
2. Select the bot
3. Click Revoke & Regenerate Token or view existing token

Via API:

# Get bot details including auth mechanism
curl "http://localhost:8585/api/v1/bots/name/ingestion-bot?fields=botUser" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"

Bot Token Validation

Validate bot tokens at jwt.io or programmatically:

import jwt

def validate_bot_token(token: str, public_key: str) -> dict:
    """Validate and decode bot JWT token."""
    try:
        payload = jwt.decode(
            token,
            public_key,
            algorithms=["RS256"],
            issuer="open-metadata.org",
        )
        assert payload.get("isBot") == True
        return payload
    except jwt.ExpiredSignatureError:
        raise ValueError("Token expired - regenerate in UI")
    except jwt.InvalidTokenError as e:
        raise ValueError(f"Invalid token: {e}")

Bot Token Rotation

Rotate bot tokens periodically:

1. Navigate to Settings → Integrations → Bots
2. Select the bot
3. Click Revoke & Regenerate Token
4. Update all systems using the old token
5. Verify ingestion pipelines are working

Roles and Policies

Access Control Model

OpenMetadata uses hybrid RBAC + ABAC:

Authorization Decision = f(User, Resource, Operation)

Where:
- User    = Identity + Roles + Teams
- Resource = Entity Type + Attributes (owner, domain, tags)
- Operation = Create, Edit, Delete, ViewAll, EditOwner, etc.

Built-in Roles

Create Custom Role

Via UI:

1. Navigate to Settings → Roles
2. Click Add Role
3. Enter name and description
4. Add policies to the role

Via API:

curl -X PUT "http://localhost:8585/api/v1/roles" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DataEngineer",
    "displayName": "Data Engineer",
    "description": "Role for data engineering team",
    "policies": [
      {"id": "policy-uuid-1", "type": "policy"},
      {"id": "policy-uuid-2", "type": "policy"}
    ]
  }'

Policy Structure

Policies contain rules that define permissions:

{
  "name": "TableEditPolicy",
  "rules": [
    {
      "name": "AllowEditTables",
      "resources": ["table"],
      "operations": ["Create", "Edit", "Delete"],
      "effect": "allow",
      "condition": "isOwner()"
    }
  ]
}

Common Policy Rules

isOwner()

inTeam('team-name')

hasDomain('domain')

hasTag('tag-fqn')

Create Policy

curl -X PUT "http://localhost:8585/api/v1/policies" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TeamOwnershipPolicy",
    "displayName": "Team Ownership Policy",
    "description": "Allow team members to edit owned resources",
    "rules": [
      {
        "name": "EditOwnedResources",
        "resources": ["table", "dashboard", "pipeline"],
        "operations": ["Edit", "EditDescription", "EditTags"],
        "effect": "allow",
        "condition": "isOwner()"
      }
    ]
  }'

Operations Reference

Create

Delete

ViewAll

ViewBasic

Edit

EditDescription

EditTags

EditOwner

EditLineage

EditCustomFields

Authentication Configuration

Supported Providers

Note: OpenMetadata does not support multiple auth providers simultaneously.

Configure SSO (Example: Okta)

1. Create Okta Application:

• Sign in to Okta Admin Console
• Navigate to Applications → Create App Integration
• Select OIDC - OpenID Connect and Web Application
• Set redirect URI:

  http://localhost:8585/callback

2. Configure OpenMetadata:

# openmetadata.yaml
authenticationConfiguration:
  provider: okta
  publicKeyUrls:
    - https://your-domain.okta.com/oauth2/default/v1/keys
  authority: https://your-domain.okta.com/oauth2/default
  clientId: <your-client-id>
  callbackUrl: http://localhost:8585/callback

3. Configure Frontend:

# openmetadata.yaml (continued)
authorizerConfiguration:
  className: org.openmetadata.service.security.DefaultAuthorizer
  containerRequestFilter: org.openmetadata.service.security.JwtFilter
  adminPrincipals:
    - admin@company.com
  principalDomain: company.com

LDAP/Active Directory

For LDAP integration, use an OIDC proxy like Keycloak:

1. Deploy Keycloak
2. Configure LDAP User Federation in Keycloak
3. Configure OpenMetadata to use Keycloak as OIDC provider

Custom Properties Administration

Create Custom Property Type

Via UI:

1. Navigate to Settings → Custom Properties
2. Select entity type (Table, Dashboard, etc.)
3. Click Add Property
4. Configure name, type, description

Via API:

curl -X PUT "http://localhost:8585/api/v1/metadata/types/name/table/customProperties" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dataClassification",
    "description": "Data classification level",
    "propertyType": {
      "id": "enum-type-uuid",
      "type": "type"
    },
    "customPropertyConfig": {
      "config": {
        "values": ["Public", "Internal", "Confidential", "Restricted"]
      }
    }
  }'

List Custom Properties

curl "http://localhost:8585/api/v1/metadata/types/name/table?fields=customProperties" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"

Troubleshooting

Authentication Issues

Problem: 401 Unauthorized

1. Check JWT token validity:

   # Decode token at jwt.io or:
   echo $JWT_TOKEN | cut -d. -f2 | base64 -d | jq .
   

2. Verify token expiration (

   exp

   claim)

3. Check issuer matches configuration

Problem: Bot ingestion failing

1. Verify bot has

   Ingestion Bot Role

   :

   curl "http://localhost:8585/api/v1/bots/name/ingestion-bot?fields=botUser" \
     -H "Authorization: Bearer ${ADMIN_TOKEN}"
   

2. Check role policies weren't modified

3. Regenerate bot token if expired

Authorization Issues

Problem: 403 Forbidden

1. Check user's roles:

   curl "http://localhost:8585/api/v1/users/name/john.doe?fields=roles,teams" \
     -H "Authorization: Bearer ${ADMIN_TOKEN}"
   

2. Verify role has required policy

3. Check policy conditions (isOwner, inTeam, etc.)

Problem: User can't see entities

1. Verify

   ViewBasic

   or

   ViewAll

   permission
2. Check team hierarchy - user must be in a Group
3. Verify entity isn't soft-deleted

Common Fixes

Operational Tasks

Backup Considerations

Critical data to back up:

• Database (MySQL/PostgreSQL)
• Elasticsearch indices
• JWT signing keys
• Configuration files

Audit Logging

OpenMetadata tracks changes via:

• Entity version history
• Change events in Elasticsearch
• API audit logs

Query audit events:

curl "http://localhost:8585/api/v1/events?entityType=table&timestamp=1704067200000" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"

Health Checks

# API health
curl "http://localhost:8585/api/v1/system/health"

# Elasticsearch health
curl "http://localhost:8585/api/v1/search/health"

Best Practices

Security

1. Never use built-in auth in production - always configure SSO
2. Rotate bot tokens periodically (every 90 days recommended)
3. Use least-privilege roles - create specific policies per team
4. Audit admin access regularly

Team Structure

1. Use Groups for ownership - only Groups can own assets
2. Mirror org structure - Business Unit → Division → Department → Group
3. Assign domain owners - use domains for cross-team governance

Bot Management

1. Create purpose-specific bots - don't reuse ingestion-bot
2. Document bot purposes in descriptions
3. Monitor bot token usage in audit logs
4. Disable unused bots rather than deleting

References

• OpenMetadata Security Guide
• Roles and Policies
• Team Management
• SSO Configuration

• openmetadata-dev

  - Using SDKs/APIs for integrations

• openmetadata-sdk-dev

  - Implementing SDKs for new languages