{"id":23765795,"url":"https://github.com/solidusio-contrib/solidus_jwt","last_synced_at":"2025-09-05T09:33:02.348Z","repository":{"id":43063378,"uuid":"154775069","full_name":"solidusio-contrib/solidus_jwt","owner":"solidusio-contrib","description":"Use json web tokens to authenticate solidus api requests","archived":false,"fork":false,"pushed_at":"2023-05-24T14:33:37.000Z","size":152,"stargazers_count":11,"open_issues_count":0,"forks_count":13,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-12-20T14:33:02.450Z","etag":null,"topics":["solidus","solidus-extensions"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/solidusio-contrib.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":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2018-10-26T03:59:24.000Z","updated_at":"2024-01-15T11:13:21.000Z","dependencies_parsed_at":"2023-02-08T09:20:26.698Z","dependency_job_id":null,"html_url":"https://github.com/solidusio-contrib/solidus_jwt","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_jwt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_jwt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_jwt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_jwt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solidusio-contrib","download_url":"https://codeload.github.com/solidusio-contrib/solidus_jwt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232034913,"owners_count":18463363,"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":["solidus","solidus-extensions"],"created_at":"2024-12-31T23:17:45.181Z","updated_at":"2024-12-31T23:17:45.837Z","avatar_url":"https://github.com/solidusio-contrib.png","language":"Ruby","readme":"SolidusJwt\n==========\n\n[![CircleCI](https://circleci.com/gh/solidusio-contrib/solidus_jwt.svg?style=svg)](https://circleci.com/gh/solidusio-contrib/solidus_jwt)\n[![Gem Version](https://badge.fury.io/rb/solidus_jwt.svg)](https://badge.fury.io/rb/solidus_jwt)\n\nThis gem gives [Solidus](https://github.com/solidusio/solidus) stores the ability to authenticate API requests with\nJSON Web Tokens.\n\nTo use this gem, you should have a sound understanding of **JSON web tokens**. For more information you can visit the [**Offical JWT Website**](https://jwt.io/introduction/). It may also be useful to look at [**ruby-jwt**](https://github.com/jwt/ruby-jwt), the library required by this gem.\n\n\nInstallation\n------------\n\nAdd solidus_jwt to your Gemfile:\n\n```ruby\ngem 'solidus'\ngem 'solidus_jwt'\n```\n\nBundle your dependencies and run the installation generator:\n\n```shell\nbundle\nbundle exec rails g solidus_jwt:install\n```\n\nConfiguration\n-------------\n```ruby\n# config/initializers/solidus_jwt.rb\n\nSolidusJwt::Config.configure do |config|\n  config.jwt_secret           = 'secret'\n  config.allow_spree_api_key  = true\n  config.jwt_algorithm        = 'HS256'\n  config.jwt_expiration       = 3_600\n  config.jwt_options          = { only: %i[email first_name id last_name] }\n  config.refresh_expiration   = 2_592_000\nend\n```\n\n#### `jwt_secret`:\nDefaults to `Rails.application.secret_key_base`. The encryption key, should be kept secret and secure.\n\n#### `allow_spree_api_key`:\nDefaults to `true`. When true, the `spree_api_key` is still accepted as an authentication token along with json web tokens.\n\n#### `jwt_algorithm`:\nDefaults to `HS256`. See: https://github.com/jwt/ruby-jwt#algorithms-and-usage for more information on accepted algorithms.\n\n#### `jwt_expiration`:\nDefaults to `3600` (1 hour). The amount of time in seconds that the token should last for.\n\n#### `jwt_options`\nDefaults to `{ only: %i[email first_name id last_name] }`. These options are passed into `Spree::User#as_json` when serializing the token's payload.  Keep in mind that the more information included, the larger the token will be. It may be in your best interest to keep it short and simple.\n\n#### `refresh_expiration`:\nDefaults to `2592000` (30 days). The amount of time in seconds that the token should last for.\n\nUsage\n-------------\n### Generating and decoding a token:\n\n```ruby\nSolidusJwt::Config.configure do |config|\n  config.jwt_secret = 'secret'\nend\n\nuser = Spree::User.new email: 'email@example.com', id: 1\ntoken = user.generate_jwt_token(expires_in: 1.hour.to_i) # Expiration is time in seconds\n# eyJhbGciOiJIUzI1NiJ9.eyJpZCI6MSwiZW1haWwiOiJlbWFpbEBleGFtcGxlLmNvbSIsInN1YiI6MSwiZXhwIjoxNTcyNTg2NTA3LCJpYXQiOjE1NzI1ODI5MDcsImlzcyI6InNvbGlkdXMifQ.UEmPLClCmOii_5-Qa6fB_ToGavIJYY6PAyfhARitMwI\n\nSolidusJwt.decode(token)\n# [\n#   {\n#     \"id\"=\u003e1, \n#     \"email\"=\u003e\"email@example.com\", \n#     \"sub\"=\u003e1, \n#     \"exp\"=\u003e1572586507, \n#     \"iat\"=\u003e1572582907, \n#     \"iss\"=\u003e\"solidus\"\n#   },\n#   {\"alg\"=\u003e\"HS256\"}\n# ]\n```\n\n### Autenticate through the API\n\nIf authenticating through the API, you must have \n[solidus_auth_devise](https://github.com/solidusio/solidus_auth_devise) setup\nbecause `solidus_jwt` piggybacks off of the [Devise](https://github.com/plataformatec/devise) \ngem. This enables authentication through a single point. If you implement \n[Devise Lockable](https://www.rubydoc.info/github/plataformatec/devise/master/Devise/Models/Lockable), \nthen locking is respected both on the front-end as well as on the API.\n\n```ruby\nPOST /oauth/token\n{\n  \"username\": \"user@example.com\"\n  \"password\": \"secret\"\n  \"grant_type\": \"password\"\n}\n\n# { \"access_token\": \"abc.123.efg\", \"refresh_token\": \"123456\" }\n```\n\nYou can now use the `access_token` to authentication with the \n[Solidus API](https://github.com/solidusio/solidus/tree/master/api) in place\nof the `spree_api_key`.\n\n#### Matching token to a user\n\nBy default, the token matches a user using the `Spree::User.for_jwt` method. This methods\nFinds a user by id using the subject claim of the token. If you want to customize how the\nsubject claim is interpreted you can override this method\n\n```ruby\ndef self.for_jwt(sub)\n  # find_by(id: sub)\n  find_by(my_external_id: sub)\nend\n```\n\n### Obtain a refresh token\n\nTo refresh your access token, instead of re-authenticating you can send\na refresh token.\n\n```ruby\nPOST /oauth/token\n{\n  \"refresh_token\": \"123456\"\n  \"grant_type\": \"refresh_token\"\n}\n\n# { \"access_token\": \"hij.456.klm\", \"refresh_token\": \"789abc\" }\n```\n\n### Invalidate refresh tokens for a user\n\nIt is good practice set the lifetime of an access token to be short. In case an\naccess token is compromised, the attacker will only have access for a short time.\n\nTo force a user to have to reauthencate rather than using a refresh token,\nyou can do the following:\n\n```ruby\n# Invalidate all refresh tokens for a user\nSolidusJwt::Token.invalidate(user)\n```\n\n### Distributing a Token Using 'solidus_auth_devise' on front-end:\n\nTo have the `solidus_auth_devise` gem distribute a token back to the client\nyou can do the following:\n```ruby\n# app/controllers/application_controller.rb\ninclude SolidusJwt::Distributor::Devise\n```\n\nWhen a user logs in, the redirect will contain the header `X-SPREE-TOKEN`.\n\nTesting\n-------\n\nFirst bundle your dependencies, then run `rake`. `rake` will default to building the dummy app if it does not exist, then it will run specs, and [Rubocop](https://github.com/bbatsov/rubocop) static code analysis. The dummy app can be regenerated by using `rake test_app`.\n\n```shell\nbundle\nbundle exec rake\n```\n\nWhen testing your applications integration with this extension you may use it's factories.\nSimply add this require statement to your spec_helper:\n\n```ruby\nrequire 'solidus_jwt/factories'\n```\n\nCopyright (c) 2018 [name of extension creator], released under the New BSD License\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidusio-contrib%2Fsolidus_jwt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolidusio-contrib%2Fsolidus_jwt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidusio-contrib%2Fsolidus_jwt/lists"}