Documentation
¶
Overview ¶
Package githubactions provides an OIDC token source and principal extraction for GitHub Actions workflows, using the workflow's ACTIONS_ID_TOKEN_REQUEST_URL to fetch tokens.
Index ¶
- func HasValidClaims(claims map[string]any) bool
- func NewHTTPClient(ctx context.Context, opts ...Opt) (*http.Client, error)
- func NewTokenSource(opts ...Opt) oauth2.TokenSource
- type Claims
- type CustomClaims
- type Opt
- type PrincipalSource
- func (s *PrincipalSource) Claims(ctx context.Context) map[string]any
- func (s *PrincipalSource) Extract(ctx context.Context) (string, error)
- func (s *PrincipalSource) IsService(ctx context.Context) bool
- func (s *PrincipalSource) Name() string
- func (s *PrincipalSource) Roles(ctx context.Context) []string
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HasValidClaims ¶ added in v0.5.7
HasValidClaims reports whether claims contains enough GitHub Actions-specific fields to be treated as a GitHub Actions OIDC token. It requires the repository claim plus at least one workflow/run indicator to reduce false positives for repositories that happen to include ref-only claims.
func NewHTTPClient ¶
NewHTTPClient creates an HTTP client configured with GitHub Actions OIDC authentication.
func NewTokenSource ¶
func NewTokenSource(opts ...Opt) oauth2.TokenSource
NewTokenSource creates a new token source for GitHub Actions OIDC It retrieves tokens from the GitHub Actions OIDC provider using environment variables See: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect
Types ¶
type Claims ¶
type Claims struct {
CustomClaims
}
Claims is the JWT claims type for a GitHub Actions OIDC token, combining CustomClaims with the auth0/go-jwt-middleware CustomClaims interface.
type CustomClaims ¶
type CustomClaims struct {
// GitHub actions specific
Actor string `json:"actor"`
ActorID string `json:"actor_id"`
BaseRef string `json:"base_ref"`
Environment string `json:"environment"`
EventName string `json:"event_name"`
HeadRef string `json:"head_ref"`
JobWorkflowRef string `json:"job_workflow_ref"`
Ref string `json:"ref"`
RefType string `json:"ref_type"`
Repository string `json:"repository"`
RepositoryID string `json:"repository_id"`
RepositoryOwner string `json:"repository_owner"`
RepositoryOwnerID string `json:"repository_owner_id"`
RunAttempt string `json:"run_attempt"`
RunID string `json:"run_id"`
RunNumber string `json:"run_number"`
RunnerEnvironment string `json:"runner_environment"`
SHA string `json:"sha"`
Workflow string `json:"workflow"`
WorkflowRef string `json:"workflow_ref"`
WorkflowSHA string `json:"workflow_sha"`
}
CustomClaims represents the custom claims in a GitHub Actions OIDC token.
type Opt ¶
type Opt func(*tokenSource)
Opt is a function option for configuring the token source.
func WithAudience ¶
WithAudience sets the audience for the OIDC token.
func WithEnvGetter ¶
WithEnvGetter sets a custom environment variable lookup function for the token source.
func WithHTTPClient ¶
WithHTTPClient sets a custom HTTP client for the token source.
type PrincipalSource ¶ added in v0.4.0
type PrincipalSource struct {
// RoleMapper maps raw GitHub Actions JWT claims to internal role strings.
// When nil, Roles returns nil.
RoleMapper mapper.Mapper
}
PrincipalSource extracts principal identity from GitHub Actions OIDC tokens.
Example ¶
ExamplePrincipalSource reads a GitHub Actions workflow identity from a validated token and grants the deployer role to one repository's main branch. The JWT middleware stores the validated token in the context; here that is done by hand.
package main
import (
"context"
"fmt"
"github.com/auth0/go-jwt-middleware/v3/core"
jwtvalidator "github.com/auth0/go-jwt-middleware/v3/validator"
"github.com/dioad/auth"
"github.com/dioad/auth/oidc/githubactions"
)
func main() {
source := &githubactions.PrincipalSource{
RoleMapper: auth.NewClaimRoleMapper([]auth.ClaimRoleMapping{
{
Claims: map[string]string{"repository": "myorg/infrastructure", "ref": "refs/heads/main"},
Role: "deployer",
},
}),
}
token := func(ref string) context.Context {
return core.SetClaims(context.Background(), &jwtvalidator.ValidatedClaims{
RegisteredClaims: jwtvalidator.RegisteredClaims{Subject: "repo:myorg/infrastructure:ref:" + ref},
CustomClaims: &githubactions.Claims{
Repository: "myorg/infrastructure",
Ref: ref,
JobWorkflowRef: "myorg/infrastructure/.github/workflows/deploy.yaml@" + ref,
RunID: "42"},
})
}
fmt.Println("main:", source.Roles(token("refs/heads/main")))
fmt.Println("feature branch:", source.Roles(token("refs/heads/feature")))
}
Output: main: [deployer] feature branch: []
func (*PrincipalSource) Claims ¶ added in v0.4.0
func (s *PrincipalSource) Claims(ctx context.Context) map[string]any
Claims returns the GitHub Actions token claims as a map. Canonical attribute keys (e.g. "username") are included alongside raw GitHub Actions claim names so that ClaimRoleMapper rules can reference either form.
func (*PrincipalSource) Extract ¶ added in v0.4.0
func (s *PrincipalSource) Extract(ctx context.Context) (string, error)
Extract returns the principal subject from a GitHub Actions token. It first attempts the typed-claims path (JWT middleware configured with a GitHub Actions validator), then falls back to fingerprinting generic validated claims stored by a non-typed JWT middleware.
func (*PrincipalSource) IsService ¶ added in v0.4.0
func (s *PrincipalSource) IsService(ctx context.Context) bool
IsService returns true for any valid GitHub Actions token, as these represent automated workflow identities rather than human users.
func (*PrincipalSource) Name ¶ added in v0.4.0
func (s *PrincipalSource) Name() string
Name returns "githubactions".