Come Configurare OIDC con Terraform per GitHub Enterprise Server

Supponiamo tu abbia un'istanza di GitHub Enterprise Server e voglia configurare GitHub Actions. Una parte di questa configurazione consiste nel fornire un modo per Actions di archiviare informazioni sui log, artefatti e pacchetti. GitHub Actions supporta l'archiviazione di questi dati su AWS S3, Azure Blob Storage o Google Cloud Storage. È possibile per GitHub Enterprise Server usare l'autenticazione basata su credenziali per accedere a questi servizi di storage, ma è raccomandato usare OpenID Connect (OIDC) per ridurre il rischio di compromissione delle credenziali.

In questo articolo ti mostrerò come configurare OIDC con Terraform per GitHub Enterprise Server. OIDC potrebbe ovviamente essere configurato manualmente, ma usare Terraform ha alcuni vantaggi:

È molto più rapido della creazione manuale delle risorse.
È più semplice tenere traccia delle modifiche alla configurazione e replicarla in altri ambienti.
Una volta che la configurazione è in atto, è difficile romperla accidentalmente.

Cos'è GitHub Enterprise Server e GitHub Actions?

Prima di entrare nei dettagli su come configurare OIDC con Terraform per GitHub Enterprise Server, capiamo prima cosa sono GitHub Enterprise Server e GitHub Actions. GitHub Enterprise Server è la versione on-premises di GitHub — immagina GitHub.com ma installato sui server di un'azienda: è qualcosa che le aziende userebbero se volessero avere più controllo e mantenere il codice privato. GitHub Actions è una funzionalità di GitHub che consente di automatizzare attività. Ad esempio, quando qualcuno aggiunge nuovo codice a un progetto, GitHub Actions può eseguire automaticamente controlli su questo codice, compilare l'applicazione e distribuirla, e praticamente qualsiasi altra cosa che potresti automatizzare con gli script.

Perché usare OIDC?

OpenID Connect (OIDC) è un protocollo di autenticazione che estende OAuth 2.0, fornendo un metodo di autenticazione robusto e standardizzato. OIDC consente a un'applicazione client di richiedere e ricevere informazioni sulla sessione e l'identità di un utente autenticato. Questo avviene tramite uno scambio sicuro di token, che spesso coinvolge un ID token in formato JWT (JSON Web Token). In breve, OIDC ti consente di autenticare gli utenti senza dover archiviare le loro credenziali.

Sia GitHub Enterprise Server che tutti i principali provider cloud supportano OIDC. Dobbiamo solo fornire la configurazione per farli comunicare. Ecco un semplice diagramma di come funziona:

Configurare le risorse cloud per usare GitHub Actions su GitHub Enterprise Server con OIDC può essere un compito lungo e impegnativo a causa delle stringenti esigenze di sicurezza che richiedono una configurazione precisa. Per semplificare il processo, ho avviato il progetto lucavallin/tf-ghes-oidc. Questo repository, pur non essendo destinato all'uso in produzione, include le configurazioni Terraform necessarie per creare risorse nei tre principali servizi cloud enterprise: Azure, Amazon Web Services (AWS) e Google Cloud Platform (GCP).

Questa configurazione Terraform è progettata per essere eseguita da un singolo utente ( anziché da un Service Account) che ha effettuato l'accesso al proprio provider cloud scelto tramite la CLI corrispondente su Linux.

Per iniziare, è necessario avere un progetto o una configurazione simile su Azure, AWS o Google Cloud, specificamente per la creazione di risorse. Inoltre, è necessario l'accesso all'istanza di GitHub Enterprise Server, sia attraverso l'interfaccia utente che via SSH. Assicurati che le tue chiavi SSH siano correttamente configurate nella Management Console dell'istanza per garantire questo accesso.

Utilizzo

Per distribuire le risorse, segui questi passaggi:

