Jfrog Oidc Setup

JFrog OIDC Setup

Prefer jf api per ../../../platform-features/skills/jfrog-cli/jf-api-patterns.md for JFrog REST calls; curl in examples is fallback when the CLI is unavailable.

Configures OpenID Connect (OIDC) integration between GitHub Actions and JFrog Platform, enabling secretless authentication for CI workflows.

Overview

OIDC allows GitHub Actions workflows to authenticate with JFrog without storing long-lived secrets. GitHub issues short-lived tokens that JFrog validates and exchanges for access.

GitHub Actions  -->  GitHub OIDC Provider  -->  JFrog Platform
     |                      |                        |
     | 1. Request token     |                        |
     |--------------------->|                        |
     |                      |                        |
     | 2. JWT token         |                        |
     |<---------------------|                        |
     |                      |                        |
     | 3. Present JWT       |                        |
     |---------------------------------------------->|
     |                      |                        |
     |                      |    4. Validate & grant |
     |<----------------------------------------------|

Inputs

• project_key -- JFrog project key
• github_repos -- list of owner/repo (e.g., ["myorg/my-app", "myorg/my-lib"])
• github_host -- GitHub host (e.g., github.com or github.mycompany.com)
• OIDC_SETUP -- boolean from manifest github.oidc_setup key (user's preference)
• OIDC_AVAILABLE -- boolean from prerequisite subscription check

Step 0: Check OIDC Setup Preference and Availability

First, check the user's preference from the manifest (OIDC_SETUP). Then verify platform support (OIDC_AVAILABLE).

If OIDC_SETUP is false: skip the entire skill regardless of subscription and return:

• oidc_provider_name = empty string
• Log: INFO: OIDC setup is disabled in manifest (github.oidc_setup: false). CI workflows will use secrets-based authentication.

If OIDC_SETUP is true AND OIDC_AVAILABLE is false: ABORT immediately and return an error:

• Log: ABORT: OIDC was requested (github.oidc_setup: true) but the JFrog subscription does not support it. Upgrade to Enterprise X or Enterprise+, or set github.oidc_setup: false.
• Do not proceed with any OIDC configuration. This is a hard stop.

If OIDC_SETUP is true AND OIDC_AVAILABLE is true: proceed with the steps below.

Decision Matrix

Subscription Check (if not already done)

jf api /artifactory/api/system/license >/tmp/oidc-license.json 2>/tmp/oidc-license.code
SUBSCRIPTION_TYPE=$(jq -r '.subscriptionType' /tmp/oidc-license.json)

if [[ "$SUBSCRIPTION_TYPE" == enterprise_xray* ]] || [[ "$SUBSCRIPTION_TYPE" == enterprise_plus* ]]; then
  OIDC_AVAILABLE=true
  echo "OK: OIDC is available (subscription: $SUBSCRIPTION_TYPE)"
else
  OIDC_AVAILABLE=false
fi

# Enforce manifest preference
if [ "$OIDC_SETUP" = "false" ]; then
  echo "INFO: OIDC setup is disabled in manifest (github.oidc_setup: false). Skipping."
  exit 0
fi

if [ "$OIDC_AVAILABLE" = "false" ]; then
  echo "ABORT: OIDC was requested (github.oidc_setup: true) but the JFrog subscription"
  echo "       ($SUBSCRIPTION_TYPE) does not support OIDC."
  echo ""
  echo "To fix this, either:"
  echo "  1. Upgrade to an Enterprise X or Enterprise+ subscription, OR"
  echo "  2. Set 'github.oidc_setup: false' in the manifest to use secrets-based auth."
  exit 1
fi

Step 1: Determine GitHub Type

Based on github_host from the manifest:

if [ "$GITHUB_HOST" = "github.com" ]; then
  ISSUER_URL="https://token.actions.githubusercontent.com"
  PROVIDER_TYPE="GitHub"
else
  ISSUER_URL="https://${GITHUB_HOST}/_services/token"
  PROVIDER_TYPE="Generic"  # Use Generic for GHE to avoid org validation errors
fi

Important: Use provider_type: "GitHub" only for public GitHub (github.com). For GitHub Enterprise, use "Generic" to avoid organization validation errors where the JFrog platform cannot reach the GHE host.

Step 2: Check for Existing OIDC Provider or Create One

Check existing providers (run with required_permissions: ["full_network"])

jf api /access/api/v1/oidc >/tmp/oidc-providers.json 2>/tmp/oidc-providers.code
PROVIDERS=$(cat /tmp/oidc-providers.json)

# Check if a provider with the correct issuer_url already exists
EXISTING_PROVIDER=$(echo "$PROVIDERS" | jq -r --arg url "$ISSUER_URL" \
  '.[] | select(.issuer_url == $url) | .name')

if [ -n "$EXISTING_PROVIDER" ]; then
  echo "Reusing existing OIDC provider: ${EXISTING_PROVIDER}"
  PROVIDER_NAME="$EXISTING_PROVIDER"
else
  echo "No matching provider found. Creating one..."
fi

Create provider if needed (run with required_permissions: ["full_network"])

# Choose a provider name
if [ "$PROVIDER_TYPE" = "GitHub" ]; then
  PROVIDER_NAME="github-oidc"
else
  PROVIDER_NAME="github-enterprise-oidc"
fi

jf api /access/api/v1/oidc -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "'"$PROVIDER_NAME"'",
    "issuer_url": "'"$ISSUER_URL"'",
    "provider_type": "'"$PROVIDER_TYPE"'"
  }'

