Refreshing a JWT
From DreamFactory
Toddappleton (Talk | contribs) |
|||
| (12 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| − | DreamFactory | + | DreamFactory uses JSON Web Tokens (JWT) to maintain user session on the server side in a stateless manner. One of the |
| − | features of JWT is the ability to refresh | + | features of JWT is the ability to refresh the token without re-authenticating, as long as the JWT (token) is within the allowed |
| − | refresh | + | refresh timeframe since it was created. |
| − | file | + | |
| + | There are two time-to-live (TTL) values that you can configure for JWT in the .env | ||
| + | file. | ||
* DF_JWT_TTL | * DF_JWT_TTL | ||
| − | ** ''Expiration TTL. This the time (in minutes) the token | + | ** ''Expiration TTL. This the time (in minutes) until the token expires. After it expires it can be refreshed until DF_JWT_REFRESH_TTL. |
* DF_JWT_REFRESH_TTL | * DF_JWT_REFRESH_TTL | ||
| − | ** ''Refresh TTL. This the time (in minutes) in which you can refresh the token as times as you want | + | ** ''Refresh TTL. This the time (in minutes) in which you can refresh the token. Between DF_JWT_TTL and DF_JWT_REFRESH_TTL the token can be refreshed as many times as you want without reauthenticating. After DF_JWT_REFRESH_TTL you must log in again.'' |
| − | For example, let's say your expiration TTL (DF_JWT_TTL) is 60 (1 hour) and your refresh TTL (DF_JWT_REFRESH_TTL) is 360 (6 hours). | + | For example, let's say your expiration TTL (DF_JWT_TTL) is 60 (1 hour) and your refresh TTL (DF_JWT_REFRESH_TTL) is 360 (6 hours). Your user authenticates at 09:00 and receives a JWT. This token is valid until 10:00. Between 10:00 and 15:00 it can be refreshed as many times as you like. Keep in mind that refreshing a token does not extend the refresh window! See these tutorials for more information about JWT internals: |
| − | Your user authenticates at | + | |
| − | you | + | |
| − | + | ||
| − | + | * [https://jwt.io/introduction/ JWT Introduction] | |
| + | * [https://scotch.io/tutorials/the-anatomy-of-a-json-web-token The Anatomy of a JSON Web Token] | ||
| − | + | For these examples, assume your current session token is abc.123.efg. | |
| − | + | === Refreshing JWT as an Admin === | |
| − | + | The Admin refresh API endpoint is api/v2/system/admin/session | |
| − | + | Request URL: | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
<pre>PUT https://foo.com/api/v2/system/admin/session?session_token=abc.123.efg</pre> | <pre>PUT https://foo.com/api/v2/system/admin/session?session_token=abc.123.efg</pre> | ||
| − | |||
| + | Note: Session token can also be supplied using X-DreamFactory-Session-Token request header. | ||
| − | - | + | === Refreshing JWT as a User (Non-Admin) === |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| + | The non-admin refresh API endpoint is api/v2/user/session | ||
Request URL: | Request URL: | ||
| − | |||
| − | |||
| − | |||
| − | |||
<pre>PUT https://foo.com/api/v2/user/session?session_token=abc.123.efg</pre> | <pre>PUT https://foo.com/api/v2/user/session?session_token=abc.123.efg</pre> | ||
| − | + | Note: Session token can also be supplied using X-DreamFactory-Session-Token request header. | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | X-DreamFactory-Session-Token | + | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
Latest revision as of 14:54, 27 August 2018
DreamFactory uses JSON Web Tokens (JWT) to maintain user session on the server side in a stateless manner. One of the features of JWT is the ability to refresh the token without re-authenticating, as long as the JWT (token) is within the allowed refresh timeframe since it was created.
There are two time-to-live (TTL) values that you can configure for JWT in the .env file.
- DF_JWT_TTL
- Expiration TTL. This the time (in minutes) until the token expires. After it expires it can be refreshed until DF_JWT_REFRESH_TTL.
- DF_JWT_REFRESH_TTL
- Refresh TTL. This the time (in minutes) in which you can refresh the token. Between DF_JWT_TTL and DF_JWT_REFRESH_TTL the token can be refreshed as many times as you want without reauthenticating. After DF_JWT_REFRESH_TTL you must log in again.
For example, let's say your expiration TTL (DF_JWT_TTL) is 60 (1 hour) and your refresh TTL (DF_JWT_REFRESH_TTL) is 360 (6 hours). Your user authenticates at 09:00 and receives a JWT. This token is valid until 10:00. Between 10:00 and 15:00 it can be refreshed as many times as you like. Keep in mind that refreshing a token does not extend the refresh window! See these tutorials for more information about JWT internals:
For these examples, assume your current session token is abc.123.efg.
Refreshing JWT as an Admin
The Admin refresh API endpoint is api/v2/system/admin/session
Request URL:
PUT https://foo.com/api/v2/system/admin/session?session_token=abc.123.efg
Note: Session token can also be supplied using X-DreamFactory-Session-Token request header.
Refreshing JWT as a User (Non-Admin)
The non-admin refresh API endpoint is api/v2/user/session
Request URL:
PUT https://foo.com/api/v2/user/session?session_token=abc.123.efg
Note: Session token can also be supplied using X-DreamFactory-Session-Token request header.
