diff --git a/README.md b/README.md index 2d6c8d643..09154e45a 100644 --- a/README.md +++ b/README.md @@ -97,44 +97,42 @@ If you have multiple Config Tokens as secrets, you can use all of them in the wo |----------------------------------------------------------------------------------------------------------------------------------------------------------| ## Connect using OpenID Connect -Sensitive connection details of the JFrog platform (i.e. the access token) used by JFrog CLI can be auto-generated by the action itself instead of storing it as a secret in GitHub. -This is achieved by utilizing the OpenID-Connect (OIDC) protocol, that can authenticate the workflow issuer and provide a valid access token, provided only the JF_URL environment variable (as a secret). -There are several steps to perform **once** in order to use OIDC protocol: -1. [**Configure an OIDC Integration**](https://jfrog.com/help/r/jfrog-platform-administration-documentation/configure-an-oidc-integration): this step sets an integration between the Action to the JFrog platform. +The sensitive connection details, such as the access token used by JFrog CLI on the JFrog platform, 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, requiring only the JF_URL environment variable. +To utilize the OIDC protocol, there are several **one-time** steps that need to be performed: +1. [**Configure an OIDC Integration**](https://jfrog.com/help/r/jfrog-platform-administration-documentation/configure-an-oidc-integration): This phase sets an integration between the Action to the JFrog platform. -| Important: 'Provider Name' value is the value you must pass as provider_name input in step 4.
'Audience' field is NOT the 'aud' claim you can insert to the identity-mapping in step 2. The only claim that will be checked are those in the Claims Json that is created in step 2. | +| Important: The value specified as the 'Provider Name' should be used as the provider_name input in step 4.
The 'Audience' field does not represent the 'aud' claim for insertion into the identity-mapping in step 2. Only the claims included in the Claims Json created during step 2 will be validated. | |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -2. [**Configure an identity mapping**](https://jfrog.com/help/r/jfrog-platform-administration-documentation/configure-identity-mappings): this step creates a reference token to authenticate with the JFrog platform - We define the details that enable the server to authenticate the action issuer, and provide him an adequate access token. - You can define any list of valid claims in order to authenticate the request. You can check a list of the possible claims [here](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token). +2. [**Configure an identity mapping**](https://jfrog.com/help/r/jfrog-platform-administration-documentation/configure-identity-mappings): This phase generates a reference token for authenticating against the JFrog platform. It involves defining the necessary details to enable server authentication of the action issuer and granting the issuer an appropriate access token. + 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](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token). Example Claims JSON: ```yml { "sub": "repo:my-user-name/project1:ref:refs/heads/main", - "aud": ["https://github.com/my-user-name"], + "aud": "https://github.com/my-user-name", "ref": "refs/heads/main", "repository": "my-user-name/project1", "iss": "https://token.actions.githubusercontent.com" } ``` -| Important: If you use 'aud' field as one of your claims you must set it inside a list in the claims JSON, but only allowed to pass a single value (see example above) | -|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| - -3. **Set required permissions**: as part of the protocol a JSON Web Token (JWT) must be obtained from GitHub's OIDC provider. In order to be able to request this token we must set the following permission in the workflow file: +3. **Set required permissions**: In the course of the protocol's execution, it's imperative to acquire a JSON Web Token (JWT) from GitHub's OIDC provider. To request this token, it's essential to configure the specified permission in the workflow file: ```yml permissions: id-token: write ``` -4. **Pass the 'provider_name' input to the Action (Required)**: 'provider_name' tells the process which predefined OIDC configuration's identity maps to look for the match between the JWT claims and identity-map claims. This input should contain the value of 'Provider Name' we set for the OIDC configuration. -5. **Pass the 'aud' input to the Action (Optional)**: 'aud' input specifies the intended recipients of an ID token (JWT), to ensure that only authorized recipients are able to access the cloud (Artifactory). By default, it holds the URL of the repository owner. - This value (if sent) will be passed as an argument to core.getIDToken(), which generates the JWT, and sets a condition that only workflows in the specified repository/organization can access the cloud role. Read more about it [here](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-audience-value). +4. **Pass the 'provider_name' input to the Action (Required)**: The 'provider_name' parameter designates the OIDC configuration whose one of its identity mapping should align with the generated JWT claims. This input needs to align with the 'Provider Name' value established within the OIDC configuration. +5. **Pass the 'aud' input to the Action (Optional)**: The 'aud' input defines the intended recipients of an ID token (JWT), ensuring access is restricted to authorized recipients for the cloud (Artifactory). By default, it contains the URL of the repository owner. + This value, if transmitted, will be used as an argument in core.getIDToken(), which generates the JWT. It enforces a condition, allowing only workflows within the designated repository/organization to access the cloud role. Read more about it [here](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-audience-value). ```yml - name: Install JFrog CLI uses: jfrog/setup-jfrog-cli@v3 env: JF_URL: ${{ secrets.JF_URL }} with: + provider_name: aud: ```