GitHub Actions OIDC: Jak zabezpieczyć swoje wdrożenia bez długotrwałych tajemnic
Dowiedz się, jak wzmocnić bezpieczeństwo wdrożeń GitHub Actions przy pomocy OIDC. Zamień długotrwałe poświadczenia chmurowe na krótkotrwałe tokeny, ogranicz dostęp przy użyciu polityk zaufania IAM i zabezpiecz swoje potoki CI/CD.
GitHub Actions OIDC: Jak zabezpieczyć wdrożenia bez długowiecznych kluczy tajnych
Wdrażanie aplikacji z GitHub Actions zazwyczaj wymaga dostępu do zewnętrznej infrastruktury. Przepływ pracy może przesyłać pliki do Amazon S3, publikować kontenery lub aktualizować zasoby chmurowe. Tradycyjnie zespoły przechowują klucz dostępu do chmury w wpisach tajnych GitHub. To działa, ale długowieczne poświadczenie nadal jest przydatne dla napastnika, jeśli przepływ pracy, zależność lub log je ujawni.
OpenID Connect (OIDC) pomaga wzmocnić bezpieczeństwo CI/CD, zastępując długowieczne poświadczenia chmurowe tymczasowym dostępem przyznawanym tylko autoryzowanym tożsamościom przepływów pracy. Zmniejsza to ujawnianie poświadczeń, ogranicza nieautoryzowany dostęp i wspiera ściślej kontrolowane wdrożenia produkcyjne.
Ten samouczek wyjaśnia korzyści bezpieczeństwa, pokazuje praktyczną konfigurację AWS i identyfikuje zabezpieczenia, których nadal potrzebujesz. OIDC nie jest magicznym przełącznikiem bezpieczeństwa: zasady zaufania, uprawnienia roli i kontrola przepływów pracy mają takie samo znaczenie jak wymiana tokenów.
Dlaczego bezpieczeństwo wdrażania jest ważne
Potoki CI/CD to uprzywilejowana automatyzacja. Mogą być w stanie zastąpić kod produkcyjny, przesłać zasoby, odczytać konfiguracje wdrażania lub zmodyfikować infrastrukturę. Skoro potok zostanie skompromitowany, może mieć to większe skutki niż skompromitowana stacja robocza dewelopera.
Trzy typowe zagrożenia zasługują na szczególną uwagę:
- Ujawnienie poświadczeń: statyczny klucz chmury skradziony ze środowiska kompilacji może pozostać ważny, dopóki ktoś go nie unieważni.
- Nadmierne uprawnienia: poświadczenie wdrażania z uprawnieniami administratora może wpłynąć na niepowiązane usługi.
- Nieautoryzowane wdrożenie: niezaufana gałąź lub przepływ pracy może uzyskać dostęp produkcyjny, jeśli kontrole tożsamości są zbyt szerokie.
OIDC rozwiązuje część tego problemu, wiążąc uwierzytelnianie z krótkotrwałą, weryfikowalną tożsamością przepływu pracy. Nie zastępuje on IAM z zasadą minimalnych uprawnień, recenzji kodu ani ochrony środowiska.
Czym jest OIDC w GitHub Actions?
OpenID Connect to warstwa tożsamości oparta na OAuth 2.0. GitHub Actions może żądać podpisanego tokena JSON Web Token (JWT) od dostawcy OIDC GitHub:
https://token.actions.githubusercontent.com
Token zawiera roszczenia opisujące tożsamość zadania i kontekst wykonywania. Usługa tożsamości chmury weryfikuje podpis tokena, wystawcę, grupę docelową i odpowiednie roszczenia, a następnie decyduje, czy wydać tymczasowe poświadczenia.
Zewnętrzna usługa musi wyraźnie ufać zamierzonej tożsamości przepływu pracy GitHub. Po prostu włączenie OIDC w pliku YAML nie przyznaje dostępu.
Zobacz dokumentację OIDC GitHub.
Poświadczenia statyczne a OIDC: porównanie bezpieczeństwa
| Zagadnienie bezpieczeństwa | Długowieczny klucz dostępu | Federacja OIDC |
|---|---|---|
| Stałe poświadczenie chmury w GitHub | Zazwyczaj wymagane | Nie wymagane dla obsługiwanych dostawców |
| Okres ważności poświadczeń | Do wygaśnięcia lub unieważnienia | Tymczasowa sesja |
| Odpowiedzialność za rotację | Zespół musi zarządzać cyklem życia klucza | Dostawca chmury wystawia krótkotrwałe poświadczenia |
| Ograniczenia tożsamości | Zależy od przechowywania poświadczeń i IAM | Zasada zaufania może ograniczać tożsamość przepływu pracy |
| Autoryzacja | Uprawnienia IAM | Nadal wymagane uprawnienia IAM |
| Pozostałe ryzyko | Kradzież i ponowne użycie statycznego klucza | Skompromitowany autoryzowany przepływ pracy lub zbyt szerokie zaufanie |
OIDC zmniejsza ryzyko i skutki kradzieży poświadczeń; nie eliminuje ona wszystkich wpisów tajnych. Aplikacje mogą nadal potrzebować haseł do baz danych, kluczy podpisujących lub tokenów API firm zewnętrznych.
Jak działa przepływ uwierzytelniania OIDC
- Autoryzowane zadanie GitHub Actions żąda tokena tożsamości.
- GitHub wystawia podpisany JWT dla tego zadania.
- Przepływ pracy przedstawia token usłudze tożsamości chmury.
- Dostawca chmury weryfikuje token i ocenia skonfigurowane warunki zaufania.
- Jeśli tożsamość jest dozwolona, dostawca wystawia tymczasowe poświadczenia.
- Przepływ pracy używa tych poświadczeń w dozwolonym zakresie roli.
Dostawca chmury musi odrzucić token, którego podmiot, grupa docelowa lub inne wymagane warunki nie są zgodne. Ta weryfikacja jest granicą między bezpiecznym wdrożeniem a takim, które ufa zbyt wiele.
Krok 1: Skonfiguruj dostawcę OIDC GitHub w AWS
AWS IAM obsługuje dostawców tożsamości OpenID Connect. Utwórz dostawcę tożsamości używając:
| Ustawienie | Wartość |
|---|---|
| URL dostawcy | https://token.actions.githubusercontent.com |
| Grupa docelowa | sts.amazonaws.com |
| Typ dostawcy | OpenID Connect |
Grupa docelowa identyfikuje zamierzonego odbiorcę tokena. Akcja poświadczeń AWS zazwyczaj używa sts.amazonaws.com.
Zobacz konfigurację roli OIDC AWS IAM.
Krok 2: Ogranicz, kto może przyjąć rolę wdrażania
Utwórz rolę IAM, której zasada zaufania zezwala na sts:AssumeRoleWithWebIdentity tylko od dostawcy tożsamości GitHub i zamierzonej tożsamości przepływu pracy.
Poniższy przykład używa tradycyjnego formatu podmiotu opartego na gałęzi GitHub:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
"token.actions.githubusercontent.com:sub": "repo:example-org/example-app:ref:refs/heads/main"
}
}
}
]
}
Zastąp numer konta AWS, organizację i repozytorium.
Nie kopiuj warunku podmiotu w ciemno. GitHub wprowadził niezmienny domyślny format podmiotu dla repozytoriów utworzonych po 15 lipca 2026 r. Sprawdź rzeczywisty format podmiotu używany przez Twoje repozytorium i skonfiguruj AWS tak, aby był zgodny. Przepływy pracy oparte na środowiskach mogą również używać innego kształtu podmiotu. Skonsultuj się z odniesieniem do tokenu OIDC GitHub.
Ograniczone zasady zaufania to jeden z najważniejszych sposobów, aby zapobiec uzyskaniu przez nieautoryzowane przepływy pracy poświadczeń produkcyjnych. Unikaj symboli wieloznacznych w podmiotach, które przypadkiem autoryzują niepowiązane repozytoria lub konteksty.
Krok 3: Ogranicz, co może robić rola
Zaufanie określa, kto może przyjąć rolę. Uprawnienia IAM określają, co rola może zrobić po uwierzytelnieniu.
Dla wdrożenia, które tylko przesyła pliki do jednego kontenera S3, uproszczona polityka to:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:PutObject"],
"Resource": "arn:aws:s3:::example-deploy-bucket/*"
}
]
}

