JFrog OIDC Management via PRM

Manage JFrog Artifactory project OIDC configurations using PRM (Platform Resource Manager) and hcpctl. This skill helps any team configure GitHub repositories to use OIDC authentication with JFrog Artifactory.

When to Use This Skill

• GitHub Actions fail with: OIDC authentication failed because this repository is not associated with an Artifactory Project
• Onboarding a new repo to use uhg-pipelines/epl-jf/saas-setup@v5
• Auditing which repos are authorized for a JFrog project
• Debugging 401 errors during npm install, pip install, or docker pull in CI

Required Team Information

Before using this skill, you need to know your team's values:

Parameter	Description	How to Find
AIDE_ID	Your team's ASK ID (e.g., AIDE_0012345)	Check your team's HCP account or ask your Producer
Project Key	JFrog project identifier (e.g., myteam-proj)	Usually <team>-<app> format, visible in JFrog UI
Resource Group	PRM namespace for your resources	Run discovery command below
GitHub Org	Where your repos live (e.g., OptumInsight-Platform)	Your GitHub organization

Prerequisites

1. Install hcpctl

# GitHub.com (GHEC) - for OptumInsight-Platform and similar orgs
brew tap optum-eeps/prm-homebrew https://github.com/optum-eeps/prm-homebrew.git
brew install hcpctl

# GitHub Enterprise (github.optum.com)
brew tap prm/homebrew https://github.optum.com/prm/homebrew.git
# These environment variables must be set before you can brew install
export HOMEBREW_ARTIFACTORY_USER=<email used to generate token>
export HOMEBREW_ARTIFACTORY_TOKEN=<generated token>
# The token must be generated from https://centraluhg.jfrog.io/ui/

brew install hcpctl

2. Configure and Login

# Create production context (one-time setup)
hcpctl context create --uri https://prm.optum.com prm-prod

# Use the context
hcpctl context use prm-prod

# Login via Azure AD (opens browser, use your corporate credentials)
hcpctl login

# Alternative: device code flow if browser doesn't work
hcpctl login -m azure-device-code

Note: Sessions expire after ~8 hours. If commands fail with auth errors, run hcpctl login again.

3. Verify Login

hcpctl context --current
hcpctl env

Discovering Your Project

Find Your Artifactory Project by Project Key

# Replace YOUR_PROJECT_KEY with your JFrog project key
hcpctl ls artifactory.project.v1 -a /spec/projectKey='YOUR_PROJECT_KEY'

Example output:

Name         Id                                                                    State Age  PendingRuntimeAction
----         --                                                                    ----- ---  --------------------
aide-0012345 myteam-resource-grp-abc123/artifactory.project.v1/aide-0012345        Ready 180d -

The Id column contains your full Resource ID in format: <resource-group>/artifactory.project.v1/<aide-id>

Find Project by AIDE_ID

If you know your AIDE_ID but not the project key:

hcpctl ls artifactory.project.v1 --id aide-0012345

List All Artifactory Projects You Can Access

hcpctl ls artifactory.project.v1

If this returns no results: You may not have RBAC access to any Artifactory projects. Contact your Producer or team lead to get access granted, or ask them for the Resource ID directly.

Common Commands

In the examples below, replace <RESOURCE_ID> with your full resource ID (e.g., myteam-resource-grp-abc123/artifactory.project.v1/aide-0012345).

View Full Project Configuration

hcpctl cat -o yaml <RESOURCE_ID>

List Authorized GitHub Repositories

hcpctl cat -o yaml <RESOURCE_ID> | grep -A 20 "githubRepositories:"

Check Project Status

For the top-level status only (avoids nested component statuses):

hcpctl cat -o yaml <RESOURCE_ID> | grep -E "^status:" -A1

View Virtual Repositories (NPM, PyPI, Docker, etc.)

Useful for debugging registry URL mismatches:

hcpctl cat -o yaml <RESOURCE_ID> | grep -E "npm|pypi|docker|vir" | head -20

Key insight: OIDC tokens are scoped to project-specific repos (e.g., myteam-npm-vir), NOT global repos like glb-npm-vir. If your lockfile has hardcoded URLs to glb-npm-vir, you'll get 401 errors.

View Full Project Spec

Shows technologies, service account, and authorized repos:

hcpctl cat -o yaml <RESOURCE_ID> | grep -A30 "spec:" | head -40

Adding a New Repository to the Allowlist

Step 1: Export Current Configuration

# Replace <RESOURCE_ID> with your full resource ID
hcpctl cat -o yaml <RESOURCE_ID> > /tmp/project-config.yaml

Step 2: Edit the YAML

Add your repository to the spec.githubRepositories list. Edit /tmp/project-config.yaml:

spec:
  projectKey: your-project-key
  # ... other fields ...
  githubRepositories:
    - YourOrg/existing-repo-1
    - YourOrg/existing-repo-2
    - YourOrg/your-new-repo  # <-- Add your new repo here

Step 3: Apply the Change

hcpctl apply -f /tmp/project-config.yaml

Step 4: Monitor Progress

The update typically takes 10-50 minutes to complete. Monitor with:

# Check overall status (top-level only)
hcpctl cat -o yaml <RESOURCE_ID> | grep -E "^status:" -A1

# Check pending actions
hcpctl cat -o yaml <RESOURCE_ID> | grep -A 10 "pendingAction:"

When status.ready: true, the update is complete.

Step 5: Verify Your Repo Was Added

hcpctl cat -o yaml <RESOURCE_ID> | grep "your-new-repo"

If it appears in the output, your repo is now authorized for OIDC authentication.

Using OIDC in GitHub Workflows

Once your repo is added to the allowlist, use this pattern in your workflows:

permissions:
  id-token: write  # Required for OIDC token generation

jobs:
  build:
    runs-on: uhg-runner
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup JFrog OIDC
        id: setup-jfrog-saas
        uses: uhg-pipelines/epl-jf/saas-setup@v5
        with:
          jfrog-project-key: YOUR_PROJECT_KEY  # Replace with your project key
          npm-setup: true      # For npm/yarn
          yarn-setup: true     # For yarn specifically
          pip-setup: true      # For Python/pip
          apt-setup: false     # For apt packages
          # Other options: terraform-setup, go-setup, maven-settings-setup

Important: Reusable Workflow Permissions

When calling reusable workflows (using uses: ./.github/workflows/...), permissions are NOT inherited automatically. Each job calling a reusable workflow needs explicit permissions:

jobs:
  build:
    permissions:
      contents: read
      id-token: write  # Must be explicit for OIDC to work
    uses: ./.github/workflows/build.yml

NPM/Yarn Lockfile Considerations

OIDC tokens are scoped to your project-specific virtual repo (e.g., yourproject-npm-vir), not the global registry (glb-npm-vir).

If your yarn.lock or package-lock.json has URLs pointing to glb-npm-vir:

• Option 1: Delete lockfile in CI and regenerate (simplest)

  - name: Install dependencies
    run: |
      rm -f yarn.lock  # Regenerate with OIDC-compatible registry
      yarn install
  

• Option 2: Regenerate lockfile locally with proper registry (requires matching auth)

Docker Registry Login

- name: Login to Artifactory Docker registry
  uses: docker/login-action@v4
  with:
    registry: https://centraluhg.jfrog.io
    username: ${{ steps.setup-jfrog-saas.outputs.oidc-subject }}
    password: ${{ steps.setup-jfrog-saas.outputs.access-token }}

Troubleshooting

"config file not found" Error

# Create the context first
hcpctl context create --uri https://prm.optum.com prm-prod
hcpctl context use prm-prod
hcpctl login

"OIDC authentication failed" in GitHub Actions

1. Verify your repo is in the allowlist:

   hcpctl cat -o yaml <RESOURCE_ID> | grep "your-repo-name"
   

2. Check if there's a pending update:

   hcpctl cat -o yaml <RESOURCE_ID> | grep -E "^status:" -A1
   

3. Ensure workflow has id-token: write permission — check both top-level and job-level permissions

4. For reusable workflows, add explicit permissions to the calling job (not just the reusable workflow file)

401 Unauthorized During npm/yarn/pip Install

1. Check which registry the lockfile points to:

   grep "resolved.*glb-npm-vir" yarn.lock | head -3
   

2. If it points to glb-npm-vir, the OIDC token won't work — see "NPM/Yarn Lockfile Considerations" above

3. Verify your project's virtual repos:

   hcpctl cat -o yaml <RESOURCE_ID> | grep -E "virtual_repos:" -A10
   

Permission Denied on hcpctl

Contact PRM support or your Producer team. RBAC permissions may need to be granted.

Artifactory URLs Reference

URL	Purpose
https://centraluhg.jfrog.io	Central Artifactory (publishing, some reads)
https://edgeinternal1uhg.optum.com	Edge Artifactory (faster reads, used by CI)

Related Resources

• EPL JFrog Action - saas-setup action source
• EPL Privileged Workflows - Reusable workflow patterns
• EPL Documentation - Full EPL docs
• PRM Documentation - hcpctl setup guide

Support

• Teams: Enterprise Pipelines Support Channel
• ServiceNow: Group EPL_SUPPORT
• Hive: Tag with "Enterprise Pipelines"