OpenID Connect Authentication

The sensitive connection details, such as the access token used by JFrog Frogbot, can be automatically generated by the action instead of storing it as a secret in GitHub. This is made possible by leveraging the OpenID-Connect (OIDC) protocol. This protocol can authenticate the workflow issuer and supply a valid access token. Learn more about this integration in this blog post. To utilize the OIDC protocol, follow these steps:

JFrog Platform configuration

Step 1: Configure an OIDC Integration

This phase is integration between GitHub Actions and the JFrog platform.

1. In the JFrog Platform, navigate to Administration > General Management > Manage Integrations.
2. From the New Integration drop-down, select OpenID Connect and enter the following information:
   1. Provider Name
      The 'Provider Name' value should be used as the oidc-provider-name input in Workflow Configuration step 2 below.
   2. Provider Type
   3. Description (optional)
   4. Provider URL
   5. Audience (optional)
      Does NOT represent the 'aud' claim that can be added to identity-mapping configured in the 'Claims JSON' (shown below). Only claims that are included in the 'Claims Json' created during step 2 will be validated.
   6. Token Issuer

Step 2: Configure an Identity Mapping

This phase is integration between a particular GitHub repository and the JFrog platform.

An identity mapping is a configuration object utilized by the JFrog Platform to associate incoming OIDC claims with particular selected fields. These fields include repository, actor, workflow, and others.

1. Select Identity Mappings > Add Identity Mapping and enter the following information:
   1. Name
   2. Priority (enter '1')
   3. Description (optional)
   4. Claims JSON
      You have the flexibility to define any valid list of claims required for request authentication. You can check a list of the possible claims here.
      Example:

{
    "repository": "repository-owner/my-repository"
}

Workflow configuration

Step 1: Set the Required Permissions

During the protocol's execution, you must obtain a JSON Web Token (JWT) from GitHub's OIDC provider. To request this token, ensure that the workflow is configured with the required permission.

1. Configure the specified permission in the workflow file:

permissions:
    id-token: write

Step 2: Pass the oidc-provider-name Input

The oidc-provider-name parameter specifies the OIDC configuration whose identity mapping should match the generated JWT claims.

1. Set the oidc-provider-name parameter to be the same as the Provider Name set in the OIDC configuration within the JFrog Platform.

Step 3: (Optional) Specify the oidc-audience Input

The oidc-audience input defines the intended recipients of the ID token (JWT), restricting access to authorized recipients within the JFrog Platform. By default, it is set to the GitHub repository owner's URL. This ensures that only workflows within the specified repository or organization can request an access token. Read more about it here.

Usage Example

- uses: jfrog/frogbot@v2
  env:
      JF_URL: ${{ vars.JF_URL }}
      JF_GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
      oidc-provider-name: frogbot-integration

Troubleshooting

Scan Failures Due to Token Expiration

When using OIDC integration, Xray or JFrog Advanced Security scans may fail if the token expires before the scans are complete. To prevent this, consider increasing the Token Expiration Time in the Identity Mapping Configuration to ensure the token remains valid for the entire scanning process. The required duration may vary based on the project's size.