Ten przykład zezwala na przesyłanie obiektów, a nie administrowanie kontem lub usuwanie kontenera. Jeśli Twoje wdrożenie usuwa również przestarzałe pliki lub wyświetla zawartość kontenera, przyznaj tylko wymagane dodatkowe operacje, takie jak objęte zakresem s3:DeleteObject lub s3:ListBucket.
Nigdy nie przyzniaj AdministratorAccess tylko po to, aby wdrożenie działało. Tymczasowe poświadczenia z nadmiernymi uprawnieniami mogą nadal powodować poważne szkody.
Krok 4: Żądaj tymczasowych poświadczeń z przepływu pracy
Zadanie wdrażania musi mieć uprawnienia do żądania tokena OIDC. Poniższy przykład przesyła wstępnie zbudowany katalog dist/ do S3:
name: Deploy website
on:
push:
branches:
- main
permissions:
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/github-deploy-role
aws-region: eu-west-1
- name: Deploy website
run: |
aws s3 cp ./dist/ s3://example-deploy-bucket/ --recursive
Przykład używa odwołań do akcji w wersji głównej dla czytelności. W środowisku produkcyjnym sprawdź aktualnie obsługiwane wersje i najlepiej przypnij akcje firm zewnętrznych do pełnych skrótów SHA komitów. Przykład zakłada, że witryna została już zbudowana w dist/.
Zwróć uwagę, czego brakuje: w przepływie pracy nie przechowuje się trwałego klucza dostępu ani tajnego klucza dostępu AWS.
Oficjalna akcja poświadczeń AWS wymienia token OIDC na tymczasowe poświadczenia AWS.
Krok 5: Zrozum id-token: write
To uprawnienie:
permissions:
id-token: write
pozwala zadaniu zażądać tożsamościowego tokena OIDC GitHub. Nie daje ono samodzielnie zadaniu uprawnień do pisania do repozytoriów GitHub ani dostępu do AWS.
Dostawca chmury nadal decyduje, czy ufać tożsamości, a rola IAM nadal kontroluje, jakie operacje są dozwolone.
Przyznaj id-token: write tylko zadaniom, które faktycznie uwierzytelniają się w chmurze. Zadania kompilacji, lintowania i testów zazwyczaj go nie potrzebują.
Krok 6: Chroń środowiska produkcyjne
OIDC nie zrekompensuje autoryzowanego przepływu pracy uruchamiającego złośliwy kod. Jeśli napastnik może zmienić zaufany przepływ pracy wdrażania lub wykonać nieprzeglądnięty kod w tym kontekście, może być w stanie uzyskać tymczasowe poświadczenia.
Środowiska GitHub mogą dodać kontrole, takie jak ograniczenia gałęzi wdrażania i wymagani recenzenci, w zależności od ustawień repozytorium i dostępności planu.
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
permissions:
contents: read
id-token: write
Gdy przepływ pracy używa środowiska, podmiot OIDC może identyfikować to środowisko zamiast gałęzi. Zaktualizuj zasadę zaufania IAM, aby dopasować rzeczywiste roszczenia, i chron samym środowiskiem.
W środowisku produkcyjnym łącz ograniczony identyfikator z ochroną gałęzi, recenzją kodu, ograniczonymi uprawnieniami przepływu pracy i regułami zatwierdzania środowisk, gdzie to odpowiednie. W ten sposób OIDC staje się częścią silniejszej postawy bezpieczeństwa wdrażania, a nie tylko zastępstwa poświadczeń.
Krok 7: Weryfikuj przyjętą tożsamość i testuj odrzucenia
Po skonfigurowaniu uwierzytelniania AWS dodaj krok diagnostyczny:
- name: Verify AWS identity
run: aws sts get-caller-identity
Sprawdź, czy odpowiedź identyfikuje zamierzone konto AWS i rolę wdrażania. Polecenie nie ujawnia tajnego klucza dostępu.
Przetestuj również, czy nieautoryzowana gałąź, repozytorium lub środowisko nie może przyjąć roli produkcyjnej. Nieudane nieautoryzowane wdrożenie jest udanym testem bezpieczeństwa.
Nie rejestruj surowych tokenów OIDC ani tymczasowych poświadczeń podczas debugowania.
Typowe błędy bezpieczeństwa i konfiguracji OIDC
Brakujące id-token: write
Zadanie nie może zażądać tokena OIDC, chyba że ma to uprawnienie. Uprawnienia na poziomie zadania mogą nadpisać uprawnienia na poziomie przepływu pracy.

