OpenID Connect Integration

📘

Subscription Information

This feature is supported with Enterprise X and Enterprise+ licenses.

OpenID Connect (OIDC) is an identity protocol that works on top of the OAuth 2.0 protocol. It utilizes the authorization and authentication mechanisms of the OAuth 2.0 protocol to authenticate and connect between different services. OIDC allows users to use single sign-on (SSO) to access sites using OpenID Providers (OPs) to authenticate their identities.

The integration of JFrog and trusted providers using OIDC establishes trust between the trusted provider and the JFrog Platform. This setup automates token management and enhances security through OpenID Connect (OIDC) for verifying identities.

OIDC integration in the JFrog Platform allows you to use services such as GitHub Actions with OpenID Connect to work on the JFrog Platform. With OIDC integration, you can allow the GitHub Actions CI pipelines to download and publish artifacts without storing JFrog passwords, tokens, or API keys in GitHub.

📘

OpenID Connect Integration Support in GitHub Enterprise Cloud

OpenID Connect Integration is tested and certified to work with GitHub Enterprise Cloud.

You can create an OIDC integration in the JFrog Platform and add multiple identity mappings to the integration. An identity mapping is a configuration object that the JFrog Platform uses to match an incoming OIDC claim to a specific authorization scope.

When you configure identity mappings for GitHub OIDC integration, the identity mapping maps the identity of the GitHub Actions workflow to an identity in the JFrog Platform. JFrog Platform creates a reference token for each identity mapping so that the external service can authenticate in the JFrog Platform.

You can also use the REST APIs to configure OIDC integration. For more information, see OIDC Integration API.

OpenID Connect Integration Benefits

OpenID Connect (OIDC) integration provides the following benefits that greatly increase the flexibility to authenticate providers working with the JFrog Platform.

• Passwordless experience: Eliminate the storage of basic credentials, permanent tokens, or API Keys, for example in GitHub Secrets, thereby mitigating security risks.
• Dynamic Token Generation: Efficient management of the token lifecycle with automated token generation with short-term lifespans. Significantly reduces the likelihood of outdated or unused tokens in the system, which minimizes security risks.
• Consistent Access Control Policies: Consistently apply access control policies with a fine-grained permission model. Enforce the principle of least privilege, which grants only the necessary permissions for specific operations, resulting in a more secure environment.
• Improved Developer Experience: Create seamless, efficient, user-friendly, and secure developer workflow by eliminating the need for manual token management to handle and manage tokens manually.
• Seamless Access: Provides automatic secure access to JFrog resources without manual token creation.
• Reduces Configuration Errors: Use OIDC parameters for authentication configuration and identity mapping.

OpenID Connect Configurations Overview

Using OpenID Connect, the JFrog Platform acts as a service provider that receives users' authentication information from external identity providers. JFrog Platform OIDC integrations connect the JFrog Platform with other services that use OpenID. In this case, JFrog is no longer responsible for the authentication of the user although it still has to redirect the login request to the identity provider and verify the integrity of the identity provider’s response.

You can create, edit, delete, and view the JFrog Platform OIDC integrations that connect the JFrog Platform with other services using OpenID.

To view the OIDC providers you have configured, go to General Management > Manage Integrations. The list of OIDC provider configurations defined in Artifactory is displayed in the list section.

You can add new OIDC provider configurations, or edit or delete existing ones.

The following table describes the settings displayed for providers:

Understanding the OIDC Token

OIDC flows are based on OAuth flows. In an OAuth flow, the end-user provides their credentials to the identity provider. The user receives an authorization prompt, in which they allow the delegated app to reuse their login to the identity provider. OAuth then provides the application an Access Token, which authorizes the user to access an app, but does not contain any information about the user. OIDC also uses an authorization prompt to authenticate a user and provide an ID Token. The ID Token is technically a JSON Web Token (JWT), and includes identifiable information about the user, such as their name and email address. The application can use this ID Token to prove users are authenticated.

When a user authenticates to an application through an identity platform using the OIDC protocol, it sends a token to the application. The application validates and uses the token to sign the user in instead of prompting for a username and password.

The OIDC token grants the user permissions and defines the token scope, and takes this one step further by providing the UserInfo Endpoint, which delivers information about the user, leveraging a set of standard scopes, while allowing customization. An OIDC ID Token includes the following basic claims:

The ID Token provides apps with additional user data, which isn’t a part of the authentication process but is used for functional purposes. The ID Token can include names, emails, and more (see the full list of OIDC standard user claims).

Identity Mappings

An identity mapping is a configuration object that the JFrog Platform uses to match an incoming OIDC claim to a specific authorization scope. An identity mapping enables users to validate access requests based on the claim JSON. This ensures that tokens are granted based on specific criteria, such as user roles or project requirements.

When you configure OIDC integration, you need to configure the associated identity mappings as well. Each identity mapping creates a reference token to authenticate with the JFrog Platform.

You can create identity mappings when you create an OIDC integration. You can also create identity mappings for an existing OIDC Integration. Starting from Artifactory version 7.104.1, you can add multiple scopes to OIDC identity mapping tokens, so both user and group scopes can be used for the same token.

📘

Note

Some scopes cannot be combined with others: refer to this table to see which scopes can be added to the same token.

Token Scope	Can be combined with:  Admin	Can be combined with:  User	Can be combined with:  Groups	Can be combined with:  User Dynamic Mapping	Can be combined with:  Groups Dynamic Mapping
Admin	N/A
User		N/A
Groups			N/A
User Dynamic Mapping				N/A
Groups Dynamic Mapping					N/A

You can create multiple identity mappings for any integration. Each mapping has a priority field. Prioritization ensures that the relevant token is generated. A token is defined by considering the configured JSON claim. We strongly encourage you to define JSON claims in the identity mapping for security purposes If you don't add claims anyone that knows the service account to target can get access.

📘

Note

