{"id":15015811,"url":"https://github.com/fenichelar/ember-simple-auth-token","last_synced_at":"2025-05-15T18:08:30.555Z","repository":{"id":20014345,"uuid":"23281976","full_name":"fenichelar/ember-simple-auth-token","owner":"fenichelar","description":"Ember Simple Auth extension that is compatible with token-based authentication like JWT.","archived":false,"fork":false,"pushed_at":"2024-09-24T19:48:25.000Z","size":3646,"stargazers_count":347,"open_issues_count":5,"forks_count":141,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-04-12T20:45:02.314Z","etag":null,"topics":["ember","ember-addon","javascript","jwt"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/fenichelar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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}},"created_at":"2014-08-24T13:42:51.000Z","updated_at":"2025-02-20T15:15:38.000Z","dependencies_parsed_at":"2023-11-08T06:47:23.211Z","dependency_job_id":"745b00bd-fb57-4d85-b8d9-42956f996f56","html_url":"https://github.com/fenichelar/ember-simple-auth-token","commit_stats":{"total_commits":467,"total_committers":45,"mean_commits":"10.377777777777778","dds":0.6959314775160599,"last_synced_commit":"9cd382a7467244c9b3c1c31a1b1962947c4d52c5"},"previous_names":["jpadilla/ember-cli-simple-auth-token"],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fenichelar%2Fember-simple-auth-token","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fenichelar%2Fember-simple-auth-token/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fenichelar%2Fember-simple-auth-token/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fenichelar%2Fember-simple-auth-token/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fenichelar","download_url":"https://codeload.github.com/fenichelar/ember-simple-auth-token/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254394722,"owners_count":22063984,"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":["ember","ember-addon","javascript","jwt"],"created_at":"2024-09-24T19:47:59.073Z","updated_at":"2025-05-15T18:08:30.522Z","avatar_url":"https://github.com/fenichelar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ember Simple Auth Token\n\n[![github-actions-image]][github-actions]\n[![ember-observer-image]][ember-observer]\n[![npm-image]][npm]\n\nThis Ember addon is an extension of the Ember Simple Auth library which provides a basic token authenticator and a JSON Web Tokens (jwt) token authenticator with automatic refresh capability. You can find more about why JSON Web Tokens are so awesome in [this blog](https://medium.com/@extio/understanding-json-web-tokens-jwt-a-secure-approach-to-web-authentication-f551e8d66deb) and [here as well](https://medium.com/swlh/all-you-need-to-know-about-json-web-token-jwt-8a5d6131157f).\n\n**Because users' credentials and tokens are exchanged between the Ember.js app and the server, you must use HTTPS for this connection!**\n\n## Demo\n\nThe test-app has an example of implementing jwt with auto-refresh. It can be run by cloning the repo, then:\n\n```node\ncd ember-simple-auth-token\nnpm i\nnpm start // express server\n// or\nnpm run mirage // mirage api mock\n// navigate to http://localhost:4201\n```\n\n## Compatibility\n\n| Library | Compatible Versions |\n| - | - |\n| node | v16, v18, v20 |\n| ember | v4.4, v4.8, v4.12, v5.4, v5.8 |\n| ember-simple-auth | v6 |\n| ember-auto-import | v2 |\n| webpack | v5 |\n\n## Installation\n\nEmber Simple Auth Token can be installed with [Ember CLI](https://ember-cli.com) by running:\n\n```\nember install ember-simple-auth-token\n```\n\nYou must manually install a compatible version of `ember-simple-auth`.\n\n## Setup\n\n### Calling session.setup() on ember-simple-auth session service\n\n`ember-simple-auth` no longer uses an initializer to wire up the session service. Your applicaton must implement an application route to call `session.setup()` on the `ember-simple-auth` session service:\n\n```js\n// app/routes/application.js\nimport Route from '@ember/routing/route';\nimport { inject } from '@ember/service';\n\nexport default class ApplicationRoute extends Route {\n  @inject session;\n\n  async beforeModel() {\n    await this.session.setup();\n  }\n}\n```\n\n### Routing\n\nIt is [recommended by](https://github.com/mainmatter/ember-simple-auth) `ember-simple-auth` to use an authenticated route in your application, placing all secure routes under it, and employing `session.requireAuthentication()` in `beforeModel`.\n\n```javascript\n// app/router.js\nimport EmberRouter from '@ember/routing/router';\nimport config from 'test-app/config/environment';\n\nexport default class Router extends EmberRouter {\n  location = config.locationType;\n  rootURL = config.rootURL;\n}\n\nRouter.map(function () {\n  this.route('login');\n  this.route('authenticated', { path: '' }, function() {\n    // all routes that require the session to be authenticated\n    this.route('index', { path: '' });\n    this.route('secure');\n  });\n});\n\n// app/routes/authenticated.js\nimport Route from '@ember/routing/route';\nimport { inject as service } from '@ember/service';\n\nexport default class AuthenticatedRoute extends Route {\n  @service session;\n\n  beforeModel(transition) {\n    this.session.requireAuthentication(transition, 'login');\n  }\n}\n```\n\nLeaving `path: ''` in your router for the authenticated root will keep all secure roots at the top-level, without an extra added path segment. You can also use a path, such as `path: 'application'`, etc. to separate the secured routes from non-secured routes in your URL structure. EG: `myapp/application/secure` and `myapp/login`.\n\nAll authenticated routes can then inherit the authenticated route:\n\n```javascript\n// app/routes/authenticated/secure.js\nimport Route from '../authenticated';\n\nexport default class SecureRoute extends Route {}\n```\n\nYour project's folder structure would look like this:\n\n```\nproject\n│\n└───app\n    │   router.js\n    │\n    └───routes\n        │   application.js\n        │   authenticated.js\n        │   login.js\n        │\n        └───authenticated\n                secure.js\n                index.js\n```\n\nMake sure `ember-simple-auth` is configured to utilize this route structure in your environment file:\n\n```javascript\n// config/environment.js\nENV['ember-simple-auth'] = {\n  routeAfterAuthentication: 'authenticated.index',\n  routeAfterInvalidation: 'login',\n};\n```\n\n### Authenticator\n\nIn order to use the token authenticator or the JSON Web Token authenticator, the application should have a route for login. In most cases, the login route will display a form with a `username` and `password` field. On form submit, the `authenticate` action will be called on the `session`:\n\n```js\n// app/router.js\nRouter.map(function() {\n  this.route('login');\n});\n```\n\n```html\n{{! app/templates/login.hbs }}\n\u003cform {{on \"submit\" this.authenticate}}\u003e\n  \u003clabel for=\"username\"\u003eLogin\u003c/label\u003e\n  {{input id='username' placeholder='Enter Login' value=username}}\n  \u003clabel for=\"password\"\u003ePassword\u003c/label\u003e\n  {{input id='password' placeholder='Enter Password' type='password' value=password}}\n  \u003cbutton type=\"submit\"\u003eLogin\u003c/button\u003e\n\u003c/form\u003e\n```\n\n```js\n// app/controllers/login.js\nimport Controller from '@ember/controller';\nimport { service } from '@ember/service';\nimport { action } from '@ember/object';\n\nexport default class LoginController extends Controller {\n  @service session;\n  @service router;\n  username = 'username';\n  password = 'password';\n\n  @action\n  async authenticate(e) {\n    e.preventDefault();\n    e.stopPropagation();\n    const authenticator = 'authenticator:jwt'; // or 'authenticator:token'\n    this.session.authenticate(authenticator, {username: this.username, password: this.password}).catch(err =\u003e {\n      if (err.status === 401) {\n        alert('Incorrect username or password');\n        return;\n      }\n      let errorMessage = '';\n      if (err.text) {\n        try {\n          if (this.isJsonResponse(err.text)) {\n            errorMessage = JSON.parse(err.text).errors[0].message;\n          } else {\n            errorMessage = err.text;\n          }\n        } catch(er) {\n          alert('An unexpected error occurred. ' + er.toString());\n        }\n      } else {\n        errorMessage = err;\n      }\n      alert(errorMessage);\n    });\n  }\n\n  isJsonResponse(response) {\n    if (typeof response !== 'string') return false;\n    try {\n      const result = JSON.parse(response);\n      const type = Object.prototype.toString.call(result);\n      return type === '[object Object]' || type === '[object Array]';\n    } catch (err) {\n      return false;\n    }\n  }\n}\n\n```\n\n#### JSON Web Token Authenticator\n\nThe JSON Web Token authenticator will decode the token and look for the expiration time. The difference in the current time and the token expiration time is calculated. The `refreshLeeway` is subtracted from this value to determine when the automatic token refresh request should be made.\n\n```js\n// config/environment.js\nENV['ember-simple-auth-token'] = {\n  refreshAccessTokens: true,\n  refreshLeeway: 300 // refresh 5 minutes (300 seconds) before expiration\n};\n```\n\nThe `refreshLeeway` can be specified to send the requests before the token expires to account for clock skew. Some libraries like [PyJWT](https://github.com/jpadilla/pyjwt), [ruby-jwt](https://github.com/jwt/ruby-jwt), and [node-jsonwebtoken](https://github.com/auth0/node-jsonwebtoken) also support specifying a clock tolerance when verifying the token. Leaving `refreshLeeway` undefined (or zero) could result in the addon's `invalidate()` function firing at the same time or immediately before the `refreshAccessToken()` api request. In this case, the user would be invalidated and logged out regardless of setting `refreshAccessTokens: true`. Setting a value for `refreshLeeway` (in seconds or decimals of a second) longer than your expected api response time should prevent this situation.\n\nSample JSON Web Token:\n\n```js\nconst encodedToken = eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImpvaG4iLCJleHAiOjk4MzQzMjM0fQ.FKuPdB7vmkRfR2fqaWEyltlgOt57lYQ2vC_vFXtlMMJfpCMMq0BEoXEC6rLC5ygORcKHprupi06Zmx0D8nChPQ;\nconst decodedHeader = {\n  'alg': 'HS512',\n  'typ': 'JWT'\n};\nconst decodedPayload = {\n  'username': 'username',\n  'exp': 98343234 // \u003cISO-8601\u003e UTC seconds\n};\n```\n\nTo debug JSON Web Token issues, see [jwt](https://jwt.io).\n\nThe JSON Web Token authenticator supports both separate access tokens and refresh tokens. By specifying the `tokenPropertyName` and the `refreshTokenPropertyName` to the same value, the same token will be used for both access and refresh requests. For more information about refresh tokens, see [this blog](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them).\n\n#### Adapter\n\nIn order to send the token with all API requests made to the server, set the headers object in the adapter:\n\n```js\n// app/adapters/application.js\nimport JSONAPIAdapter from '@ember-data/adapter/json-api';\nimport { service } from '@ember/service';\n\nexport default class ApplicationAdapter extends JSONAPIAdapter {\n  namespace = 'api';\n\n  @service session;\n\n  get headers() {\n    if (this.session.isAuthenticated) {\n      return {\n        Authorization: `Bearer ${this.session.data.authenticated.token}`,\n      };\n    } else {\n      return {};\n    }\n  }\n\n  handleResponse(status) {\n    if (status === 401 \u0026\u0026 this.session.isAuthenticated) {\n      this.session.invalidate();\n    }\n  }\n}\n```\n\n### Mixins\n\nMixin support has been removed from `ember-simple-auth` v6. Mixins are therefore no longer supported in `ember-simple-auth-token`. If you need mixin support, please use the pre Ember 5, non Embroider version of `ember-simple-auth-token`.\n\n### Customization Options\n\n#### Token Authenticator\n\n```js\n// config/environment.js\nENV['ember-simple-auth-token'] = {\n  serverTokenEndpoint: '/api/token-auth/', // Server endpoint to send authenticate request\n  tokenPropertyName: 'token', // Key in server response that contains the access token\n  headers: {} // Headers to add to the authenticate request\n};\n```\n\n#### JSON Web Token Authenticator\n\nIn addition to all the customization options available to the token authenticator:\n\n```js\n// config/environment.js\nENV['ember-simple-auth-token'] = {\n  tokenDataPropertyName: 'tokenData', // Key in session to store token data\n  refreshAccessTokens: true, // Enables access token refreshing\n  tokenExpirationInvalidateSession: true, // Enables session invalidation on token expiration\n  serverTokenRefreshEndpoint: '/api/token-refresh/', // Server endpoint to send refresh request\n  refreshTokenPropertyName: 'refresh_token', // Key in server response that contains the refresh token\n  tokenExpireName: 'exp', // Field containing token expiration\n  refreshLeeway: 0, // Amount of time in seconds to send refresh request before token expiration\n  tokenRefreshInvalidateSessionResponseCodes: [401, 403], // Array of response codes that cause an immediate session invalidation if received when attempting to refresh the token\n  refreshAccessTokenRetryAttempts: 0, // Number of token retry attempts to make\n  refreshAccessTokenRetryTimeout: 1000, // Amount of time in milliseconds to wait between token refresh retry attempts\n  tokenRefreshFailInvalidateSession: false // Enables session invalidation if all token refresh retry requests fail\n};\n```\n\n## mirage\n\nThe test-app now uses mirage.js via [ember-cli-mirage](https://github.com/miragejs/ember-cli-mirage) to simulate a server response to the `/token-auth` and `/token-refresh` api endpoints. Run the test-app with mirage support (`ember s --environment=mirage`) from within the cloned repo:\n\n```node\ncd ember-simple-auth-token\nnpm run mirage\n```\n\nLaunching the test-app with `npm run mirage` or `npm run mirage-test` will prevent the express server from running. The mirage mock server runs in test mode (`ember s --environment=test`) simply because the api responses are logged in the browser console and can more easily be inspected. If using FastBoot in the cloned repo, the mirage api mock will not run. You must instead use the express server via `npm start`.\n\n## express server\n\nThe test-app also ships with an express server which is run with `ember s --environment=development` from within the cloned repo:\n\n```node\ncd ember-simple-auth-token\nnpm start\n```\n\nLaunching the test-app with `npm start` will prevent the mirage api mock from running.\n\nBoth mirage and express have a `/api/helloworld` GET endpoint to verify the backend service is running. A call to this endpoint is commented out in `test-app/app/routes/application.js`.\n\n## Testing Configuration\n\nFor acceptance testing, token refresh must be disabled to allow the test to exit. Therefore, the following configuration should be set:\n\n```js\n// config/environment.js\nif (environment === 'test') {\n  ENV['ember-simple-auth-token'] = {\n    refreshAccessTokens: false,\n    tokenExpirationInvalidateSession: false,\n  };\n}\n```\n\nIf your tests are still timing out due to a setTimeout(), you can manually end the timers used in `ember-simple-auth-token` at the end of each of your tests:\n\n```javascript\nimport { module, test } from 'qunit';\nimport { setupTest } from 'test-app/tests/helpers';\nimport { getSettledState } from '@ember/test-helpers';\n\nmodule('Unit | Authenticator | authenticators/jwt.js', function (hooks) {\n  setupTest(hooks);\n\n  hooks.beforeEach(function() {\n    this.owner.application.jwt = this.owner.lookup('authenticator:jwt');\n  });\n\n  const clearState = jwt =\u003e {\n    let state = getSettledState();\n    if (state.hasPendingTimers || state.hasRunLoop) {\n      jwt.cancelAllTimers();\n    }\n  };\n\n  test('your test message`', function(assert) {\n    assert.expect(1);\n    // ... tests\n    clearState(this.owner.application.jwt);\n  });\n});\n```\n\n## Running tests in a cloned repo\n\nember-cli / qunit tests can be run via the command line from within the cloned repo:\n\n```node\ncd ember-simple-auth-token\nnpm run test\n```\n\nTests can also be run in the browser, which will refresh and rerun all tests after any change to a test:\n\n```node\ncd ember-simple-auth-token\nnpm run mirage-test\n// visit http://localhost:4201/tests\n```\n\n## Upgrade Notes\n\nVersion 6:\n\n- mixins are no longer supported by `ember-simple-auth-token`\n\n- `ember-simple-auth` requires calling `session.setup()` in your app's `routes/application.js`\n\n- if `refreshLeeway` is not set in your app's `config/environment.js`, it will default to 0 seconds. This may create a race condition where `handleAccessTokenExpiration()` could be called before `refreshAccessToken()` completes, even if `refreshAccessTokens = true`. If this happens, you can set `refreshLeeway` to a positive number in your `config/environment.js` to prevent the user being logged out.\n\n\n[github-actions-image]: https://github.com/fenichelar/ember-simple-auth-token/actions/workflows/test.yml/badge.svg\n[github-actions]: https://github.com/fenichelar/ember-simple-auth-token/actions/workflows/test.yml\n[ember-observer-image]: https://emberobserver.com/badges/ember-simple-auth-token.svg\n[ember-observer]: https://emberobserver.com/addons/ember-simple-auth-token\n[npm-image]: https://img.shields.io/npm/v/ember-simple-auth-token.svg\n[npm]: https://www.npmjs.com/package/ember-simple-auth-token\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffenichelar%2Fember-simple-auth-token","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffenichelar%2Fember-simple-auth-token","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffenichelar%2Fember-simple-auth-token/lists"}