AWS zwraca AccessDenied przy przyjmowaniu roli
Sprawdź dostawcę tożsamości, grupę docelową, ARN roli i warunek podmiotu. W szczególności zweryfikuj rzeczywisty format podmiotu GitHub zamiast zakładać, że każde repozytorium używa tego samego domyślnego.
Uwierzytelnianie się powiodło, ale przesyłanie nie powiodło się
Relacja zaufania może być poprawna, podczas gdy rola nie ma wymaganych uprawnień S3. Napraw wąsko określone zasady uprawnień IAM, zamiast poszerzać zaufanie tożsamości.
Dostęp produkcyjny jest dozwolony zbyt wielu kontekstach
Symbol wieloznaczny w podmiocie lub niewystarczające ograniczenia środowiskowe mogą udostępniać poświadczenia produkcyjne przepływom pracy, które nigdy ich nie powinny otrzymać. Ogranicz zasadę zaufania i przetestuj nieautoryzowane przypadki.
Żądanie ściągnięcia nie może wdrożyć
Żądania ściągnięcia mogą mieć różne roszczenia i niezaufany kod. Nie osłabiaj warunków zaufania produkcyjnego tylko po to, aby żądanie ściągnięcia mogło przyjąć rolę wdrażania. Uruchamiaj walidację osobno od wdrożenia produkcyjnego.
Czy można używać OIDC z platformą Azure lub Google Cloud?
Tak. Mechanizm federacji jest podobny, ale konfiguracja tożsamości się różni.
| Chmura | Mechanizm federacji | Akcja GitHub |
|---|---|---|
| AWS | Dostawca i rola OIDC IAM | aws-actions/configure-aws-credentials |
| Microsoft Azure | Poświadczenia tożsamości federacyjnej | azure/login |
| Google Cloud | Workload Identity Federation | google-github-actions/auth |
Platforma Azure zazwyczaj kojarzy poświadczenie federacyjne z aplikacją lub zarządzaną tożsamością. Google Cloud używa puli tożsamości obciążenia i dostawcy, z bezpośrednim dostępem do zasobów lub personifikacją konta usługi, w zależności od konfiguracji.
Każda platforma ma własne reguły grupy docelowej, dopasowania podmiotu i autoryzacji. Zapoznaj się z aktualną oficjalną dokumentacją dostawcy przed skopiowaniem przykładu.
Co z witrynami PHP na tradycyjnym hostingu?
Każdy host internetowy nie akceptuje tożsamości OIDC GitHub. Współdzielony hosting i zarządzany hosting PHP mogą nadal używać kluczy SSH, poświadczeń SFTP, webhooków wdrażania lub tokenów API dostawcy.
Włączenie OIDC w GitHub Actions nie zastępuje automatycznie klucza SSH, jeśli serwer docelowy nie ma mechanizmu federacji.
Gdzie OIDC jest niedostępne, używaj dedykowanego konta wdrażania, wąsko określonych uprawnień, chronionych wpisów tajnych i rotacji poświadczeń. Ograniczaj dostęp do systemu plików i poleceń tam, gdzie to możliwe.
Celem bezpieczeństwa jest zasada minimalnych uprawnień i ograniczone ujawnianie poświadczeń, niezależnie od tego, czy OIDC jest obsługiwane.
Lista kontrolna bezpieczeństwa wdrażania
Przed wdrożeniem w produkcji zweryfikuj, czy:
- Wystawca i grupa docelowa OIDC są poprawnie skonfigurowani.
- Zasada zaufania pasuje tylko do zamierzonego repozytorium i kontekstu wdrażania.
- Warunek podmiotu odzwierciedla rzeczywisty format tokena GitHub Twojego repozytorium.
- Rola IAM ma tylko uprawnienia wymagane przez wdrożenie.
- Tylko zadania wdrażania otrzymują
id-token: write. - Gałęzie i środowiska produkcyjne mają odpowiednią ochronę.
- Akcje firm zewnętrznych są przeglądane i najlepiej przypięte do niezmiennych skrótów SHA komitów.
- Niezaufane żądania ściągnięcia nie mogą przyjąć ról produkcyjnych.
- Nieautoryzowane gałęzie i repozytoria kończą się niepowodzeniem uwierzytelniania.
- Tokeny i tymczasowe poświadczenia nigdy nie są rejestrowane ani niepotrzebnie przechowywane.
Często zadawane pytania
Czy OIDC jest bezpieczniejsze niż statyczne klucze dostępu AWS?
Zmniejsza to narażenie na kradzież długowiecznych poświadczeń. Silne zasady zaufania, ograniczone uprawnienia i chronione przepływy pracy są nadal niezbędne.
Czy OIDC eliminuje wpisy tajne GitHub?
Zastępuje niektóre poświadczenia uwierzytelniania chmury, nie każdy wpis tajny aplikacji lub klucz API.
Co przyznaje id-token: write?
Pozwala przepływowi pracy zażądać tokena tożsamości. Uprawnienia do chmury są określane osobno przez dostawcę.
Czy niezaufane żądania ściągnięcia mogą używać produkcyjnych poświadczeń OIDC?
Nie powinny. Skonfiguruj ograniczające warunki zaufania i trzymaj wdrożenia produkcyjne osobno od niezaufanego kodu.
Czy OIDC działa z dowolnym dostawcą hostingu?
Nie. Usługa docelowa lub pośrednik tożsamości musi obsługiwać i ufać tokenom OIDC GitHub.
Wniosek: wzmocnij bezpieczeństwo, a nie tylko uwierzytelnianie
GitHub Actions OIDC to skuteczny sposób na zwiększenie bezpieczeństwa wdrażania dla obsługiwanych usług chmurowych. Usuwa konieczność przechowywania trwałych kluczy chmury w GitHub, umożliwia krótkotrwały dostęp i pozwala zasadom zaufania chmury ograniczać, które przepływy pracy mogą wdrażać.
Ale najsilniejszy projekt łączy OIDC z IAM o zasadzie minimalnych uprawnień, chronionymi środowiskami, przejrzanym kodem przepływu pracy i jawnymi testami, że nieautoryzowane tożsamości są odrzucane.
Celem nie jest po prostu zastąpienie wpisu tajnego. Chodzi o to, aby upewnić się, że tylko właściwy przepływ pracy może uzyskać dostęp do właściwych zasobów, z minimalnymi uprawnieniami i przez najkrótszy praktyczny czas.