GitHub PATs
Azure pipelines may sometimes be required to perform an action in GitHub from a pipeline, for example, creating a new release as is the case with hmcts/jenkins-packer.
Because we utilise single sign on (SSO) to GitHub with our Microsoft Entra ID, personal access tokens (PATs) must be authorised with SSO.
Why is this important?
You may come across an error in an Azure Pipeline like the following:
##[error]Error: Resource protected by organization SAML enforcement. You must grant your Personal Access token access to this organization.
If you do get this error, this means you need to authorise the PAT for use with SSO.
GitHub have an official guide on how to do this which can be found here.
Which account are PATs created under?
We have a central account HMCTS Platform Operations that we use to create PATs that will be used by multiple pipelines within the Azure DevOps
organisation, applications used by SOC team, etc.
The sign in details for this account can be found in the rpe-prod Azure Key Vault. You will need to find three secrets:
github-bot-owner-username, github-bot-owner-password, and github-bot-owner-recovery-codes.
The username is currently set as hmcts-platform-operations.
Once you get signed into GitHub with this account, go to Settings > Developer settings > Personal access tokens
and view existing PAT tokens or create a new one.
To avoid using the recovery codes, you can set up MFA on your phone.
For MFA, the secret key and account name have been saved in the keyvault as well. Look for github-bot-owner-totp-secret.
You can set up the MFA code on your phone on an authenticator app of your choosing, though it should support entering the secret key manually.
Select the option to create the code manually in the app rather than scanning a QR code.
You should then have the codes being generated on your phone that you can use to authenticate.
If you only need this one time, it would be best to remove this from your phone again.
NOTE: If resetting the MFA, do not use MS authenticator/Google authenticator as these apps don’t allow you to view the secret key after setting it up. Use an app like Aegis Authenticator or Ente Authenticator instead. Once added to the app, view the secret key and update the github-bot-owner-totp-secret value in Key Vault. After it’s been reset, you should be able to sign in using MS authenticator/Google authenticator.
How can I perform single-sign-on to GitHub with the owner account?
The github bot owner account is backed by an Entra ID account. The details for this are also in the keyvault.
Just look for sso in the secret name. There is a username and password.
For MFA, the secret key (github-bot-owner-sso-totp-secret) and account name github-bot-owner-sso-totp-account-name) have been saved in the keyvault as well.
You can set up the MFA code on your phone on an authenticator app of your choosing.
Select the option to create the code manually in the app rather than scanning a QR code.
You should then have the codes being generated on your phone that you can use to authenticate.
If you only need this one time, it would be best to remove this from your phone again.
Phone backup method
There is a phone number configured on the account as a backup. This will call Tim Jacomb’s phone to approve the sign in request.
This should only be required if the MFA code method is not working.
Recovery codes
Recovery codes have been generated but these should only be used as a last resort.
If you use a recovery code, regenerate them after you’ve regained access.