Utilizing GitHub OIDC as an Authentication Method through CyberArk Conjur’s authn-jwt

Utilizing GitHub OIDC as an Authentication Method through CyberArk Conjur’s `authn-jwt`

Overview: This documentation demonstrates how to use GitHub's OpenID Connect (OIDC) as an authentication method in Conjur Cloud & Self-Hosted Enterprise using the authn-jwt authenticator. The process involves configuring the JWT authenticator, mapping claims from the GitHub OIDC token to annotations in Conjur Cloud, and finally authenticating a workload.

Step 1: Configure GitHub OIDC with JWT Authenticator

Plan the Configuration:
- Claims Mapping: The GitHub OIDC token typically includes claims such as sub (subject), repository, actor, and ref. These claims can be mapped to Conjur Cloud annotations to create a secure authentication flow.
- Annotations: Use the repository, actor, and ref claims to define workload identities. These claims ensure that only specific GitHub workflows can authenticate to Conjur Cloud.

Example Policy Configuration:

- !policy
  id: github-oidc
  body:
    - !webservice

    - !variable
      id: jwks-uri

    - !variable
      id: token-app-property

    - !variable
      id: identity-path

    - !variable
      id: issuer

    - !group apps

    - !permit
      role: !group apps
      privilege: [ read, authenticate ]
      resource: !webservice

Explanation:
- jwks-uri: URL for retrieving the public key from GitHub.
- token-app-property: Maps to a claim like repository or actor.
- identity-path: Path to workload identity.
- issuer: GitHub OIDC provider URL (https://token.actions.githubusercontent.com).

Load Policy into Conjur:

conjur policy load -f /path/to/github-oidc-policy.yaml -b conjur/authn-jwt

Step 2: Populate Variables

Populate the required variables in Conjur using the Conjur CLI:

conjur variable set -i conjur/authn-jwt/github-oidc/jwks-uri -v https://token.actions.githubusercontent.com/.well-known/openid-configuration
conjur variable set -i conjur/authn-jwt/github-oidc/token-app-property -v repository
conjur variable set -i conjur/authn-jwt/github-oidc/identity-path -v data/github-apps
conjur variable set -i conjur/authn-jwt/github-oidc/issuer -v https://token.actions.githubusercontent.com

Step 3: Create Workload Identity

Create a workload identity in Conjur Cloud that matches the claims in the GitHub OIDC token. Here's an example token payload and how to map it:

Example OIDC Token Payload:

{
  "sub": "repo:your-organization/your-repo:ref:refs/heads/main",
  "repository": "your-organization/your-repo",
  "actor": "github-username",
  "ref": "refs/heads/main",
  "iss": "https://token.actions.githubusercontent.com"
}

Workload Policy Mapping:

- !policy
  id: github-apps
  body:
    - !group

    - &hosts
      - !host
        id: your-repo-main
        annotations:
          authn-jwt/github-oidc/repository: your-organization/your-repo
          authn-jwt/github-oidc/actor: github-username
          authn-jwt/github-oidc/ref: refs/heads/main
          
    - !grant
      role: !group
      members: *hosts

Load the policy:

conjur policy load -f /path/to/github-oidc-workload.yaml -b data

Step 4: Enable the JWT Authenticator

Enable the JWT authenticator for GitHub OIDC in Conjur:

conjur authenticator enable --id authn-jwt/github-oidc

Step 5: Send an Authentication Request

To authenticate, send a POST request to the authn-jwt endpoint:

curl -k --request POST 'https://<subdomain>.secretsmgr.cyberark.cloud/api/authn-jwt/github-oidc/conjur/authenticate' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header "Accept-Encoding: base64" \
--data-urlencode 'jwt=<your_jwt_token>'

Summary: This guide outlines how to integrate GitHub OIDC with Conjur Cloud using the authn-jwt authenticator. By mapping GitHub token claims to Conjur annotations and configuring the necessary policies, you can securely authenticate GitHub workflows to Conjur Cloud.

infamousjoeg/GitHubOIDC-CyberArkConjur.md