From Artifactory version 7.94 you can create identity mappings associated with a specific project.

A Project Admin can now create identity mappings.

When you are working in the scope of All Projects, a Platform Admin can create identity mappings. If you are working in the scope of a specific project, a Project Admin can create identity mappings for that project. There are both global level identity mappings and project level identity mappings. Global identity mappings can apply to all projects. A Project identity mapping applies only to a selected project. Each identity mapping is assigned a priority rating. Project identity mappings take precedence in priority over global identity mappings.

JSON Claims

The JSON Web tokens (JWT) used by OIDC and OAuth applications contain pieces of information about the user known as claims. A JSON Claim is information that an identity provider states about a user inside the token they issue for that user.

In an OIDC response, claims data is typically contained in the ID Token issued by the identity provider in the form of a JWT. Identity mappings contain JSON Claims that are used to provide token information.

JSON web token claims are pieces of information asserted about a subject (user). For example, an ID token, which is always a JWT, can contain a claim called name that asserts that the name of the user undergoing authentication is "Sally Doe". In a JWT, a claim appears as a name/value pair where the name is always a string and the value can be any JSON value.

For example, the following JSON object contains three claims (sub, name, admin):

{
      "sub": "1234567890",
      "name": "Sally Doe",
      "admin": true
 }

The JWT specification defines seven reserved claims that are not required, but are recommended to allow interoperability with third-party applications. They include the following basic claims:

For more information, see a list of OIDC standard user claims. See also a full list of JSON claims.

You can define your own custom claims which you control and you can add them to a token by configuring them in the identity mapping that you create for an OIDC integration.

When you configure your cloud to trust GitHub's OIDC provider, you must add conditions that filter incoming requests, so that untrusted repositories or workflows will not be able to request access tokens for your cloud resources. We strongly encourage people to set at least one claim in the identity mapping. If you don't add claims anyone that knows the service account to target can get access.

Before granting an access token, your cloud provider checks that the subject and other claims used to set conditions in its trust settings match those in the request's JSON Web Token (JWT). As a result, you must ensure you correctly define the subject and other conditions in your cloud provider. See also Security Hardening.

The OIDC trust configuration steps and the syntax to set conditions for cloud roles (using Subject and other claims) will vary depending on which cloud provider you're using. For some examples, see Example subject claims.

Multiple Values

From Artifactory version 7.94.1, multiple values are supported for JSON Claims. Identity mappings use JSON Claims to define the scope of generated access tokens. You can now define the scope of an access token for multiple values, for example for multiple repositories and environments.

Example

Following is an example of a JSON Claim definition for multiple repositories.

{
 "repository":["jfrog/jfrog-cli", "jfrog/artifactory-client-java", "jfrog/setup-jfrog-cli"]
}

Wildcard Values

Wildcard values are supported from Artifactory version 7.94.1 for JSON Claims. You can now define the scope of an access token using wildcard values, and can use both explicit and implied patterns.

Examples

Following are two examples of a JSON Claim definition for repositories using a wildcard.

{
  "repository": "jfrog/*"
}

{
  "repository": "jfrog/jfrog-cli/**"
}

Multiple Values in JSON Claims

From Artifactory version 7.94.1, multiple values are supported for JSON Claims. Identity mappings use JSON Claims to define the scope of generated access tokens. You can now define the scope of an access token for multiple values, for example for multiple repositories and environments.

The following is an example of a JSON Claim definition for multiple repositories.

{
 "repository":["jfrog/jfrog-cli", "jfrog/artifactory-client-java", "jfrog/setup-jfrog-cli"]
}

Wildcard Values in JSON Claims

Wildcard values are supported from Artifactory version 7.94.1 for JSON Claims. You can now define the scope of an access token using wildcard values, and can use both explicit and implied patterns.

Following are two examples of a JSON Claim definition for repositories using a wildcard.

{
  "repository": "jfrog/*"
}

{
  "repository": "jfrog/jfrog-cli/**"
}

Dynamic Mapping

Identity mappings can contain dynamic mappings that are used to support verification or modification for a username or group name in the token subject based on a pattern. The pattern is a string that specifies which claim you want to extract from the token request. If the claim is not found, the token request fails. The pattern can be used to replace a part of the claim with a username, or to add data, or to verify that the data in the claim matches a definition. For a dynamic group definition, the pattern is applied to all groups and adds the pattern to the group scope.

When creating an identity mapping, you can choose for the token scope to create a Group Mapping with an identity mapping Pattern, as shown below.

📘

Note

Starting from Artifactory version 7.130.0, the JFrog Platform supports more advanced logic in dynamic mappings. For examples, see Advanced Dynamic Mapping

Following are several examples of identity mapping patterns.

Example

For the following mapping, there will be no change. The identity mapping will take the actor claim and use it as is. When the claims are applied, the pattern “actor” : “saidegreen” in the token subject will be used as is: applied-permissions/user:saidegreen.

{{actor}}

Example

The following dynamic mapping will try to find the actor claim in the token request claim and add @jfrog.com at the end. When the claims are applied, the pattern “actor” : “saidegreen” in the token subject will become applied-permissions/user:[email protected].

{{actor}} | [email protected]

Example

The following dynamic mapping will try to find the actor claim in the token request claim and then remove the @jfrog.com at the end. When the claims are applied, the pattern “actor” : “[email protected]” in the token subject will become applied-permissions/user:username.

({{actor}}) @jfrog.com|$1

Example

The following dynamic mapping will look for email claims that start with jf and end with jfrog.com. When the claims are applied, the pattern “mail” : “[email protected]” in the token subject will become applied-permissions/user:[email protected]:username. However, “mail” : “[email protected]” will fail the request because the email does not start with jf.

jf{{mail}}jfrog.com|$0

Example

