{"id":40407499,"url":"https://github.com/intility/go-jwks","last_synced_at":"2026-02-22T23:20:33.460Z","repository":{"id":285715631,"uuid":"958444810","full_name":"intility/go-jwks","owner":"intility","description":"A lightweight package for fetching remote JWKSs and validating JWTs","archived":false,"fork":false,"pushed_at":"2026-01-05T10:52:12.000Z","size":361,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-01-08T10:43:39.412Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/intility.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-01T07:58:44.000Z","updated_at":"2026-01-05T10:52:14.000Z","dependencies_parsed_at":"2025-04-02T09:42:15.917Z","dependency_job_id":"94a09443-e81c-481b-b4e3-86217387eca0","html_url":"https://github.com/intility/go-jwks","commit_stats":null,"previous_names":["intility/go-jwks"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/intility/go-jwks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intility%2Fgo-jwks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intility%2Fgo-jwks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intility%2Fgo-jwks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intility%2Fgo-jwks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/intility","download_url":"https://codeload.github.com/intility/go-jwks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intility%2Fgo-jwks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28604712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T12:01:53.233Z","status":"ssl_error","status_checked_at":"2026-01-20T12:01:46.545Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-20T14:00:40.990Z","updated_at":"2026-02-22T23:20:33.446Z","avatar_url":"https://github.com/intility.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go JWKS Fetcher and JWT Validator\n\n A Go library for JWT validation with automatic JWKS fetching and key rotation. Includes HTTP middleware.\n\n## Features\n\n- **Minimal Config** — Get up and running with just your audience + tenant ID or genric discovery endpoint\n- **HTTP Middleware** — Drop-in `http.Handler` middleware for protected routes\n- **Generic OIDC** — Works with Auth0, Okta, or any OIDC provider \n\n## Installation\n```bash\ngo get github.com/intility/go-jwks\n```\n\n\n## Quick Start\n```go\nfetcher, _ := jwks.NewJWKSFetcher(jwks.EntraID{TenantID: \"your-tenant-id\"})\nfetcher.Start(ctx)\n\nvalidator, _ := fetcher.NewJWTValidator(\"api://your-audience\")\nmiddleware := jwks.JWTMiddleware(validator)\n\nmux.Handle(\"/protected\", middleware(yourHandler))\n```\n\nThe validator uses **smart defaults**:\n- **Issuer**: Automatically extracted from the OIDC discovery document\n- **Signing methods**: RS256\n\nSee the [examples](./examples) folder for complete runnable examples:\n- **[basic](./examples/basic)** - Standard JWT validation with HTTP middleware\n- **[custom-claims](./examples/custom-claims)** - Using generic claims types for application-specific JWT fields\n\n## Fetcher Options\n\nThe fetcher uses secure defaults (HTTPS required, TLS 1.2+, 24h refresh). Override when needed:\n\n```go\nfetcher, err := jwks.NewJWKSFetcher(\n    jwks.Generic{DiscoveryURL: \"https://auth.example.com/.well-known/openid-configuration\"},\n    jwks.WithFetchInterval(12 * time.Hour),                      // Override refresh interval (default: 24h)\n    jwks.WithAllowedJWKSHosts([]string{\"auth.example.com\"}),     // Restrict JWKS to specific hosts\n    jwks.WithMicrosoftHosts(),                                   // Preset for Microsoft Entra ID hosts\n    jwks.WithRequireHTTPS(false),                                // Allow HTTP (default: true)\n    jwks.WithTLSConfig(customTLSConfig),                         // Custom TLS configuration\n    jwks.WithMaxResponseSize(512 * 1024),                        // Limit response size (default: 1MB)\n    jwks.WithMaxKeysCount(50),                                   // Limit key count (default: 100)\n)\n```\n\n## Validator Options\n\nThe validator uses smart defaults (issuer from discovery, RS256 signing). Override when needed:\n\n```go\nvalidator, err := fetcher.NewJWTValidator(\"api://my-app\",\n    jwks.WithIssuers(\"https://custom-issuer\"),       // Override discovery issuer\n    jwks.WithAdditionalAudiences(\"api://other\"),    // Add more audiences\n    jwks.WithValidMethods(\"RS384\"),                 // Override signing methods\n)\n```\n\n## Security Features\n\nThis library implements several security best practices by default:\n\n\n### Host Allowlisting\nProtect against SSRF attacks by restricting which hosts can serve JWKS:\n```go\nfetcher, err := jwks.NewJWKSFetcher(\n    jwks.Generic{DiscoveryURL: \"https://auth.example.com/.well-known/openid-configuration\"},\n    jwks.WithAllowedJWKSHosts([]string{\"auth.example.com\", \"backup-auth.example.com\"}),\n)\n```\n\nFor Microsoft Entra ID, use the preset configuration:\n```go\nfetcher, err := jwks.NewJWKSFetcher(\n    jwks.EntraID{TenantID: \"your-tenant-id\"},\n    jwks.WithMicrosoftHosts(), // Allows only Microsoft's auth domains\n)\n```\n\n### Secure Defaults\n- **HTTPS Required**: By default, only HTTPS URLs are accepted for JWKS endpoints. This can be disabled for testing/internal environments using `WithRequireHTTPS(false)`\n- **TLS 1.2+**: Minimum TLS version 1.2 is enforced for all HTTPS connections\n- **Response Size Limits**: JWKS responses are limited to 1MB by default to prevent memory exhaustion attacks\n- **Key Count Limits**: Maximum of 100 keys per JWKS to prevent resource exhaustion\n\n\n## How It Works\n\n1. **Fetcher** retrieves public keys from the OIDC discovery endpoint and refreshes them periodically (default: 24h)\n2. **Validator** uses these keys to verify JWT signatures and validate claims (issuer, audience, expiry)\n3. **Middleware** extracts the Bearer token from `Authorization` header and validates it\n\n## Standalone Validation\n\nFor validating JWTs outside of HTTP handlers:\n\n```go\nclaims, err := validator.ValidateJWT(ctx, tokenString)\nif err != nil {\n    if errors.Is(err, jwks.ErrInvalidAud) {\n        // Handle invalid audience\n    }\n    return err\n}\nfmt.Printf(\"User: %s\\n\", claims.Email)\n```\n\n**Error types:** `ErrInvalidToken`, `ErrInvalidAud`, `ErrInvalidIss`\n\n## Current limitations\n\nCurrently only RSA based encryption algorithms are supported.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintility%2Fgo-jwks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintility%2Fgo-jwks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintility%2Fgo-jwks/lists"}