{"id":15683112,"url":"https://github.com/tspascoal/gh-oidc-sub","last_synced_at":"2025-05-07T12:44:41.945Z","repository":{"id":61751112,"uuid":"554380561","full_name":"tspascoal/gh-oidc-sub","owner":"tspascoal","description":"GitHub CLI extension to configure Actions OIDC subject templates","archived":false,"fork":false,"pushed_at":"2024-06-18T17:08:36.000Z","size":40,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-31T10:11:18.182Z","etag":null,"topics":["gh-extension","github","github-actions","oidc"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tspascoal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-19T18:06:52.000Z","updated_at":"2024-06-18T17:08:39.000Z","dependencies_parsed_at":"2024-10-03T17:12:34.571Z","dependency_job_id":null,"html_url":"https://github.com/tspascoal/gh-oidc-sub","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tspascoal%2Fgh-oidc-sub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tspascoal%2Fgh-oidc-sub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tspascoal%2Fgh-oidc-sub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tspascoal%2Fgh-oidc-sub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tspascoal","download_url":"https://codeload.github.com/tspascoal/gh-oidc-sub/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252881293,"owners_count":21819141,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gh-extension","github","github-actions","oidc"],"created_at":"2024-10-03T17:02:12.756Z","updated_at":"2025-05-07T12:44:41.919Z","avatar_url":"https://github.com/tspascoal.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GH oidc-sub\n\n\u003e Manage GitHub Actions OIDC subject custom templates within an organization or repository.\n\n## Why?\n\nOpenID connect (ODIC) is a standard for authentication and authorization. OIDC support in GitHub Actions enables secure cloud deployments using short-lived tokens that are automatically rotated for each deployment.\n\nYou can configure ODIC to configure the [subject claim format](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-subject-claims-for-an-organization-or-repository) within the OIDC tokens, by defining a customization template at either org or repo levels. Once the configuration is completed, the new OIDC tokens generated during each deployment will follow the custom format.\n\nThis enables organization \u0026 repository admins to standardize OIDC configuration across their cloud deployment workflows that suits their compliance \u0026 security needs.\n\n## Installation\n\n### Prerequisites\n\n- `Bash`\n- `jq` (optional but recommended)\n- `curl`\n\n### gh cli extension\n\nYou can install `oidc-sub` as a [gh cli](https://github.com/cli/cli) extension!\n\n```console\ngh extensions install tspascoal/gh-oidc-sub\n```\n\n#### Verify installation\n\n```console\t\ngh oidc-sub --help\n```\n\n## Usage\n\n### Operations\n\nThis extension supports the following operations:\n\n- get\n- set\n- use-default (or usedefault)\n- list-claims\n- list-repos\n\nTo understand the semantics of claim customizaiton, please read [Customizing the subject claims for an organization or repository](https://docs.github.com/en/enterprise-cloud@latest/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-subject-claims-for-an-organization-or-repository).\n\nPay special attention of the opt in semantics for repository customizations. Setting the organization may not be enough, quoting from GitHub docs:\n\n\u003e [!Note]\n\u003e When the organization template is applied, it will not affect any action workflows in existing repositories that already use OIDC. For existing repositories, as well as any new repositories that are created after the template has been applied, the repository owner will need to opt-in to receive this configuration, or alternatively could apply a different configuration specific to the repo. For more information, see \"[Set the customization template for an OIDC subject claim for a repository.](https://docs.github.com/en/enterprise-cloud@latest/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)\"\n\n#### list-claims\n\nGets the list of sub claims that can used in the template.\n\nYou can read more about the claims and their semantic in the [Understanding the OIDC token](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token).\n\n#### get\n\nGet the current OIDC subject configuration for an organization or repository.\n\nFor organizations it will throw an error if no claims have ever been customized.\n\nFor repositories it will return if the default subject is used and the list of claims.\n\nThe output will always be the full result of the API call (in JSON), you can use the `--jq` parameter with a `jq` expression to filter the output (no need for `jq` to be installed).\n\n#### Examples\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\nGet the organization custom OIDC claims for an organization that never had subject claims customized.\n\u003c/summary\u003e\n\n```console\n$ gh oidc-sub get --org mona\n{\n  \"message\": \"No Actions OIDC custom sub claim template found for the organization tspascoal-demo2\",\n  \"documentation_url\": \"https://docs.github.com/rest/actions/oidc#get-the-customization-template-for-an-oidc-subject-claim-for-an-organization\"\n}\ngh: No Actions OIDC custom sub claim template found for the organization tspascoal-demo2 (HTTP 404)\n```\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nGet the organization custom OIDC claims for an organization with subject claims customized.\n\u003c/summary\u003e\n\n```console\n$ gh oidc-sub get --org mona\n{\n  \"include_claim_keys\": [\n    \"repo\"\n  ]\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\nGet repository custom OIDC claims for an repo with subject claims customized, returning only the claims.\n\u003c/summary\u003e\n  \n```console\n$ gh oidc-sub get --repo mona/repo\n{\n  \"use_default\": false,\n  \"include_claim_keys\": [\n    \"repo\"\n  ]\n}\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nGet repository custom OIDC claims for an repo with subject claims customized, returning only the claims.\n\u003c/summary\u003e\n \n```console\n$ gh oidc-sub get --repo mona/repo --jq '.include_claim_keys'\n[ \"repo\" ]\n```\n\u003c/details\u003e\n\n#### set\n\nSet the OIDC subject configuration for an organization or repository.\n\nFor repository the `--subs` paramemeter is optional. If you don't set the list of claims, we will opt out out of the default claims and organization claims will be used instead, if you do specificy the subs than those will be used instead of the organization claims.\n\n\u003e The claims keys are not validated so be sure you are not mispelling any claim.\n\n##### Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e\nSet custom claims template for an organization\n\u003c/summary\u003e\n\n```console\n$ gh oidc-sub set --org mona --subs \"org,repo,job_workflow_ref\"\n{}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\nSet custom claims template for a repository\n\u003c/summary\u003e\n\n```console\n$ gh oidc-sub set --repo mona/repo --subs \"org,repo\"\n{}\n```\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nConfigure repository to use organization custom claims template\n\u003c/summary\u003e\n\n```console\n$ gh oidc-sub set --repo mona/repo\n{}\n```\n\u003c/details\u003e\n\n#### use-default\n\nIf you want to revert a customization, you can use this command.\n\nFor organizations it sets the customization subject claims to `repo,context`\n\nFor repositories it disables the customization subject claims and configures it to use the default ones (`use_default: true`)\n\n##### Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e\nConfigure organization customization subject claims to the default value\n\u003c/summary\u003e\n\n```console\n$ gh oidc-sub use-default --org mona\n{}\n\n$ gh oidc-sub get --org mona\n{\n  \"include_claim_keys\": [\n    \"repo\",\n    \"context\"\n  ]\n}\n```\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\nConfigure repository customization subject claims to use the defaults\n\u003c/summary\u003e\n\n```console\n$ gh oidc-sub use-default --repo mona/repo\n{}\n\n$ gh oidc-sub get --repo mona/repo\n{\n  \"use_default\": true\n}\n```\n\u003c/details\u003e\n\n#### list-repos\n\nList the current configuration for all repositories in a given organization. This will give a full view which repos are using the default configuration and which ones are using customized claims.\n\nThe output will be a TSV with:\n- Repository\n- If it uses default claims\n- Claims list (comma separated)\n\n#### Examples\n\n\u003cdetails\u003e\n\n\u003csummary\u003eGet organization repositories oidc claims template customization\u003c/summary\u003e\n\n```console\n$ gh oidc-sub list-repos --org mona\nrepository\tuse default\tclaims\ntspascoal-oidc/customized\tfalse\trepo,ref\ntspascoal-oidc/usingdefault\ttrue\n```\n\n\u003c/details\u003e\n\n### Parameters\n\nCompatible with [GitHub Enterprise Server](https://github.com/enterprise). ([see](https://cli.github.com/manual/) for more details)\n\n```text\n\nUsage: \n    \u003ccommand\u003e [options]:\n        get (--org ORG | --repo owner/repo) [--jq JQ_FILTER]\n        set (--org ORG | --repo owner/repo) --subs \"SUBS LIST\"\n        use-default (--org ORG | --repo owner/repo) (Note: usedefault is also supported)\n        list-claims\n        list-repos (--org ORG)\n\nCommand:\n  get - Gets the value of the sub customization\n  set - Sets the value of the sub customization \n  use-default - Use default value instead of a customization\n  list-claims - Lists the claims available for customization\n  list-repos - Generates a tsv with all repo configurations. It has two fields: if repo uses default claims and the claims list.\n\nOptions:\n    -h, --help                    : Show script help\n    -o, --org                     : Name of the organization to get/set sub\n    -r, --repo,--repository       : Name of the repo to get/set sub\n    -q, --jq                      : JQ expression to filter the get output (optional)\n    -s, --subs                    : The list of sub customization to set (comma separated). \n                                    Mandatory for organization set operation and optional for repo set operation.\n\nDescription:\n\nAllows setting and getting OIDC sub customization claims for an organization or a repo.\n\nLearn more on https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect\n\nBy default the output JSON returned by the API calls. You can use the --jq option to filter the output.\n\nExamples:\n  # Get the sub customization for the organization mona\n  get --org mona\n  # Sets the sub customization for the organization mona with claims repository_id,environment\n  set --org mona --sub \"repo,context,job_workflow_ref\"\n  # Gets the list of claims available for customization\n  list-claims\n  # get only the claims list\n  get --org mona --jq \".include_claim_keys\" \n  # Gets the settings for all repos in a org\n  list-repos --org mona  \n```\n\n## Permissions\n\nThe following scopes are required to use this command:\n\n- Organization:\n\n  - `read:org` To get custom claims\n  - `write:org` To set custom claims\n\n- Repository:\n\n  - `repo` To get and set custom claims\n\nIf you are unsure which scopes you have, you can get the list of scopes of the logged in user with one of the following commands:\n\n```\n$ gh auth status\ngithub.com\n  ✓ Logged in to github.com as XXXXXX  (/home/XXXXXXXX/.config/gh/hosts.yml)\n  ✓ Git operations for github.com configured to use https protocol.\n  ✓ Token: gho_************************************\n  ✓ Token scopes: admin:org, delete_repo, gist, repo, workflow\n```\n\n```console\n$ gh api user -i --silent | grep -i 'X-Oauth-Scopes:'\nX-Oauth-Scopes: admin:org, delete_repo, gist, repo, workflow\n```\n\nTo get more permissions you can use the [gh auth refresh](https://cli.github.com/manual/gh_auth_refresh) command with `--scopes` parameter.\n\n## Debugging\n\nTo understand which subject claim is being sent to the OIDC provider from a GitHub action, you can run the following command in a workflow step:\n\n```sh\n  curl -s -H \"Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN\" \"$ACTIONS_ID_TOKEN_REQUEST_URL\" \\\n    -H \"Accept: application/json; api-version=2.0\" \\\n    -H \"Content-Type: application/json\" | cut -f2 -d . | base64 -d | jq -r .sub\n```\n\nA simpler alternative would be enabling debug logging since actions tend to emit more logs. You can enable debug logs by setting the `ACTIONS_STEP_DEBUG` environment variable to `true`.\n\nFor example the [azure/login](https://github.com/azure/login) action when running in debug mode will log the subject claim being sent to Azure.\n\nThis an example of `azure/login` logs snippet of repo with a customized claim `repo,ref` :\n```text\nRun Azure/login@v1.4.6\nUsing OIDC authentication...\nFederated token details: \n issuer - https://token.actions.githubusercontent.com \n subject claim - repo:mona/repo:ref:refs/heads/main\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftspascoal%2Fgh-oidc-sub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftspascoal%2Fgh-oidc-sub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftspascoal%2Fgh-oidc-sub/lists"}