For the following, the dynamic mapping will look for claims that contain group and add to the end of the claim -jfrog. When the claims are applied, the claims claim("group", "gitgroup, gitgroup2, gitgroup3, gitgroup4") will become applied-permissions/groups:"gitgroup-jfrog","gitgroup2-jfrog","gitgroup3-jfrog","gitgroup4-jfrog".

{{group}} | $0-jfrog

Example

Following are examples of dynamic mapping patterns with the format {claim value, pattern, result}.

{"jfuser-f12jf", "jf{{actor}}jf|$1", "user-f12"}
{“jfuser-f12jf”, jfrog{actor}}jfrog|$1, “jfroguser-f12jfrog”}
{“user”, “{{actor}}”, “user”}
{“user”, “{{actor}} | hub$0jfrog”, “hubuserjfrog”}

Advanced Dynamic Mappings

The following are examples of more advanced dynamic mapping patterns, supported for Artifactory versions 7.130.0 and above:

Example

For the following, the dynamic mapping will convert user emails into an app username format. To do so, the mapping will remove the @hapoelj.com suffix, replace it with the _xom suffix, and convert all periods (.) with hyphens (-).

{{email}} | ^([^@]+)@jfrog\.com$ | $1_xom | op:replaceAll(".","-")

When the claims are applied, the pattern “email” : “[email protected]” in the token subject will become applied-permissions/user:nick-v-goose_xom.

Example

For the following, the dynamic mapping will replace all the hyphens (-) with underscores (_), and replace the _gme suffix with an _artifactory_cicd suffix.

{{actor}} | op:replaceAll("-","_") | ^([^_]+)_([^_]+)_([^_]+)_gme$ | $1_$2_$3_artifactory_cicd

When the claims are applied, the pattern “actor” : “Si-nam-abced_gme” in the token subject will become applied-permissions/user:Si_nam_abced_artifactory_cicd.

Example

For the following, the dynamic mapping will replace the first lowercase 'a' with an uppercase 'A', replace the last lowercase 't' with an uppercase 'T', and replace the hyphen (-) with an underscore (_)

{{data}} | ^([^-]+)-([^-]+)$ | op:replaceFirst("a","A") | op:replaceLast("t","T") | $1_$2

When the claims are applied, the pattern “data” : “team-project” in the token subject will become applied-permissions/user:teAm_projecT.

JFrog CLI Code Snippets

Add OIDC configuration code to your GitHub Actions workflow file by generating and copying a snippet with the JFrog CLI.

When you create an integration, you can use the Show snippet option to create a JFrog CLI configuration code snippet for the integration. Utilizing the Setup JFrog CLI simplifies integration of GitHub Actions workflows with JFrog OIDC integration.

For example, you can generate the following snippet and add it to your GitHub Actions workflow.

Configure an OIDC Integration

You can configure an OIDC integration to connect the JFrog Platform with other services that use OpenID. This procedure includes configuration for two OIDC providers, for example, JFrog Platform and GitHub OIDC Provider, which includes configuring trust policy (identity mapping) between the two providers.

1. In the JFrog Platform, select the Administration module and go to General Management > Manage Integrations. The Integrations page appears.
2. Click New Integration > OpenID Connect. The OIDC Integration page appears.

