{"id":20849504,"url":"https://github.com/labstack/echo-jwt","last_synced_at":"2025-10-24T04:55:45.851Z","repository":{"id":65071917,"uuid":"569065345","full_name":"labstack/echo-jwt","owner":"labstack","description":"JWT middleware for Echo framework","archived":false,"fork":false,"pushed_at":"2025-03-21T22:50:52.000Z","size":54,"stargazers_count":104,"open_issues_count":9,"forks_count":13,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-16T18:06:23.020Z","etag":null,"topics":["echo","echo-framework","jwt","middleware"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/labstack.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2022-11-22T02:07:14.000Z","updated_at":"2025-05-15T19:32:29.000Z","dependencies_parsed_at":"2025-05-07T12:00:58.442Z","dependency_job_id":null,"html_url":"https://github.com/labstack/echo-jwt","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labstack%2Fecho-jwt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labstack%2Fecho-jwt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labstack%2Fecho-jwt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labstack%2Fecho-jwt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/labstack","download_url":"https://codeload.github.com/labstack/echo-jwt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254582904,"owners_count":22095518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["echo","echo-framework","jwt","middleware"],"created_at":"2024-11-18T03:05:27.231Z","updated_at":"2025-10-08T20:13:23.873Z","avatar_url":"https://github.com/labstack.png","language":"Go","readme":"[![Sourcegraph](https://sourcegraph.com/github.com/labstack/echo-jwt/-/badge.svg?style=flat-square)](https://sourcegraph.com/github.com/labstack/echo-jwt?badge)\n[![GoDoc](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](https://pkg.go.dev/github.com/labstack/echo-jwt/v4)\n[![Go Report Card](https://goreportcard.com/badge/github.com/labstack/echo-jwt?style=flat-square)](https://goreportcard.com/report/github.com/labstack/echo-jwt)\n[![Codecov](https://img.shields.io/codecov/c/github/labstack/echo-jwt.svg?style=flat-square)](https://codecov.io/gh/labstack/echo-jwt)\n[![License](http://img.shields.io/badge/license-mit-blue.svg?style=flat-square)](https://raw.githubusercontent.com/labstack/echo-jwt/master/LICENSE)\n\n# Echo JWT middleware\n\nJWT middleware for [Echo](https://github.com/labstack/echo) framework. This middleware uses by default [golang-jwt/jwt/v5](https://github.com/golang-jwt/jwt) \nas JWT implementation.\n\n## Versioning\n\nThis repository does not use semantic versioning. MAJOR version tracks which Echo version should be used. MINOR version\ntracks API changes (possibly backwards incompatible) and PATCH version is incremented for fixes.\n\nNB: When `golang-jwt` MAJOR version changes this library will release MINOR version with **breaking change**. Always \nadd at least one integration test in your project.\n\nFor Echo `v4` use `v4.x.y` releases.\nMinimal needed Echo versions:\n* `v4.0.0` needs Echo `v4.7.0+`\n\n`main` branch is compatible with the latest Echo version.\n\n## Usage\n\nAdd JWT middleware dependency with go modules\n```bash\ngo get github.com/labstack/echo-jwt/v4\n```\n\nUse as import statement\n```go\nimport \"github.com/labstack/echo-jwt/v4\"\n```\n\nAdd middleware in simplified form, by providing only the secret key\n```go\ne.Use(echojwt.JWT([]byte(\"secret\")))\n```\n\nAdd middleware with configuration options\n```go\ne.Use(echojwt.WithConfig(echojwt.Config{\n  // ...\n  SigningKey:             []byte(\"secret\"),\n  // ...\n}))\n```\n\nExtract token in handler\n```go\nimport \"github.com/golang-jwt/jwt/v5\"\n\n// ...\n\ne.GET(\"/\", func(c echo.Context) error {\n  token, ok := c.Get(\"user\").(*jwt.Token) // by default token is stored under `user` key\n  if !ok {\n    return errors.New(\"JWT token missing or invalid\")\n  }\n  claims, ok := token.Claims.(jwt.MapClaims) // by default claims is of type `jwt.MapClaims`\n  if !ok {\n    return errors.New(\"failed to cast claims as jwt.MapClaims\")\n  }\n  return c.JSON(http.StatusOK, claims)\n})\n```\n\n## IMPORTANT: Integration Testing with JWT Library\n\nEnsure that your project includes at least one integration test to detect changes in major versions of the `golang-jwt/jwt` library early.\nThis is crucial because type assertions like `token := c.Get(\"user\").(*jwt.Token)` may fail silently if the imported version of the JWT library (e.g., `import \"github.com/golang-jwt/jwt/v5\"`) differs from the version used internally by dependencies (e.g., echo-jwt may now use `v6`). Such discrepancies can lead to invalid casts, causing your handlers to panic or throw errors. Integration tests help safeguard against these version mismatches.\n\n```go\nfunc TestIntegrationMiddlewareWithHandler(t *testing.T) {\n\te := echo.New()\n\te.Use(echojwt.WithConfig(echojwt.Config{\n\t\tSigningKey: []byte(\"secret\"),\n\t}))\n\n  // use handler that gets token from context to fail your CI flow when `golang-jwt/jwt` library version changes \n  // a) `token, ok := c.Get(\"user\").(*jwt.Token)`\n  // b) `token := c.Get(\"user\").(*jwt.Token)`\n\te.GET(\"/example\", exampleHandler) \n\n\treq := httptest.NewRequest(http.MethodGet, \"/example\", nil)\n\treq.Header.Set(echo.HeaderAuthorization, \"Bearer \u003cTOKEN\u003e\")\n\tres := httptest.NewRecorder()\n\n\te.ServeHTTP(res, req)\n\t\n\tif res.Code != 200 {\n\t\tt.Failed()\n\t}\n}\n```\n\n\n## Full example\n\n```go\npackage main\n\nimport (\n\t\"errors\"\n\t\"github.com/golang-jwt/jwt/v5\"\n\t\"github.com/labstack/echo-jwt/v4\"\n\t\"github.com/labstack/echo/v4\"\n\t\"github.com/labstack/echo/v4/middleware\"\n\t\"log\"\n\t\"net/http\"\n)\n\nfunc main() {\n\te := echo.New()\n\te.Use(middleware.Logger())\n\te.Use(middleware.Recover())\n\n\te.Use(echojwt.WithConfig(echojwt.Config{\n\t\tSigningKey: []byte(\"secret\"),\n\t}))\n\n\te.GET(\"/\", func(c echo.Context) error {\n\t\ttoken, ok := c.Get(\"user\").(*jwt.Token) // by default token is stored under `user` key\n\t\tif !ok {\n\t\t\treturn errors.New(\"JWT token missing or invalid\")\n\t\t}\n\t\tclaims, ok := token.Claims.(jwt.MapClaims) // by default claims is of type `jwt.MapClaims`\n\t\tif !ok {\n\t\t\treturn errors.New(\"failed to cast claims as jwt.MapClaims\")\n\t\t}\n\t\treturn c.JSON(http.StatusOK, claims)\n\t})\n\n\tif err := e.Start(\":8080\"); err != http.ErrServerClosed {\n\t\tlog.Fatal(err)\n\t}\n}\n```\n\nTest with\n```bash\ncurl -v -H \"Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ\" http://localhost:8080\n```\n\nOutput should be\n```bash\n*   Trying 127.0.0.1:8080...\n* Connected to localhost (127.0.0.1) port 8080 (#0)\n\u003e GET / HTTP/1.1\n\u003e Host: localhost:8080\n\u003e User-Agent: curl/7.81.0\n\u003e Accept: */*\n\u003e Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ\n\u003e \n* Mark bundle as not supporting multiuse\n\u003c HTTP/1.1 200 OK\n\u003c Content-Type: application/json; charset=UTF-8\n\u003c Date: Sun, 27 Nov 2022 21:34:17 GMT\n\u003c Content-Length: 52\n\u003c \n{\"admin\":true,\"name\":\"John Doe\",\"sub\":\"1234567890\"}\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flabstack%2Fecho-jwt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flabstack%2Fecho-jwt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flabstack%2Fecho-jwt/lists"}