In dieser Anleitung wird beschrieben, wie Sie mit einer Workload Identity-Föderation Arbeitslasten authentifizieren, die außerhalb von Google Cloud ausgeführt werden, damit sie auf Mikrodienste zugreifen können, die von Cloud Run gehostet werden. Diese Anleitung richtet sich an Administratoren, die eine Workload Identity-Föderation mit ihrem vorhandenen Identitätsanbieter (IdP) einbinden möchten. Mit der Workload Identity-Föderation können Sie externe Arbeitslasten mit Arbeitslasten verbinden, die in Google Cloud ausgeführt werden. Mit Cloud Run können Sie zustandslose, containerisierte Mikrodienste ausführen.
In dieser Anleitung erfahren Sie, wie Sie Jenkins als externe Arbeitslast, Keycloak als IdP, Cloud Run und Workload Identity-Föderation konfigurieren. Nach Abschluss dieser Anleitung erfahren Sie, wie Sie mit der Workload Identity-Föderation Ihre Jenkins-Anwendung mithilfe der OpenID Connect-Authentifizierung bei Google Cloud authentifizieren.
Externe Arbeitslast mit Workload Identity-Föderation authentifizieren
Mit der Workload Identity-Föderation können Sie Arbeitslasten außerhalb von Google Cloud authentifizieren, ohne einen statischen Dienstkontoschlüssel zu verwenden. Dieses Feature kann von allen externen Arbeitslasten genutzt werden, die Dienste in Google Cloud nutzen müssen.
Mit der Workload Identity-Föderation können Sie Ihren IdP verwenden, um sich direkt bei Google Cloud zu authentifizieren. Für die Authentifizierung verwenden Sie OpenID Connect. Cloud Run akzeptiert OpenID Connect-Tokens von Ihrem IdP zur Authentifizierung.
Der Authentifizierungsprozess sieht bei Verwendung der Workload Identity-Föderation so aus:
- Ihre Authentifizierungsbibliothek (AUTHN) sendet eine JSON-Webtoken-Anfrage (JWT) an den IdP.
- Ihr IdP signiert die JSON-Webtokens (JWT). Die AUTHN-Bibliothek liest diese Daten aus einer Variablen.
- Die Bibliothek sendet einen POST-Befehl an den Security Token Service, der das signierte Token enthält.
- Der Security Token Service prüft den Anbieter des Workload Identity-Pools, den Sie zum Erstellen der Vertrauensstellung konfiguriert haben, und überprüft die Identität der Anmeldedaten.
- Der Security Token Service sendet ein föderiertes Token zurück.
- Die Bibliothek sendet das Token an IAM.
- IAM tauscht das Token gegen ein OpenID Connect-Token eines Dienstkontos aus. Weitere Informationen finden Sie unter OpenID Connect-ID-Tokens generieren.
- Die Bibliothek stellt das OpenID Connect-Token für Jenkins bereit.
- Jenkins verwendet dieses Token zur Authentifizierung bei Cloud Run.
Das folgende Diagramm zeigt den Authentifizierungsablauf:
Ziele
- Jenkins als externe Arbeitslast konfigurieren.
- Keycloak als IdP konfigurieren, der mit OpenID Connect kompatibel ist.
- Jenkins mit Keycloak verbinden.
- Cloud-Clientbibliotheken installieren, um das JWT-Token von Keycloak an Google Cloud zu senden.
- Google Cloud mit Keycloak und Jenkins verbinden.
- JWT für authentifizierten Nutzer von Keycloak abrufen.
Obwohl in dieser Anleitung Keycloak verwendet wird, können Sie einen beliebigen Identitätsanbieter verwenden, der OpenID Connect unterstützt, z. B. GitLab, Okta oder OneLogin.
Kosten
In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:
Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen.
Nach Abschluss der in diesem Dokument beschriebenen Aufgaben können Sie weitere Kosten vermeiden, indem Sie die erstellten Ressourcen löschen. Weitere Informationen finden Sie unter Bereinigen.
Hinweise
-
In the Google Cloud console, go to the project selector page.
-
Select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- Richten Sie einen Mikrodienst in Cloud Run ein. Weitere Informationen finden Sie unter Kurzanleitung: Container in Cloud Run bereitstellen.
Jenkins konfigurieren
Führen Sie diese Aufgaben in einer Nicht-Google Cloud-Umgebung aus, z. B. in Ihrer lokalen Umgebung oder in einer anderen Cloud.
Wenn Sie bereits einen Identitätsanbieter haben, der OpenID Connect und eine externe Arbeitslast unterstützt, können Sie diesen Schritt überspringen und mit Cloud-Clientbibliotheken installieren fortfahren.
Zum Simulieren einer externen Arbeitslast können Sie eine VM verwenden, auf der Jenkins installiert ist. Sie können Jenkins als Docker-Image ausführen oder direkt auf Ihrem Server installieren. Die folgenden Schritte zeigen, wie Sie es direkt auf dem Server installieren.
- Öffnen Sie auf einer VM Ihrer Wahl eine Befehlszeile.
Installieren Sie Java:
$ sudo apt update $ sudo apt install openjdk-11-jre $ java -version
Installieren Sie Jenkins:
curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo tee \ /usr/share/keyrings/jenkins-keyring.asc > /dev/null echo deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] \ https://pkg.jenkins.io/debian-stable binary/ | sudo tee \ /etc/apt/sources.list.d/jenkins.list > /dev/null sudo apt-get update sudo apt-get install jenkins
Prüfen Sie, ob Sie auf Port 8080 auf Ihren Jenkins-Server zugreifen können. Wenn Sie eine VM verwenden, die sich hinter einer Firewall befindet, achten Sie darauf, dass die entsprechenden Ports geöffnet sind.
Rufen Sie Ihr Administratorpasswort ab und richten Sie Jenkins ein. Eine Anleitung finden Sie unter Einrichtungsassistent nach der Installation.
Führen Sie zum Einrichten von SSL die folgenden Aktionen aus:
- Wenn Sie einen Domainanbieter haben, können Sie dessen Zertifizierungsstelle (CA) verwenden, um ein signiertes Zertifikat anzufordern. Alternativ können Sie ein kostenloses signiertes Zertifikat unter zerossl.com anfordern, das 90 Tage lang unter gültig ist.
Laden Sie die ZIP-Datei des Zertifikats herunter und übertragen Sie sie auf Ihren Server, auf dem Jenkins ausgeführt wird:
scp -i CERTFILE.pem -r CERTFILE.zip VM_FQDN:/home/USERNAME
Ersetzen Sie Folgendes:
CERTFILE
durch den Namen der Zertifikatsdatei, die Ihren öffentlichen Schlüssel enthält.VM_FQDN
durch den FQDN Ihres Servers außerhalb von Google Cloud.USERNAME
durch Ihren Nutzernamen.
Benennen Sie die Dateien um und generieren Sie eine pkcs12-Datei, die Jenkins verwenden kann:
openssl rsa -in KEYFILE.com.key -out KEYFILE.com.key
Ersetzen Sie
KEYFILE
durch den Namen der Zertifikatsdatei.
Aktualisieren Sie die Datei
/etc/sysconfig/jenkins
:Öffnen Sie die Datei in einem Texteditor.
vi /etc/sysconfig/jenkins
Setzen Sie
JENKINS_PORT
auf-1
.Setzen Sie
JENKINS_HTTPS_PORT
auf8443
.Fügen Sie unten in der Datei die folgenden Argumente hinzu:
JENKINS_ARGS="--httpsCertificate=/var/lib/jenkins/.ssl/CERTFILE.crt --httpsPrivateKeys=/var/lib/jenkins/.ssl/KEYFILE.pkcs1.key"
Ersetzen Sie Folgendes:
CERTFILE
durch den Dateinamen der Zertifikatsdatei im CRT-Format.KEYFILE
durch den Dateinamen des PKCS-Schlüssels.
Starten Sie den Jenkins-Server neu.
Prüfen Sie, ob Port 8443 in Ihrer Firewall geöffnet ist und greifen Sie über Port 8443 auf Jenkins zu.
Installieren Sie das Jenkins-Plug-in, das Sie benötigen, um Keycloak in Jenkins einzubinden. Sie können eine der folgenden Optionen auswählen:
Gehen Sie zum Installieren des Plug-ins so vor:
- Wählen Sie im Jenkins-Dashboard Manage Jenkins > Manage Plugins aus.
Wählen Sie Available aus und suchen Sie nach dem Plug-in Ihrer Wahl. Der folgende Screenshot zeigt den Plug-in-Manager mit ausgewähltem Tab Available.
Installieren Sie das Plug-in.
Keycloak konfigurieren
In dieser Anleitung verwaltet Keycloak die Nutzer, Gruppen und Rollen. Keycloak verwaltet Nutzer mit sogenannten Realms oder Bereichen.
Installieren Sie den Keycloak-Server auf der VM, die außerhalb von Google Cloud ausgeführt wird. Für diese Anleitung empfehlen wir die Installation von Keycloak aus einem Docker-Container.
Öffnen Sie die Keycloak Admin-Konsole.
Rufen Sie Realm settings auf.
Prüfen Sie auf dem Tab General, ob die Felder so festgelegt sind:
- Enabled: ON
- User-Managed Access: OFF
- Endpoints: OpenID Endpoint Configuration und SAML 2.0 Identity Provider Metadata
Der folgende Screenshot zeigt die Felder, die Sie konfigurieren müssen.
Erstellen Sie einen Client, damit Sie eine Entität haben, die Keycloak zum Authentifizieren eines Nutzers anfordern kann. Clients sind häufig Anwendungen und Dienste, die Keycloak verwenden, um eine Lösung für die Einmalanmeldung (SSO) bereitzustellen.
- Klicken Sie in der Admin-Konsole von Keycloak auf Clients > Create.
Geben Sie Folgendes ein:
- Client ID: jenkins
- Client Protocol: openid-connect
- Root URL: http://JENKINS_IP_ADDRESS:8080, wobei JENKINS_IP_ADDRESS die IP-Adresse Ihres Jenkins-Servers ist.
Der folgende Screenshot zeigt die Felder, die Sie konfigurieren müssen.
Klicken Sie auf Speichern.
Prüfen Sie auf dem Tab Installation, ob das Tokenformat Keycloak OIDC JSON ist. Erstellen Sie eine Kopie dieses Tokens, da Sie es benötigen, um die Einrichtung von Jenkins abzuschließen.
So erstellen Sie eine Testgruppe:
- Klicken Sie in der Admin-Konsole von Keycloak auf Groups > New.
- Geben Sie einen Namen für die Gruppe ein und klicken Sie auf Save.
- Erstellen Sie eine weitere Testgruppe. Sie können Ihren Gruppen Rollen zuweisen, aber für diese Anleitung sind sie nicht erforderlich.
So erstellen Sie einen Testnutzer, der der Gruppe hinzugefügt werden soll:
- Klicken Sie in der Admin-Konsole von Keycloak auf Manage user > Add users.
Geben Sie die Nutzerinformationen ein und klicken Sie auf Save.
Der folgende Screenshot zeigt Beispielinformationen für ein Nutzerkonto.
Klicken Sie auf den Tab Credentials und prüfen Sie, ob Temporary auf OFF gesetzt ist.
Setzen Sie das Passwort zurück.
Sie verwenden dieses Konto später im JWT für die Authentifizierung.
Der folgende Screenshot zeigt den Tab Credentials mit den Feldern, die Sie konfigurieren müssen.
Klicken Sie auf den Tab Groups und wählen Sie eine der zuvor erstellten Gruppen aus.
Klicken Sie auf Teilnehmen.
Wiederholen Sie diesen Schritt, um weitere Testnutzer zu erstellen.
Jenkins für die OpenID Connect-Konfiguration konfigurieren
In diesem Abschnitt wird beschrieben, wie Sie das OpenID Connect-Plug-in für Jenkins konfigurieren.
- Gehen Sie auf Ihrem Jenkins-Server zu Manage Jenkins > Configure Global Security.
Wählen Sie unter Security Realm Keycloak Authentication Plug-in aus. Klicken Sie auf Save.
Klicken Sie auf Configure system.
Unter den Global Keycloak-Einstellungen kopieren Sie Ihre Keycloak-Installations-JSON, die Sie unter Keycloak konfigurieren erstellt haben. Wenn Sie die JSON-Daten noch einmal abrufen müssen, gehen Sie so vor:
Gehen Sie in der Admin-Konsole von Keycloak zu Clients.
Klicken Sie auf den Namen Ihres Clients.
Klicken Sie auf dem Tab Installation auf Format Option und wählen Sie Keycloak OIDC JSON aus.
Hier ein Beispiel für Keycloak-JSON:
{ "realm":"master" "auth-server-url":"AUTHSERVERURL" "ssl-required":"none" "resource":"jenkins" "public-client":true "confidential-port":0 }
AUTHSERVERURL ist die URL für Ihren Authentifizierungsserver.
Klicken Sie auf Save, um die OIDC-Konfiguration zu speichern.
Jenkins kann jetzt zu Keycloak weiterleiten, um Nutzerinformationen abzurufen.
Cloud-Clientbibliotheken installieren
Wenn Sie ein JWT von Keycloak an Google Cloud senden möchten, müssen Sie die Cloud-Clientbibliotheken auf dem Jenkins-Server installieren. In dieser Anleitung wird für die Interaktion mit Google Cloud über das SDK Python verwendet.
Installieren Sie Python auf dem Jenkins-Server. Die folgenden Schritte zeigen, wie Sie python3 installieren:
sudo apt update sudo apt install software-properties-common sudo add-apt-repository ppa:deadsnakes/ppa sudo apt update sudo apt install python3.8
Installieren Sie pip3, damit Sie Cloud-Clientbibliotheken herunterladen und importieren können:
pip3 –version sudo apt update sudo apt install python3-pip pip3 –version
Installieren Sie die Cloud-Clientbibliotheken für Python mit pip3:
pip3 install –upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib
Beispiel:
pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib Collecting google-api-python-client Downloading google_api_python_client-2.42.0-py2.py3-none-any.whl (8.3 MB) USERNAME | 8.3 MB 19.9 MB/s Collecting google-auth-httplib2 Downloading google_auth_httplib2-0.1.0-py2.py3-none-any.whl (9.3 MB) Collecting google-auth-oauthlib Downloading google_auth_oauthlib-0.5.1-py2.py3-non-any.whl (19 KB)
Ersetzen Sie USERNAME durch Ihren Nutzernamen.
Installieren Sie die Google Cloud CLI auf Ihrem Jenkins-Server. Eine Anleitung finden Sie unter Kurzanleitung: gcloud CLI installieren.
Google Cloud-Umgebung konfigurieren
In diesem Abschnitt werden die Schritte beschrieben, die Sie ausführen müssen, damit Ihre Google Cloud-Umgebung, in der Ihr serverloser Container gehostet wird, eine Verbindung mit Jenkins und Keycloak herstellen kann.
Erstellen Sie in Google Cloud ein Dienstkonto, damit der Mikrodienst in Cloud Run auf die Berechtigungen zugreifen kann, die mit ihm verknüpft sind. So erstellen Sie beispielsweise ein Dienstkonto über die gcloud CLI:
gcloud iam service-accounts create cloudrun-oidc \ –-description="cloud run oidc sa" \ –-display-name="cloudrun-oidc"
Cloud Run erstellt standardmäßig ein Standarddienstkonto für Sie. Die Verwendung des Standarddienstkontos stellt jedoch keine Best Practice für die Sicherheit dar, da das Konto über ein breites Spektrum an Berechtigungen verfügt. Daher empfehlen wir, ein separates Dienstkonto für Ihren Mikrodienst zu erstellen. Eine Anleitung zum Erstellen eines Dienstkontos für Cloud Run finden Sie unter Dienstkonten erstellen und verwalten.
Erstellen Sie einen Workload Identity-Pool. Führen Sie den folgenden Befehl aus, um einen Pool mit der gcloud CLI zu erstellen:
gcloud iam workload-identity-pools create cloudrun-oidc-pool \ --location="global" \ —-description="cloudrun-oidc" \ —-display-name="cloudrun-oidc"
Erstellen Sie einen Anbieter von Workload Identity-Pools für OpenID Connect:
gcloud iam workload-identity-pools providers create-oidc cloud-run-provider \ --workload-identity-pool="cloudrun-oidc-pool" \ --issuer-uri="VAR_LINK_TO_ENDPOINT" \ --location="global" \ --attribute-mapping ="google.subject=assertion.sub,attribute.isadmin-assertion.isadmin,attribute.aud=assertion.aud" \ --attribute-condition="attribute.isadmin=='true'"
Ersetzen Sie
VAR_LINK_TO_ENDPOINT
durch eine Variable, die den Link zum Keycloak-OIDC-Endpunkt enthält. Klicken Sie dazu in der Keycloak Admin-Konsole im Fenster Realm auf den Tab General. Der Endpunkt muss HTTPS sein. Das bedeutet, dass Sie Ihren Keycloak-Server mit HTTPS konfigurieren müssen.
JWT für den authentifizierten Nutzer aus Keycloak abrufen
Laden Sie das Token auf Ihre VM, auf der Keycloak ausgeführt wird, in eine Textdatei herunter. Führen Sie unter Linux beispielsweise Folgendes aus:
curl -L -X POST 'https://IP_FOR_KEYCLOAK:8080/auth/realms/master/protocol/openid-connect/token' -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=jenks' \ --data-urlencode 'grant_type=password' \ --data-urlencode 'client_secret=CLIENT_SECRET \ --data-urlencode 'scope=openid' \ --data-urlencode 'username=USERNAME' \ --data-urlencode 'password=PASSWORD' | grep access_token | cut -c18-1490 > token.txt
Ersetzen Sie Folgendes:
IP_FOR_KEYCLOAK
durch die IP-Adresse des Keycloak-Servers.CLIENT_SECRET
durch den Keycloak-Clientschlüssel.USERNAME
durch einen Keycloak-Nutzer.PASSWORD
durch das Passwort für den Keycloak-Nutzer.
Dieser Befehl enthält die Client-ID, den Clientschlüssel, den Nutzernamen und das Passwort. Als Best Practice für die Sicherheit empfehlen wir die Verwendung von Umgebungsvariablen, um diese Werte zu maskieren, anstatt die Befehlszeile zu verwenden. Mit dem Beispielbefehl werden die Anmeldedaten an eine Datei mit dem Namen
token.txt
weitergeleitet.Optional können Sie ein Bash-Skript erstellen, um diesen Schritt zu automatisieren.
Validieren Sie Ihr Token unter jwt.io.
Erstellen Sie auf der VM Ihre Datei mit den Anmeldedaten:
gcloud iam workload-identity-pools create-cred-config \ projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/cloudrun-oidc-pool/providers/cloud-run/provider \ --output-file=sts-creds.json \ --credential-source-file=token.txt
Weitere Informationen finden Sie unter gcloud iam workload-identity-pools create-cred-config.
Ihre Ausgabedatei sollte so aussehen:
{ "type": "external_account", "audience": "//iam.google.apis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/cloudrun-oidc-pool/subject/USER_EMAIL", "subject_token_type": "urn:ietf:params:oauth:token-type:jwt", "token_url": "https://sts.googleapis.com/v1/token", "credential_source": { "file" "token.txt" } }
PROJECT_NUMBER
ist Ihre Projektnummer.Legen Sie auf der VM die Datei
sts.creds.json
als Variable für ADC fest:export GOOGLE_APPLICATION_CREDENTIALS=/Users/USERNAME/sts-creds.json
Ersetzen Sie USERNAME durch Ihren UNIX-Nutzernamen.
Vor dem Start der Workload Identity-Föderation war dieser Wert der Dienstkontoschlüssel. Bei der Workload Identity-Föderation ist dieser Wert die neu erstellte Datei mit den Anmeldedaten.
Erstellen Sie eine Rollenbindung für den Nutzer, um die Identität des Dienstkontos zu übernehmen:
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT \ --role roles/iam.workloadIdentityUser \ --member "principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/cloudrun-oidc-pool/subject/USER_EMAIL
Ersetzen Sie Folgendes:
SERVICE_ACCOUNT
durch die E-Mail-Adresse des Dienstkontos, das Sie unter Google Cloud-Umgebung konfigurieren erstellt haben. Weitere Informationen finden Sie unter gcloud iam service-accounts add-iam-policy-binding.USER_EMAIL
durch Ihre E-Mail-Adresse.
Erlauben Sie dem Dienstkonto, den Cloud Run-Dienst aufzurufen:
gcloud run services add-iam-policy-binding SERVICE_NAME --member-"serviceAccount:SERVICE_ACCOUNT" \ --role="roles/run.invoker"
Ersetzen Sie Folgendes:
SERVICE_NAME
durch den Namen des in Cloud Run ausgeführten Mikrodiensts.SERVICE_ACCOUNT
durch die E-Mail-Adresse des Dienstkontos für Cloud Run.
Weitere Informationen finden Sie unter gcloud run services add-iam-policy-binding.
Generieren Sie ein ID-Token:
#!/usr/bin/python from google.auth import credentials from google.cloud import iam_credentials_v1 import google.auth import google.oauth2.credentials from google.auth.transport.requests import AuthorizedSession, Request url = "https://WORKLOAD_FQDN" aud = "https://WORKLOAD_FQDN" service_account = 'SERVICE_ACCOUNT' name = "projects/-/serviceAccounts/{}".format(service_account) id_token = client.generate_id_token(name=name,audience=aud, include_email=True) print(id_token.token) creds = google.oauth2.credentials.Credentials(id_token.token) authed_session = AuthorizedSession(creds) r = authed_session.get(url) print(r.status_code) print(r.text)
Ersetzen Sie Folgendes:
WORKLOAD_FQDN
durch den FQDN für Ihre Arbeitslast.SERVICE_ACCOUNT
durch die E-Mail-Adresse des Dienstkontos für Cloud Run.
Das verwendete Token kann die Identity and Access Management API aufrufen, um das neue JWT zu erhalten, das Sie zum Aufrufen Ihres Cloud Run-Dienstes benötigen.
Sie können Ihr Token in einer Jenkins-Pipeline verwenden, um den serverlosen Container aufzurufen, den Sie in Cloud Run ausführen. Diese Schritte werden jedoch in dieser Anleitung nicht behandelt.
Bereinigen
Um zu vermeiden, dass Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen in Rechnung gestellt werden, können Sie Ihr Projekt löschen.
Projekt löschen
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Nächste Schritte
- Weitere Informationen zur Workload Identity-Föderation
- Weitere Referenzarchitekturen, Diagramme und Best Practices finden Sie im Cloud-Architekturcenter.