4. Enter the OIDC provider name that you want to connect with the JFrog Platform. The provider name must match the configuration in the OIDC provider.

   In GitHub OIDC integration, for example, you must enter the same provider name that you configure in the JFrog Platform in the following section of the GitHub Actions YAML file.

   \"provider_name\": \"<your provider name> \"}"

   The following snippet shows part of a sample GitHub Actions YAML file, where the provider name is github-oidc-integration.

   - name: Fetch Access Token from Artifactory id: fetch_access_token env: ID_TOKEN: ${{ steps.idtoken.outputs.id_token }} run: | ACCESS_TOKEN=$(curl \ -X POST \ -H "Content-type: application/json" \ https://example.jfrog.io/access/api/v1/oidc/token \ -d \ "{\"grant_type\": \"urn:ietf:params:oauth:grant-type:token-exchange\", \"subject_token_type\":\"urn:ietf:params:oauth:token-type:id_token\", \"subject_token\": \"$ID_TOKEN\", \"provider_name\": \"github-oidc-integration\"}" | jq .access_token | tr -d '"')

5. Select the provider type. You can choose between the following options.

   • GitHub
   • Azure
   • Generic OpenID Connect

6. Enter the description of the OIDC integration.

7. Enter the provider URL. If you chose GitHub as the provider, the provider URL is automatically set as https://token.actions.githubusercontent.com.

8. (Optional) Enter the name of the audience for this integration. The audience determines the scope of the integration. You must use scope definitions as provided by the OIDC provider.

9. Take provider-specific additional steps:

   • (Optional) For GitHub, select Enable Permissive Configuration to enable authentication without organization restrictions. Note: this is not recommended, as the permissive configuration may grant broader access.
   • For Azure, if the application has custom signing keys as a result of using the claims-mapping feature, you must provide the Azure App ID. See the Azure documentation for more information. (Only relevant for Azure provider type)

10. Do one of the following:

    • Click Save and Continue to continue configuring identity mappings. You can create multiple identity mappings for an integration. Each mapping has a priority field. Prioritization ensures that the relevant token is generated by considering the configured JSON claim. For more information, see Configure Identity Mappings.
    • Click Save to save the configuration and configure identity mappings later.

11. You can use the Show snippet option to generate code with the definitions you created above to include in your authentication workflow. For more information, see generating and copying a snippet.

Configure Identity Mappings

Perform the following steps to add identity mappings for an existing OIDC integration.

📘

Note

From Artifactory version 7.94, you can create identity mappings associated with a specific project. A Project Admin can now create identity mappings.

1. Select All Projects, or from the Projects list, select the project for which to view identity mappings.

2. Select the Administration module, and then select General Management > Manage Integrations.

   The Integrations page appears.

3. On the row of the relevant OIDC integration, click the + menu on the right and select Add Identity Mapping for an existing integration. The OpenID Connect Integration window appears.

   

4. In the OpenID Connect Integration window, in the Identity Mappings area, select the Global or Project tab, depending on the level of the identity mapping that you want to create.

   

5. In the Identity Mappings dialog, enter the mapping details. The following table describes the fields. Some fields are required.

   

6. Enter the Priority of the identity mapping.

   The priority should be a number. The higher priority is set for the lower number. If you do not enter a value, the identity mapping is assigned the lowest priority.

   We recommend that you assign the highest priority (1) to the strongest permission gate. Set the lowest priority to the weakest permission for a logical and effective access control setup.

   The project priority takes precedence over the global priority.

7. Enter the Description of the identity mapping.

8. Enter the Claims JSON from the OpenID provider for the identity mapping.

   For more information about claims JSON in GitHub Actions, refer to the GitHub Actions Documentation. We strongly encourage you to define JSON claims in the identity mapping for security purposes. If you don't add claims, anyone who knows the service account to target can get access.

   The following is an example JSON Claim:

   {
     "iss": "https://token.actions.githubusercontent.com",
     "repository": "octo-org/octo-repo"
   }

9. When in the Global scope:

   1. Select the Token Scope.

      The following scopes are available.

      • Admin
      • User
      • Group

   2. Enter the User Name.

      The username appears in the JFrog Platform logs when the external service authenticates with this identity mapping.

10. When in the Project scope, the Project Role is defined as the Project Admin.

    Select the Role that identifies the permissions that will be associated with the project-scoped token.

    You can select one or more roles. You can select from the project roles that you have defined for a specific project.

11. Select the Services for which the mapping applies. Select All to apply the mapping to all services.

12. Set the Expiration Time for the token in minutes. The default value is 1.

13. When finished, click Save.

    The new identity mapping appears in the list of identity mappings, according to whether it is a global or project mapping.

14. To edit or delete an identity mapping, click the ... menu at the end of the row.

View OIDC Configurations

📘

Note

From Artifactory 7.94, you can view OIDC Configurations associated with specific projects.

1. Select All Projects, or from the Projects list, select the project for which to view webhooks.

2. In the Administration module, select General Management > Manage Integrations.

   The Integrations page appears.

3. Select the OpenID Connect tab. If you are viewing a specific project, only OIDC configurations associated with the project are shown.

Platform Admins can edit or delete OIDC integrations.

Both Platform Admins and Project Admins can add identity mappings to an OIDC configuration. For more information, see Configure Identity Mappings.

View OIDC Configuration Identity Mappings

📘

Note

From Artifactory 7.94, Project Admins can create Identity Mappings associated with specific projects.

1. Select All Projects, or from the Projects list, select the project for which to view OIDC configurations.

2. In the Administration module, select General Management > Manage Integrations. The Integrations page appears.

3. Select the OpenID Connect tab to view the OIDC configurations and their associated identity mappings. If you are viewing a specific project, only OIDC configurations associated with the project are shown.

   Enter the provider URL.

4. To view identity mapping details, click the eye icon in the row of the identity mapping.

   To add an identity mapping, see Configure Identity Mappings.

Optimize OIDC Integration Performance

Optimizing your OpenID Connect (OIDC) integration is key to delivering fast, secure, and scalable authentication experiences. By thoughtfully managing identity mappings, applying throttling, and designing for scalability, you can ensure that your OIDC implementations remain resilient and efficient even as user demand grows, and ensure optimal performance and stability of the JFrog Platform Deployment (JPD).

📘

Environment and Resource Context

The following recommendations were created by conducting performance testing on the Access service in a new, large environment with the following resources:

• 3 pods of each service

• Limits for each Access service container:

  • CPU limit: 6 cores
  • Memory limit: 3 GB

Note that different instances might have different performance capabilities.

The OIDC system demonstrates strong reliability at moderate load levels. To effectively scale your OIDC integration and avoid issues, use the following best practices:

Optimize Identity Mappings

Efficient identity mappings are essential for maintaining low latency and predictable performance. To optimize identity mappings:

• Keep claims small and simple: Avoid elements like wildcards (*) that increase processing overhead.
• Prioritize critical mappings: Place the most frequently used mappings higher in the list to reduce search depth, resources, and evaluation time.

Control Load and Concurrency

A high number of concurrent operations causes stress on the system. To control your load:

• Keep identity mapping creation/edit rate below 500 requests per second: To maintain consistent performance and prevent overload, use throttling or scheduled updates when approaching 1000 requests per second.
• Keep token exchange rate below 40 requests per second: Use throttling or scheduled updates when exceeding this threshold.

Plan for Scale and Resilience

To ensure scalability and fault tolerance under varying workloads:

• Segment mappings: To avoid massive, monolithic mapping lists that slow down processing, separate mapping lists by different projects or teams.
• Enable auto-scaling and proactive monitoring: Monitor for error spikes (specifically 409, 502, or 503 errors) as early indicators of resource strain or contention.

In summary, to maintain stability under higher concurrency, optimize mappings, enforce throttling, and design for horizontal scalability for smooth and scalable performance.

Integration with GitHub

There are two main ways to integrate the JFrog Platform with GitHub via OpenID Connect (OIDC):

• Integration With GitHub App
• Integration with GitHub Actions

Integration With GitHub App

The JFrog GitHub App enables you to connect GitHub repositories to the JFrog platform, providing a scalable setup, advanced vulnerability scanning for both source code and binaries, and a unified view, all within GitHub. The integration allows you to automate Frogbot deployment and create a centralized OIDC configuration, and view JFrog Advanced Security information in GitHub Advanced Security Dashboard.

Related Information:

• JFrog App for GitHub
• Integrate Frogbot with the JFrog GitHub App

Configure JFrog OIDC Integration with GitHub App

You can configure OpenID Connect (OIDC) integration between JFrog and GitHub using two modes: Automatic and Advanced.

1. In the JFrog Platform, select the All Projects scope

2. Select the Administration module, and go to General Management > Manage Integrations

3. Click New Integration, and select GitHub Repositories from the drop-down menu. The Connect Git Repositories page opens.

4. Click Open GitHub Marketplace to be redirected to the JFrog App for GitHub integration page on GitHub.

5. Review the integration readme file and click Install to install the JFrog App for GitHub.

6. Select the repositories on which to install the application and click Install & Authorize. The JFrog App installer dialog opens.

7. In the Platform URL field, enter your Hostname URL, select the checkbox to agree to the terms, and click Start

The app installer prompts you to grant permission to access JFrog Platform resources. To allow the integration, select the checkbox to agree to the terms and click Allow.

8. The Integration Setup page appears.

The Select GitHub Repositories area lists your GitHub repositories. Select the repositories for which you want to enable the integration. Click Next.

In the Select Token Type area, enter the values JFrog uses to Create a Scoped Token. In the Service field, all services are selected by default. If you wish, specify the services that the integration can use.

In the Create Pull Request area, enable the Auto-Generate Pull Request checkbox to send a pull request to the repositories you selected. Click Next.

3. In GitHub, go to a repository that you selected in the previous step, and verify that the JFrog pull request is there.

4. The pull request should contain the following code sample, including all the necessary OIDC configuration parameters, such as the OIDC provider name:

    name: "Setup JFrog CLI OIDC Example"
                   on: push
                   
                   permissions:
                     # This is required for requesting the OIDC token
                     id-token: write
                     # This is required for actions/checkout
                     contents: read
                   jobs:
                     build:
                       runs-on: ubuntu-latest
                       steps:
                         - name: Checkout
                           uses: actions/checkout@v4
                         - name: Setup JFrog CLI
                           uses: jfrog/setup-jfrog-cli@v4
                           env:
                             JF_URL: ${{ vars.JF_URL }}
                           with:
                             oidc-provider-name: <github_username>/<repo-name>@github
                   
                         - name: Run JFrog CLI
                           run: |
                             # Ping the server
                             jf rt ping

5. Integrate the code snippet components in your own GitHub workflow, and replace the JF_URL placeholder with your own JFrog Host URL

6. Merge the pull request in your GitHub repository.

Manage JFrog OIDC Integration with GitHub App

This section describes you can take within the JFrog OIDC Integration after configuring it.

Add repositories to the JFrog Integration with GitHub

To add more GitHub repositories to the integration, follow these steps:

1. Select the Administration module, and go to General Management > Manage Integrations

2. Go to the Git Repositories tab, and click + Add Repositories

3. In the Integration Setup dialog, configure app settings:

   The Select GitHub Repositories area lists your GitHub repositories. Select the repositories for which you want to enable the integration. Click Next.

   In the Select Token Type area, enter the values JFrog uses to Create a Scoped Token. In the Service field, all services are selected by default. If you wish, specify the services that the integration can use.

   In the Create Pull Request area, enable the Auto-Generate Pull Request checkbox to send a pull request to the repositories you selected. Click Next.

4. In GitHub, go to a repository that you selected in the previous step, and verify that the JFrog pull request is there.

Edit Identity Mapping for a Repository in the JFrog Integration with GitHub App

To edit an existing repository in the integration, follow these steps:

1. Select the Administration module, and go to General Management > Manage Integrations
2. Find the repository you want to edit, and click the options menu next to it: Select Edit Identity Mapping from the drop-down menu
3. Change the identity mapping and click Save.

Remove a Repository from the JFrog Integration with GitHub App

This topic describes how to disconnect unwanted GitHub repositories from the integration.

1. From the Administration module, click General Management > Manage Integrations > Git Repositories.
2. Find the repository you want to remove, and click the options (...) menu next to it.
3. Select Disconnect Integration from the drop-down menu.
4. In the pop-up confirmation dialog, click Delete.

Integration with GitHub Actions

GitHub Actions OIDC Integration Workflow

The following diagram provides the workflow of GitHub Action OIDC Integration with JFrog Platform.

1. GitHub Actions Workflow requests for an ID token from the GitHub OIDC Provider when it encounters a connection to the JFrog Platform.
2. GitHub OIDC Provider generates an ID token that contains multiple claims to establish a security-hardened and verifiable identity about the specific workflow that is trying to authenticate.
3. The workflow sends the ID token to the JFrog Platform where JFrog Access processes the request.
4. JFrog Access verifies the ID Token from GitHub by utilizing a certificate supplied from GitHub's JSON Web Key (JWK).
5. JFrog Access validates claims in the ID token, the scope of the audience, and generates a short-lived access token that is available only for the duration that was configured when you created the identity mapping.

JFrog Access sends the access token to the GitHub Action Workflow to successfully validate the operation that involves the JFrog Platform.

Whenever your job runs, JFrog Platform utilizes the GitHub’s OIDC Provider and generates an OIDC token. This token contains multiple claims to establish a verifiable identity for the workflow that is authenticating.

Include a step in your job to request this token from GitHub’s OIDC provider and send it to the JFrog Platform. At this step, the JFrog Platform verifies the ID Token from GitHub by utilizing a certificate supplied from GitHub’s JSON Web Key (JWK).

Once the JFrog Platform successfully validates the claims presented in the token, it provides a short-lived access token that is available only for the duration that was configured when you created the identity mapping.

For a sample workflow, see Sample GitHub Actions Workflow YAML. For more information about setting up OIDC integration with GitHub Actions, see Sample Integration with GitHub.

Configure JFrog Platform OIDC Integration with GitHub Actions

For more information about configuring the integration and the GitHub Actions workflow, see Sample Integration of JFrog OIDC with GitHub Actions and GitHub Actions Workflow.

1. Navigate to the Administration tab In the JFrog Platform UI.

2. Click General Management > Integrations.

   The Integrations page appears.

3. Click New Integration > OpenID Connect.

   The OIDC Integration page appears.

4. Enter the name of the OIDC configuration, the OIDC provider that will connect with the JFrog Platform.

5. Select GitHub as the provider type.

6. Enter the provider URL. OIDC issuer URL. For GitHub actions, the URL is https://token.actions.githubusercontent.

7. Enter the audience. Used to provide details of the audience that uses the OIDC configuration.

8. Provide the token issuer when the OIDC provider URL is not the same as the token issuer.

9. Add OIDC configuration code to your GitHub Actions workflow file by generating and copying a snippet

10. Create one or more identity mappings.

11. Configure the integration and click Save.

Setting up GitHub Actions to Establish Trust with the JFrog Platform

After setting up the OIDC Integration in the JFrog Platform you must set up GitHub Actions and the GitHub Actions workflow to establish trust.

When you configure the JFrog Platform OIDC integration, you need to configure a GitHub Actions workflow in GitHub. For more information about configuring the GitHub Actions workflow, see GitHub Actions Workflow

1. In the GitHub Actions Workflow YAML file, add the permissions setting to request the JSON Web Token (JWT).

   permissions:
     id-token: write # This is required for requesting the JWT   

2. Generate a token in GitHub Actions.

   In the GitHub YAML, to generate a token in GitHub Actions, you can use getIDToken() from the Actions toolkit to request a JWT from GitHub's OIDC provider.

   getIDToken()

   For more information and alternatives, see Updating Actions for OIDC.

3. Add a POST request to the JFrog Platform OIDC Token Exchange API. Add the POST request to your GitHub Actions YAML file to the JFrog OpenID endpoint to receive the JWT token.

   curl -X POST -H "Content-type: application/json" 
        https://example.jfrog.io/access/api/v1/oidc/token -d \
        '{“grant_type”: “urn:ietf:params:oauth:grant-type:token-exchange”, \
         “subject_token_type”:”urn:ietf:params:oauth:token-type:id_token”, \
         “subject_token”: <ID_TOKEN>, \
         "provider_name": "github-oidc"}'

4. Use the JWT token in GitHub Actions. The JWT token generated by the OIDC endpoint can be used like an API key.

Configure OIDC-GitHub Integration with Code Snippets

📘

Note

Showing and copying code snippets is currently only available for configuration of OIDC integration with GitHub Actions.

To simplify and streamline the creation of your authentication workflow, you can use OIDC configuration integration with code generation capabilities to obtain code snippets that contain all the Integration parameters and their definitions.

For example, you can add OIDC configuration code to your GitHub Actions workflow file by copying a snippet generated with the JFrog CLI. For more information about using the JFrog CLI, see JFrog CLI. For more information about JFrog CLI setup, see Setup JFrog CLI. For a sample version of the GitHub Actions workflow YAML, see Sample OIDC Integration YAML.

1. In the OIDC Integration page, after you configure the OIDC integration for GitHub Actions, click Show snippet.

   The generate snippet feature takes the general parameters and generates a snippet that contains the parameter names and values to be added to the GitHub Workflow. There are two snippets available, one for those who use the JFrog CLI and a general code snippet for use with CURL commands.

   For example, to use the JFrog CLI code snippet, select the JFrog CLI tab. The JFrog CLI snippet appears.

   

2. Use the Copy option to add a snippet to your GitHub workflow.

   

Configuring Permissions in the Workflow YAML

To update your GitHub Actions workflows for OIDC, you will need to add permissions settings for the token.

A GitHub Actions job or workflow run requires a permissions setting with id-token: write to allow an OIDC provider to create a JSON Web Token for every run. You will not be permitted to request the OIDC JWT ID token if the permissions for id-token is not set to write.

This setting enables the workflow to fetch and set the OIDC token for an action or step to enable authenticating with a short-lived access token. The actual trust setting is defined using OIDC claims. For more information about how to define these claims, see "About security hardening with OpenID Connect."

The id-token: write setting allows the JWT to be requested from GitHub's OIDC provider.

Add the following code to your GitHub Actions Workflow YAML:

permissions:
  id-token: write # This is required for requesting the JWT

Sample Integration of JFrog OIDC with GitHub Actions

This is an example of how to create a basic JFrog Platform OIDC integration between the JFrog Platform and GitHub Actions with a GitHub Actions workflow that uses the JFrog CLI.

When you configure the JFrog Platform OIDC integration, you also need to configure a GitHub Actions workflow in GitHub. For more information about configuring the GitHub Actions workflow, see GitHub Actions Workflow

1. In the JFrog Platform, create an OIDC integration between GitHub Actions to the JFrog Platform:

   1. Navigate to the Administration tab In the JFrog Platform UI.

   2. Click General Management > Integrations.

      The Integrations page appears.

   3. Configure the OIDC integration.

      

   4. Create one or more identity mappings. In the Identity Mappings window, fill in the mapping details.

   5. Add OIDC configuration code to your GitHub Actions workflow file by generating and copying a snippet.

2. Set up permissions in GitHub Actions and in your GitHub Actions workflow YAML.

   1. Open your GitHub Actions YAML file which sets up your GitHub Actions workflow.

   2. In the GitHub Actions YAML file, add the permissions setting to request the JSON Web Token (JWT).

      permissions:
        id-token: write # This is required for requesting the JWT   

   3. Generate a token in GitHub Actions.

      In the GitHub YAML, to generate a token in GitHub Actions, you can use getIDToken() from the Actions toolkit to request a JWT from GitHub's OIDC provider.

      For more information and alternatives, see Updating Actions for OIDC.

   4. Add a POST request to the JFrog Platform OIDC Token Exchange API. Add the POST request to your GitHub Actions YAML file to the JFrog OpenID endpoint to receive the JWT token.

      You can use the JFrog CLI snippet you copied from the JFrog OIDC integration configuration to copy configuration information such as the environment URL, provider name, and audience.

      See the following general example.

      curl -X POST "${{ secrets.JFROG_PLATFORM_URL }}/access/api/v1/oidc"
          -H "Content-Type: application/json"
          -d '{
                "name": "${{ env.OIDC_PROVIDER_NAME }}",
                "issuer_url": "https://token.actions.githubusercontent.com",
                "provider_type": "GitHub",
                "description": "This is a test configuration created for OIDC-Access integration test"
                "projectKey": "projectkey15901"
          }'

   5. Use the JWT token in GitHub Actions. The JWT token generated by the OIDC endpoint can be used to establish.