Installa Terraform e le CLI del provider cloud eseguendo lo script scripts/install.sh. Se necessario, aggiorna il file di profilo della console (come ~/.bashrc) per abilitare l'uso della CLI senza richiedere il percorso completo.
Inizializza le CLI del (o dei) provider cloud scelto e autenticati con il tuo provider cloud.
Naviga nella directory src.
Esegui terraform init per inizializzare Terraform e installare le dipendenze necessarie.
Il backend Terraform predefinito è impostato su local, il che significa che lo state di Terraform viene archiviato localmente. Questo può essere modificato con qualsiasi backend supportato.
Cambia il nome di terraform.tfvars.example in terraform.tfvars e modifica le variabili per adattarle alla tua configurazione. Il file terraform.tfvars contiene la configurazione per i file Terraform.
Esegui terraform plan -out=plan per preparare la creazione delle risorse. Questo piano viene salvato nel file plan per il passaggio successivo.
Usa terraform apply plan per avviare la creazione delle risorse.
La configurazione necessaria per abilitare Actions su GitHub Enterprise Server con OIDC nella Management Console di GitHub Enterprise Server viene fornita al termine del processo, come indicato dagli output specificati in src/outputs.tf.
Le istruzioni aggiuntive specifiche per ciascun provider cloud sono dettagliate più avanti.

Nota: Se stai solo sperimentando con GitHub Actions su GitHub Enterprise Server con OIDC, usa terraform destroy per eliminare tutte le risorse create da Terraform per prevenire spese indesiderate.

Informazione Utile: La configurazione nel repository viene verificata tramite una GitHub Action in .github/terraform.yml, che ne garantisce l'accuratezza.

Variabili

La configurazione Terraform richiede valori per le variabili elencate in src/variables.tf. Il file terraform.tfvars.example serve da guida. Rinominando terraform.tfvars.example in terraform.tfvars, puoi fornire le informazioni necessarie come segue:

GitHub Enterprise Server_NAME: Nome dell'istanza GitHub Enterprise Server (es. my-GitHub Enterprise Server-instance)
GitHub Enterprise Server_HOSTNAME: URL dell'istanza GitHub Enterprise Server senza 'https://' (es. my-GitHub Enterprise Server-instance.com)
AZURE_SUBSCRIPTION_ID: ID della Subscription Azure da usare
AZURE_REGION: Regione per l'Account di Storage Azure (predefinita: West Europe)
AZURE_STORAGE_ACCOUNT_TIER: Tier per l'Account di Storage Azure (predefinito: Standard)
AZURE_STORAGE_ACCOUNT_REPLICATION_TYPE: Tipo di Replica per l'Account di Storage Azure (predefinito: LRS)
AWS_REGION: Regione AWS per le Risorse OIDC (predefinita: eu-north-1)
AWS_OIDC_THUMBPRINT: Thumbprint dell'istanza GitHub Enterprise Server per la configurazione OIDC su AWS
GCP_PROJECT_ID: ID del Progetto Google Cloud da usare
GCP_REGION: Regione Google Cloud per le Risorse OIDC (predefinita: EUROPE-WEST4)

Provider Cloud

Azure

Prima di avviare la creazione delle risorse in Azure, segui questi passaggi preliminari:

Assicurati di avere una subscription Azure disponibile.
Esegui az login --use-device-code per autenticarti con Azure.
Se la subscription Azure specifica che desideri usare non è già attiva, impostala usando az account set --subscription="SUBSCRIPTION_ID".
Modifica la variabile AZURE_SUBSCRIPTION_ID nel file terraform.tfvars per corrispondere all'ID della subscription Azure scelta per la distribuzione delle risorse.

Le risorse necessarie per Azure sono dettagliate nel file src/azure.tf. La configurazione essenziale per configurare Actions su GitHub Enterprise Server con OIDC nella Management Console viene prodotta come output: azure_tenant_id, azure_client_id, azure_storage_account_name e azure_blob_endpoint_suffix.

Terraform crea le seguenti risorse per Azure:

Un Resource Group per le risorse OIDC
Un Account di Storage da usare per i dati di Actions
Un'Applicazione Azure AD per GitHub Enterprise Server
Un Service Principal per l'Applicazione Azure AD
Un Role Assignment per il Service Principal

AWS

Per configurare le risorse su AWS, devi seguire questi passaggi:

In AWS, crea un set di Access Keys per il tuo account. Puoi trovarlo nella sezione Security Credentials (vedi la documentazione).
Esegui il comando aws configure e inserisci gli Access Keys appena creati. Questo passaggio collega la AWS CLI al tuo account AWS e crea i file ~/.aws/config e ~/.aws/credentials richiesti dal provider Terraform AWS.
Crea un nuovo Thumbprint per la tua istanza GitHub Enterprise Server come descritto nella documentazione. Questo Thumbprint è necessario per la configurazione OIDC.

