From a70fc9ce21166bc9219fa3ae04c74336d5ca9da2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alain=20H=C3=A9la=C3=AFli?= Date: Thu, 16 May 2024 14:47:00 +0200 Subject: [PATCH] Moar documentation --- .github/workflows/deploy-staging.yml | 2 +- README.md | 45 +++++++++++++++++++++++++++- 2 files changed, 45 insertions(+), 2 deletions(-) diff --git a/.github/workflows/deploy-staging.yml b/.github/workflows/deploy-staging.yml index 2ec44a6..085d1c2 100644 --- a/.github/workflows/deploy-staging.yml +++ b/.github/workflows/deploy-staging.yml @@ -57,7 +57,7 @@ jobs: name: staging steps: - name: 'Az CLI login' - uses: azure/login@v1 + uses: azure/login@v2 with: client-id: ${{ secrets.AZURE_CLIENT_ID }} tenant-id: ${{ secrets.AZURE_TENANT_ID }} diff --git a/README.md b/README.md index 6ca0124..458e6a2 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,46 @@ +Automate the approval of fine grained Personal Access Tokens in GitHub. You can now define a maximum duration for fine grained PAT and automatically approve or reject them. -# Config +[!NOTE] Organization admins can still create long lived PATs. + +# Usage + +- Install the application from [my staging environment](https://github.com/apps/gh-patol-staging) onto your organization and authorize it to access the `.github-private` repository. The application is only authorized to access the `gh-patrol.yaml` file, nothing else. +- Restrict the Personal access token settings of your organization so that only fine grained tokens are allowed and require administrator authorization. +- Create a `gh-patrol.yaml` file in the `.github-private` repository of your organization with a content similar to the following: +```yaml +- name: trusted users + users: + - user1 + - user2 + max_duration: 2 +- name: super trusted users + users: + - user3 + - user4 + max_duration: 5 +- name: other users + users: + - all + max_duration: 1 +``` + +Users now need to create a fine grained PAT with a short enough duration. When a user requests a personal access token, the application will check the `gh-patrol.yaml` file to determine the maximum duration of the token. If the user is not listed in the file, the token will be granted for a maximum of 1 day. If the user is listed in the file, the token will be granted for the maximum duration specified in the file. When their token expires, users need to log back to the GitHub website and regenerate the token. It will go through the same approval process but its value will not change. + +Cloning repos using `git clone https://github_pat_xxxxxx@github.com//`. + +[!WARNING] Users still can use SSH keys to clone repos without the need for a PAT. If you want to enforce the use of PATs, you need to force the use of HTTPS URLs in your organization. Currently, the only way to do this is: +- use a VPN and block the SSH port +- configure IP allow lists in your organization to force the use of the VPN + +# Deploy your own instance of GitHub Patrol + +Create a clone of this repository and follow the instructions below to deploy your own instance of GitHub Patrol. + +## Azure Function App +Create an Azure Function App. You will need to downlaod the publish profile from the Azure Portal. + +## Configure the OIDC authentication +The deployment workflow needs to authenticate with Azure to deploy the Azure Function App. This is done using OIDC. Follw the instructions [here](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Clinux) to configure the OIDC authentication and note the following values: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID`. ## GitHub App @@ -32,6 +73,8 @@ After creating the app, note the App ID and download the private key. ```bash base64 -i .private-key.pem ``` +- `AZURE_FUNCTIONAPP_PUBLISH_PROFILE` - The publish profile downloaded from the Azure Function App within the Azure Portal. + ### Envionment variables (for `production` and `staging` environment) - `APP_ID` - The GitHub App ID. ### Repository secret