3. In GitHub, create a new GitHub repository.

4. In the GitHub repository you created, create a secret named JF_URL. For more information about setting secrets, see Creating and using secrets encrypted variables. Set the value of the secret to be the JFrog Platform URL, for example, https://acme.jfrog.io.

5. To test the workflow, push the workflow.yml file under .github/workflows/ in your GitHub repository.

6. The GitHub Action workflow runs following any push to the repository.

Sample GitHub Actions Workflow YAML

The following example shows a sample GitHub Actions Workflow YAML file that you can use to test OIDC integration in the JFrog Platform. The workflow YAML is used to facilitate OpenID Connect Integration between the JFrog Platform and GitHub Actions by providing configuration details and definitions. You need to create and deploy a workflow YAML in GitHub Actions after you configure OIDC integration in the JFrog Platform.

You can also view a live sample on GitHub.

name: "Setup JFrog CLI OIDC Example"
on: push

permissions:
  # This is required for requesting the OIDC token
  id-token: write
  # This is required for actions/checkout
  contents: read
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup JFrog CLI
        uses: jfrog/setup-jfrog-cli@v4
        env:
          # JFrog platform url (for example: https://acme.jfrog.io)
          JF_URL: ${{ vars.JF_URL }}
        with:
          # Name of the OIDC provider as specified on the OIDC integration page in the JFrog Platform
          oidc-provider-name: setup-jfrog-cli

      - name: Run JFrog CLI
        run: |
          # Ping the server
          jf rt ping
          # Collect environment variables for the build
          jf rt bce
          # Collect VCS details from git and add them to the build
          jf rt bag
          # Publish build info
          jf rt bp