Questo repository fornisce anche lo script scripts/thumbprint.sh che genera il Thumbprint. Usalo come segue:

bash

# ./script/thumbprint.sh <GitHub Enterprise Server_HOSTNAME>
$ ./script/thumbprint.sh my-GitHub Enterprise Server-instance.example.com
$ GitHub Enterprise Server Thumbprint: AB1234567890ABCDEF1234567890ABCDEF123456 # Thumbprint

Aggiorna le variabili AWS_REGION e AWS_OIDC_THUMBPRINT nel file terraform.tfvars. Impostale sulla regione AWS scelta per la distribuzione delle risorse e sul Thumbprint dell'istanza GitHub Enterprise Server per la configurazione OIDC.

Le risorse necessarie per AWS sono dettagliate nel file src/aws.tf. La configurazione essenziale per configurare Actions su GitHub Enterprise Server con OIDC nella Management Console viene prodotta come output: aws_s3_bucket, aws_role e aws_region.

Terraform crea le seguenti risorse per AWS:

Un Bucket S3 da usare per i dati di Actions
Un OpenID Connect Provider per GitHub Enterprise Server
Un IAM Role per GitHub Enterprise Server
Una IAM Policy per l'IAM Role

Google Cloud

Prima di avviare la creazione delle risorse in un progetto Google Cloud, devi seguire questi passaggi preparatori:

Assicurati che il progetto sia collegato a un Billing Account.
Esegui gcloud init per avviare la Google Cloud CLI e scegli il progetto dove prevedi di distribuire le risorse.
Esegui gcloud auth application-default login per autenticare la CLI con Google Cloud.
Modifica la variabile GCP_PROJECT_ID nel file terraform.tfvars per corrispondere all'ID del progetto Google Cloud scelto per la distribuzione delle risorse.

Le risorse necessarie per Google Cloud sono dettagliate nel file src/gcp.tf. La configurazione essenziale per configurare Actions su GitHub Enterprise Server con OIDC nella Management Console viene prodotta come output: gcp_service_url, gcp_bucket_name, gcp_workload_identity_provider_id e gcp_service_account.

Terraform esegue le seguenti operazioni per Google Cloud:

Abilita i servizi iamcredentials.googleapis.com e storage.googleapis.com per il progetto.
Crea un Workload Identity Pool (Provider) per GitHub Enterprise Server
Crea un Service Account per GitHub Enterprise Server
Assegna i ruoli roles/iam.workloadIdentityUser, roles/storage.objectAdmin e roles/iam.serviceAccountTokenCreator al Service Account
Crea un Storage Bucket da usare per i dati di Actions

Miglioramenti alla Configurazione Terraform

In futuro, potrei migliorare le cose separando le impostazioni per i diversi servizi cloud come Azure, AWS e Google Cloud in parti separate. Questo renderebbe più facile e flessibile lavorare con ciascuno individualmente. Aiuterebbe gli utenti a gestire le proprie impostazioni per ogni servizio cloud da soli. In questo modo, se stai lavorando con un solo servizio cloud, le cose sarebbero più fluide.

Riepilogo

In questo articolo ti ho guidato attraverso la configurazione di OpenID Connect (OIDC) con Terraform per GitHub Enterprise Server. GitHub Enterprise Server è come un GitHub privato, installato sui server di un'azienda per un maggiore controllo e privacy. GitHub Actions, una funzionalità del prodotto, automatizza attività come i controlli del codice e le distribuzioni. L'articolo spiega come OIDC, un protocollo di autenticazione che estende OAuth 2.0, migliora la sicurezza consentendo l'autenticazione degli utenti senza archiviare le credenziali. È supportato da GitHub Enterprise Server e dai principali provider cloud. Infine abbiamo dato un'occhiata a lucavallin/tf-ghes-oidc, un progetto Terraform per semplificare la configurazione di OIDC sui principali servizi cloud come Azure, AWS e GCP. Il repository fornisce passaggi dettagliati per configurare l'ambiente Terraform ed eseguire le configurazioni, insieme a istruzioni specifiche per ogni provider cloud, sottolineando la semplicità, la sicurezza e l'efficienza di questo approccio.

Come Configurare OIDC con Terraform per GitHub Enterprise Server

Cos'è GitHub Enterprise Server e GitHub Actions?

Perché usare OIDC?