API notes:

• issuer_url must be a top-level field (not nested inside a configuration object)
• 409 = provider already exists -- treat as success

Step 3: Create Identity Mappings for Each Repository

For each repo in github_repos, check if an identity mapping already exists and create one if needed.

Check existing mappings (run with required_permissions: ["full_network"])

jf api "/access/api/v1/oidc/${PROVIDER_NAME}/identity_mappings" >/tmp/oidc-mappings.json 2>/dev/null
MAPPINGS=$(cat /tmp/oidc-mappings.json)

REPO="owner/repo"  # from github_repos[]

# Check if an existing mapping already covers the repo
EXISTING_MAPPING=$(echo "$MAPPINGS" | jq -r --arg repo "$REPO" \
  '.[] | select(.claims.repository == $repo) | .name')

Create mapping for main branch (deploy access)

If no existing mapping covers the repo:

# Sanitize repo name for mapping name (replace / with -)
MAPPING_NAME=$(echo "$REPO" | tr '/' '-')

jf api /access/api/v1/oidc/${PROVIDER_NAME}/identity_mappings -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "'"${MAPPING_NAME}-main"'",
    "project": "'"${PROJECT_KEY}"'",
    "priority": 100,
    "claims": {
      "repository": "'"$REPO"'",
      "ref": "refs/heads/main"
    },
    "token_spec": {
      "scope": "applied-permissions/roles:'"${PROJECT_KEY}"':Developer",
      "expires_in": 300
    }
  }'

Create mapping for PRs (read-only access)

jf api /access/api/v1/oidc/${PROVIDER_NAME}/identity_mappings -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "'"${MAPPING_NAME}-pr"'",
    "project": "'"${PROJECT_KEY}"'",
    "priority": 90,
    "claims": {
      "repository": "'"$REPO"'"
    },
    "token_spec": {
      "scope": "applied-permissions/roles:'"${PROJECT_KEY}"':Developer",
      "expires_in": 300
    }
  }'

Important notes:

• The scope must include the project key: applied-permissions/roles:{PROJECT_KEY}:Developer (not just applied-permissions/roles:Developer, which returns "token_spec Invalid scope")
• Higher priority mappings are evaluated first -- main branch (100) matches before general repo (90)
• 409 = mapping already exists -- treat as success

Step 4: Report Results

After processing all repos, return:

• oidc_provider_name -- the provider name (e.g., github-oidc) for use in CI workflows
• Summary of identity mappings created or reused

Inform the user:

OIDC has been configured. The CI workflow skill will use oidc-provider-name: {provider_name} in the setup-jfrog-cli action.

Error Handling

• 409 Conflict: Provider or mapping already exists -- treat as success
• 400 Bad Request: Check the request body format, especially issuer_url placement
• "oidc_setting Organization is not valid": Use provider_type: "Generic" for GitHub Enterprise
• "token_spec Invalid scope": Ensure scope includes the project key in the role path

GitHub Token Claims Reference

GitHub OIDC tokens include claims that identify the source:

Permission Scopes

Troubleshooting

Debug: View GitHub Token Claims

Add this step to a workflow to inspect the claims:

- name: Debug OIDC token
  run: |
    TOKEN=$(curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
      "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=jfrog" | jq -r '.value')
    echo "Token claims:"
    echo $TOKEN | cut -d'.' -f2 | base64 -d 2>/dev/null | jq .