Additional Sample Workflow YAML

The following example shows an additional sample GitHub Actions YAML file that you can create and deploy in GitHub Actions after you configure OIDC integration in the JFrog Platform.

name: oidc-poc
on:
  push:
    branches:
      - '*'
jobs:
  auth:
    permissions:
      contents: read
      id-token: write

    runs-on: ubuntu-latest
    steps:
      - name: Get id token
        run: |
          ID_TOKEN=$(curl -sLS -H "User-Agent: actions/oidc-client" -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
          "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=jfrog-github" | jq .value | tr -d '"')
          echo "ID_TOKEN=${ID_TOKEN}" >> $GITHUB_ENV
          echo "::add-mask::$ACCESS_TOKEN"
      - name: Exchange token with access
        env:
          ID_TOKEN: ${{ env.ID_TOKEN }}
          POC_URL: ${{ vars.POC_URL }}
        run: |
          ACCESS_TOKEN=$(curl -XPOST "${POC_URL}/token" -d "{\"grant_type\": \"urn:ietf:params:oauth:grant-type:token-exchange\", \"subject_token_type\":\"urn:ietf:params:oauth:token-type:id_token\", \"subject_token\": \"$ID_TOKEN\", \"provider_name\": \"github-oidc\"}" | jq .access_token | tr -d '"')
          echo "ACCESS_TOKEN=${ACCESS_TOKEN}" >> $GITHUB_ENV
      - name: Checkout
        uses: actions/checkout@v2
      - name: Build
        run: |
          make build
      - name: Deploy to artifactory
        env:
          ID_TOKEN: ${{ env.ACCESS_TOKEN }}
          POC_URL: ${{ vars.POC_URL }}
        run: |
          curl -H "Authorization: Bearer $ACCESS_TOKEN" -T oidc-poc "${POC_URL}/artifactory/access-oidc-poc/oidc-poc-$(date +%Y%m%d%H%M%S)"

