Authenticate via the JFrog CLI

This procedure explains how to authenticate to the JFrog Platform using the JFrog CLI command-line tool. Authentication is required to securely access JFrog services, including Artifactory, Xray, Distribution, and other components.

When working with JFrog Platform, you have multiple authentication options. Each method allows you to secure access to your JFrog service instance and interact with the API effectively.

This topic covers the following authentication methods:

• Authenticate with Username and Password
• Authenticate with an Access Token
• Browser Login (Interactive)
• OIDC Token Exchange
• Environment Variable Authentication

Authentication Methods Overview

Which Method Should I Use?

Prerequisites

Before proceeding with authentication using JFrog CLI, ensure that you meet the following prerequisites.

• JFrog CLI Installed: Make sure that you have the JFrog CLI installed on your system.
• JFrog Account: An active JFrog account with appropriate permissions to access the service. Ensure you have the necessary login credentials (username and password) or an access token.
• Token Validity (if using access tokens): If you choose to authenticate with an access token, ensure that it is a valid JFrog access token and has not expired. Review your token's scope and permissions to confirm it grants the required access.

Authentication using CLI

When using JFrog CLI, authentication is mandatory for accessing JFrog Platform services. You can authenticate using either a username and password or an access token. Below are detailed instructions for both methods.

Authenticating with Username and Password

To authenticate using your JFrog login credentials, you can configure your credentials permanently using the jf c add command. Alternatively, you can provide your credentials dynamically for each command.

Configure Once Using jf c add

To configure authentication with your username and password:

1. Run the following command:

   Bash

   jf c add

2. Follow the prompts to enter the necessary information:

   • Choose a server ID: Your chosen name for this configuration (for example, my_server).
   • JFrog Platform URL: The base URL for your JFrog instance (for example, https://yourjfroginstance.jfrog.io)
   • JFrog username: Your username.
   • JFrog password: Your password.

Using Command Options

For each command, you can specify the following options:

Example Command (Artifactory ping):

jf rt ping --url "https://yourjfroginstance.jfrog.io/artifactory" --user "your_username" --password "your_password"

Example Command (Config Add with credentials):

jf c add my_server --url "https://yourjfroginstance.jfrog.io" --user "your_username" --password "your_password"

Placeholders:

• <platform_url>: JFrog Platform URL (for example, https://yourcompany.jfrog.io/artifactory)
• <username>: Your JFrog username
• <password>: Your JFrog password

Authenticating with an Access Token

To authenticate using a JFrog Access Token, similar to username/password authentication, you can configure your access token using the jf c add command, or you can include it directly with each command.

Configure Once Using jf c add

To configure authentication with an access token:

1. Run the following command:

   Bash

   jf c add

2. When prompted, enter your access token instead of a password.

Using Command Options

You can specify the following options for authentication:

Example Command (Artifactory ping):

jf rt ping --url "https://yourjfroginstance.jfrog.io/artifactory" --access-token "your_access_token"

Example Command (Config add with access token):

jf c add my_server --url "https://yourjfroginstance.jfrog.io" --access-token "your_access_token"

Additional Configuration Options

The jf c add command supports additional flags for advanced configuration:

Example with service-specific URLs:

jf c add my_server \
  --url "https://yourjfroginstance.jfrog.io" \
  --artifactory-url "https://yourjfroginstance.jfrog.io/artifactory" \
  --xray-url "https://yourjfroginstance.jfrog.io/xray" \
  --user "your_username" \
  --password "your_password"

Using a Configured Server

Once you have configured a server using jf c add, you can reference it in subsequent commands using the --server-id flag:

jf rt ping --server-id my_server

To set a configured server as the default, use:

jf c use my_server

To view your configured servers:

jf c show

Security Best Practices

• Security: Ensure that your credentials and access tokens are kept secure and not hardcoded in scripts wherever possible. Consider using environment variables or secure vaults for sensitive information. Use --password-stdin or --access-token-stdin to avoid passing credentials directly on the command line.
• Token Expiration: Access tokens may have an expiration time. Be aware of this and renew your token as needed to maintain access.
• Token Refresh: By default, JFrog CLI automatically refreshes access tokens. Use --disable-token-refresh if you want to disable this behavior.

Browser Login (Interactive)

Use the jf login command to authenticate with the JFrog Platform through a web browser. This opens a browser window for SSO/SAML sign-in. Available for Artifactory 7.64.0 and above.

To authenticate using browser login:

• Run the following command:

  Bash

  jf login

📘

Note

: This command is interactive only. It cannot be used in CI/CD servers or headless environments. For non-interactive authentication, use access tokens or OIDC token exchange.

OIDC Token Exchange

Exchange an OIDC provider token for a JFrog access token. This is the recommended method for OIDC-enabled CI systems like GitHub Actions and Azure DevOps.

To exchange an OIDC token for a JFrog access token:

• Run the following command:

  Bash

  jf eot --oidc-token-id=<token-id> --oidc-provider-name=<provider> --url=<your-url>

  Where:

  • <token-id>: The OIDC token identity mapping ID configured in the JFrog Platform.
  • <provider>: The name of the OIDC provider configured in the JFrog Platform.
  • <your-url>: The URL of your JFrog Platform instance (for example, https://yourcompany.jfrog.io).

Supported provider types: GitHub, Azure, GenericOidc. Use --oidc-provider-type to specify. Pass --oidc-audience when required by your provider.

Complete GitHub Actions OIDC Example

# .github/workflows/build.yml
name: Build with JFrog CLI (OIDC)
on: [push]
permissions:
  id-token: write  # Required for OIDC
  contents: read
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jfrog/setup-jfrog-cli@v4
        env:
          JF_URL: ${{ vars.JF_URL }}
        with:
          oidc-provider-name: github-oidc  # Must match JFrog Platform OIDC config
      - run: jf rt ping  # Verify authentication works
      - run: jf npm ci --build-name=my-app --build-number=${{ github.run_number }}

This eliminates the need to store long-lived access tokens as GitHub secrets. The setup-jfrog-cli action handles the OIDC token exchange automatically.

Environment Variable Authentication

Override authentication per run without stored configuration.

To authenticate using environment variables:

1. Set the required environment variables:

   Bash

   export JFROG_URL=<your-url>
   export JFROG_ACCESS_TOKEN=<your-token>

   Where:

   • <your-url>: The URL of your JFrog Platform instance (for example, https://yourcompany.jfrog.io).
   • <your-token>: A valid JFrog access token.

2. Run any JFrog CLI command. The CLI uses the environment variables for authentication:

   Bash

   jf rt ping

Supported variables include JFROG_URL, JFROG_ACCESS_TOKEN, JFROG_USER, and JFROG_PASSWORD. Run jf options for the full list.

Troubleshooting Authentication

Set JFROG_CLI_LOG_LEVEL=DEBUG to get detailed output for diagnosing authentication issues:

JFROG_CLI_LOG_LEVEL=DEBUG jf rt ping

📘

Coming from the JFrog UI?

If you have been managing artifacts through the Artifactory web interface, the CLI uses the same access tokens. Generate a token in the UI via Administration > Identity and Access > Access Tokens, then pass it to jf config add --access-token=<token>. Your repository names, permissions, and project keys are the same in both UI and CLI.

📘

Migrating from the REST API?

If you have been using curl with JFrog REST endpoints, the CLI handles authentication headers, token refresh, and retries automatically. Replace curl -H "Authorization: Bearer <token>" https://your-server/api/... with jf config add followed by CLI commands. The CLI maps to the same underlying API — for example, curl -X POST .../api/security/token becomes jf access-token-create.