Integration with Azure

Integration of JFrog OIDC with Azure DevOps

This guide walks you through the process of configuring OpenID Connect (OIDC) integration between JFrog and Azure DevOps. This integration allows JFrog to trust the Azure DevOps identity provider and authenticate users and pipelines securely via short-lived tokens.

Step 1: Configure the Service Connection in Azure DevOps

Before setting up the integration in JFrog, you need to create a Service Connection in Azure DevOps to obtain the necessary information, such as the Organization GUID and token issuer URL. For more information, see the Azure Documentation.

1. In Azure DevOps, go to Project settings → Service connections

2. Click New service connection, select JFrog Platform as the type of service connection, and click Next

3. In the Authentication method field, select OpenID Connect Integration

4. Enter the following information in the module fields:

   

   1. In the Server URL field, enter your full JFrog domain URL: for example, https://my.jfrog.io/
   2. In the OpenID Connect Provider Name field, enter a name you will later use in the JFrog integration: for example, azure-oidc
   3. In the Platform URL field, enter your JFrog Platform base URL: for example, https://my.jfrog.io/
   4. (Optional) In the Service Connection Name field, enter a name for the connection: this name must match the sub-claim format used in your identity mapping Description

5. Run a pipeline using this service connection—even if it fails, the output will include valuable information needed for the next steps. Look in the pipeline logs and copy the following values:

   OIDC Token Issuer: https://vstoken.dev.azure.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   OIDC Token Subject: sc://<DevopsOrgName>/<ProjectName>/<ServiceConnectionName>
   OIDC Token Audience: api://AzureADTokenExchange

📘

Note

Do not log the full ID token or access token. However, it is safe to log claims like sub, aud, or iss for debugging.

Step 2: Configure OpenID Connect Integration and Identity Mappings in the JFrog Platform

Now that you have the values from the pipeline output, you can create the integration and identity mappings in JFrog.

1. Log in to your JFrog instance as an administrator

2. Navigate to: Administration → General Management → Manage Integrations

3. Click New Integration, and select OpenID Connect from the drop-down menu.

4. Enter the following values in the module fields:

   

   1. In the Provider Name field, enter a name for the integration: enter the same name as you did in Azure DevOps OpenID Connect Provider Name.
   2. In the Provider Type field, select Azure from the drop-down menu
   3. (Optional) In the Description field, enter a description for the integration
   4. In the Provider URL field, enter your Azure DevOps URL: for example, https://vstoken.dev.azure.com/{ORG_GUID}
   5. In the Audience field, enter: api://AzureADTokenExchange
   6. Leave the Token Issuer field blank, unless you are using a custom token issuer.

5. With the integration in place, define Identity Mappings to authorize specific Azure DevOps service connections and projects. To do so, Select the Administration module, and then select General Management > Manage Integrations.

6. Select the Integration you have created, click the option menu to the right, and select + Create Identity Mapping from the drop-down menu.

   1. Fill in the module fields: for more information, see: Identity Mappings.

   2. In the Claims JSON field, create the identity mapping based on the ID token from Azure DevOps, which has the following structure:

      {
        "jti": "<guid>",
        "sub": "sc://<DevopsOrgName>/<ProjectName>/<ServiceConnectionName>",
        "aud": "api://AzureADTokenExchange",
        "iss": "https://vstoken.dev.azure.com/<ORG_GUID>"
      }

      Create the identity mapping in the Claims JSON field based on the "sub" claim, and use wildcards (*) where appropriate.

      

      For example:

      • The mapping sc://MyOrg/MyProject/MyConnection would allow access to the MyProject project
      • The mapping sc://MyOrg/*/MyConnection would allow access to all projects under the MyConnection connection.

Optional: Use OIDC Output Variables in Pipelines

When using OIDC authentication, the JFrog Azure DevOps tasks automatically export the following variables:

• oidc_user
• oidc_token

You can use these output variables in later pipeline steps. For example:

- task: JfrogCliV2@1
  name: jfStep
  inputs:
    jfrogPlatformConnection: 'azure-oidc'
    command: 'jf rt ping'

- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      echo "OIDC Username: $($jfStep.oidc_user)"
      echo "OIDC Token: $env:oidc_token"

Integration With GitLab

Configure JFrog OIDC Integration with GitLab

To configure an integration between the JFrog Platform and GitLab, follow these steps:

1. Navigate to the Administration tab In the JFrog Platform UI

2. Click General Management > Manage Integrations

3. Click New Integration, and select OpenID Connect from the drop-down menu. Enter the following information in the module fields:

   

   1. In the Provider Type field, select Generic OpenID Connect from the drop-down menu

   2. In the Provider URL field:

      • For Cloud GitLab users, enter: https://gitlab.com
      • For Self-Hosted GitLab users, enter the URL of your GitLab instance

   3. (Optional) In the Description field, enter a description for the integration

   4. (Optional) In the Audience field, enter the audience you want to use for the integration- note that the token audience needs to match this value.

   5. (Optional) In the Token Issuer field, if required, add the token issuer

📘

Note

Token Issuer is required only if the iss claim in the GitLab token is different from the value of the Provider URL field.

4. Under Identity Mappings, click Add Identity Mapping. Enter the following information in the module fields:

   

   1. In the Priority field, enter 1 to assign the strongest permission gate

   2. (optional) In the Description field, enter a description for the identity mapping

   3. In the Claims JSON field, enter the identity mapping according to the token claims you want to match: for example, in this entry, the "sub" claim matches value "project_path:root/oidc-poc:ref_type:branch:ref:main":

      {"sub": "project_path:root/oidc-poc:ref_type:branch:ref:main"}

      See below for a list of valid GitLab JSON claims:

      

   4. Click Save

5. Click Save

Sample GitLab Workflow YAML

The following example shows a sample GitLab Workflow YAML file that you can use to configure and test the OIDC integration in the JFrog Platform by providing configuration details and definitions.

After configuring your OIDC integration in the JFrog Platform, create and deploy the following snippet in your .gitlab-ci.yml workflow YAML file in GitLab:

jf-cli-job:
  stage: build
  id_tokens:
    JFROG_CLI_OIDC_EXCHANGE_TOKEN_ID:
      aud: <AUDIENCE>
  script:
    - |
      # Configure JFrog CLI
      jf c add \
        --url=$<JPD_URL> \
        --oidc-provider-name=<PROVIDER_NAME> \
        --interactive=false
      # Ping Artifactory
      jf rt ping
      # Collect environment variables for the build
      jf rt bce mybuild $CI_PIPELINE_ID
      # Collect VCS details from git and add them to the build
      jf rt bag mybuild $CI_PIPELINE_ID
      # Publish build info
      jf rt bp mybuild $CI_PIPELINE_ID

Alternatively, you can use the following snippet with REST API commands:

rest-api-job:
  stage: build
  id_tokens:
    ID_TOKEN:
      aud: <AUDIENCE>
  script:
    - |
      ACCESS_TOKEN=$(curl -XPOST "${<JPD_URL>}/access/api/v1/oidc/token" -H 
"Content-Type: application/json" -d "{\"grant_type\": 
\"urn:ietf:params:oauth:grant-type:token-exchange\", 
\"subject_token_type\":\"urn:ietf:params:oauth:token-type:id_token\", 
\"subject_token\": \"$ID_TOKEN\", \"provider_name\": \"<PROVIDER_NAME>\"}" | jq .access_token | tr -d '"')
    - |
      curl -XPUT -H "Authorization: Bearer $ACCESS_TOKEN" 
"${JPD_URL}/artifactory/gitlab-oidc-repo/oidc-upload-$(date +%Y%m%d%H%M%S)" -d "Content to upload"