Forever sessions

From DreamFactory
Jump to: navigation, search
DreamFactoryTutorialsForever sessions
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
== Tutorial ==
+
This tutorial builds on the concepts covered in the other User Authentication tutorials. JWT session tokens can only be refreshed prior to the <code>DF_JWT_REFRESH_TTL</code> timer expiring. Normally when you refresh a JWT session token you get a new token but your refresh ttl window stays the same. It does not reset. Eventually when you will go outside this refresh ttl window you can no longer refresh your old token for a new one. You will have re-authenticate in order to obtain a brand new token.
  
−
Setting up user session tokens so that the session may be refreshed indefinitely without providing credentials again. This is similar to the Facebook model, where a device remains logged into an account forever, unless explicitly logged out.
+
However, when you use a forever session, every time you refresh your token the system also resets the refresh ttl window. This means that the refresh ttl window starts fresh when you get the new token. This will allow you to refresh your token forever as long as you refresh it within the refresh ttl window (which keeps extending as you refresh). ONCE THE REFRESH TTL WINDOW IS PASSED NO TOKEN CAN EVER BE REFRESHED. YOU WILL NEED TO RE-AUTHENTICATE AT THIS POINT.
  
−
== Background ==
+
==Configuration==
  
−
''This tutorial builds on the concepts covered in [[DreamFactory/Tutorials/Logging_in#Log_in_as_an_User_.28non-admin.29|Logging in]], [[DreamFactory/Tutorials/Access_Using_JWT_and_API_Key|Access using JWT and API Key]], and [[DreamFactory/Tutorials/Refreshing_a_JWT|Refreshing a JWT]].''
+
To set up forever sessions, configure <code>DF_ALLOW_FOREVER_SESSIONS</code> and <code>DF_JWT_TTL</code> in the <code>.env</code> file. Note that <code>DF_JWT_REFRESH_TTL</code> will reset upon refreshing a forever token when <code>DF_ALLOW_FOREVER_SESSIONS</code> is set to <code>true</code>.
  
−
You may configure user sessions to never expire if a client sets <code>"remember_me": true</code> at login. This means that a session may be refreshed forever without providing the user's credentials again. The initial <code>session_token</code> will be valid until the token TTL (time-to-live) expires, after which a new <code>session_token</code> value may be obtained by simply refreshing the original session. This may be repeated for the same session indefinitely, or until an explicit logout (session deletion).
+
The <code>.env</code> file for a DreamFactory instance is located at the installation's root directory. Refer to the example <code>.env-dist</code> file [https://github.com/dreamfactorysoftware/dreamfactory/blob/master/.env-dist provided in the GitHub repository here]. <br />
  
−
== Configuration ==
+
'''1. Set <code>DF_ALLOW_FOREVER_SESSIONS</code>'''
  
−
To set up forever sessions, we will configure <code>DF_ALLOW_FOREVER_SESSIONS</code> and <code>DF_JWT_TTL</code> in the <code>.env</code> file. Note that <code>DF_JWT_REFRESH_TTL</code> will be ignored once <code>DF_ALLOW_FOREVER_SESSIONS</code> is set to <code>true</code>.
+
In <code>.env</code>, add or un-comment this line and set the value to <code>true</code>:
  
−
The <code>.env</code> file for a DreamFactory instance is located at the installation's root directory. Refer to the example <code>.env-dist</code> file [https://github.com/dreamfactorysoftware/dreamfactory/blob/master/.env-dist provided in the GitHub repository here]. <br /> <br />
+
<pre>DF_ALLOW_FOREVER_SESSIONS=true</pre>
  
−
'''1. Set <code>DF_ALLOW_FOREVER_SESSIONS</code>'''
+
To make sure forever session is enabled, make the following API call.
−
: <br />
+
 
−
:
+
<pre>GET http://{url}/api/v2/system/environment</pre>
−
: In <code>.env</code>, add or un-comment this line and set the value to <code>true</code>:
+
 
−
:
+
Look for the following in your response.
−
: <pre>DF_ALLOW_FOREVER_SESSIONS=true</pre>
+
 
−
:: <br />
+
<pre>
 +
...
 +
"authentication":{
 +
    ....
 +
    "allow_forever_sessions":true
 +
    ....
 +
}
 +
...
 +
</pre>
  
 
'''2. Set <code>DF_JWT_TTL</code>'''
 
'''2. Set <code>DF_JWT_TTL</code>'''
−
: <br />
+
 
−
:
+
In <code>.env</code>, add or un-comment this line and set the value to your desired TTL in minutes. A session refresh will be required to receive a new session token after this many minutes.
−
: In <code>.env</code>, add or un-comment this line and set the value to your desired TTL in minutes. A session refresh will be required to receive a new <code>session_token</code> after this many minutes.
+
 
−
:
+
<pre>DF_JWT_TTL=720</pre>
−
: <pre>DF_JWT_TTL=720</pre>
+
 
−
:
+
The above setting will require a session refresh every 12 hours (720 minutes).
−
: The above setting will require a session refresh every 12 hours (720 minutes).
+
 
−
:  
+
'''3. Clear config'''
 +
 
 +
Run this command from the root directory for your DreamFactory instance installation.
 +
 
 +
<code>php artisan config:clear</code>
  
 
== Usage ==
 
== Usage ==
  
−
* Users instantiate sessions as documented in the [[DreamFactory/Tutorials/Logging_in#Log_in_as_an_User_.28non-admin.29|Logging in]] tutorial.
+
* A forever session is instantiated if the client sets <code>"remember_me": true</code> at login.
−
* A forever session is instantiated if the client sets <code>"remember_me": true</code> at login, as documented in the [[DreamFactory/Tutorials/Logging_in#Log_in_as_an_User_.28non-admin.29|Logging in]] tutorial.
+
* Forever sessions may be refreshed to receive a new session token at any time as long as the <code>DF_JWT_REFRESH_TTL</code> timer doesn't expire.
−
* Sessions may be refreshed to receive a new <code>session_token</code> as documented in the [[DreamFactory/Tutorials/Refreshing_a_JWT|Refreshing a JWT]] tutorial at any time, including after <code>DF_JWT_TTL</code> expires.
+
* If a session is deleted or the refresh ttl is expired, the token can no longer be refreshed. Logging in again with valid credentials will be required.
−
* If a session is deleted as documented in the [[DreamFactory/Tutorials/Logging_out|Logging out]] tutorial, it may no longer be refreshed. Logging in again with valid credentials will be required.
+

Latest revision as of 20:39, 28 September 2017

This tutorial builds on the concepts covered in the other User Authentication tutorials. JWT session tokens can only be refreshed prior to the DF_JWT_REFRESH_TTL timer expiring. Normally when you refresh a JWT session token you get a new token but your refresh ttl window stays the same. It does not reset. Eventually when you will go outside this refresh ttl window you can no longer refresh your old token for a new one. You will have re-authenticate in order to obtain a brand new token.

However, when you use a forever session, every time you refresh your token the system also resets the refresh ttl window. This means that the refresh ttl window starts fresh when you get the new token. This will allow you to refresh your token forever as long as you refresh it within the refresh ttl window (which keeps extending as you refresh). ONCE THE REFRESH TTL WINDOW IS PASSED NO TOKEN CAN EVER BE REFRESHED. YOU WILL NEED TO RE-AUTHENTICATE AT THIS POINT.

Configuration

To set up forever sessions, configure DF_ALLOW_FOREVER_SESSIONS and DF_JWT_TTL in the .env file. Note that DF_JWT_REFRESH_TTL will reset upon refreshing a forever token when DF_ALLOW_FOREVER_SESSIONS is set to true.

The .env file for a DreamFactory instance is located at the installation's root directory. Refer to the example .env-dist file provided in the GitHub repository here.

1. Set DF_ALLOW_FOREVER_SESSIONS

In .env, add or un-comment this line and set the value to true: 

DF_ALLOW_FOREVER_SESSIONS=true

To make sure forever session is enabled, make the following API call. 

GET http://{url}/api/v2/system/environment

Look for the following in your response. 

...
"authentication":{
    ....
    "allow_forever_sessions":true
    ....
}
...

2. Set DF_JWT_TTL

In .env, add or un-comment this line and set the value to your desired TTL in minutes. A session refresh will be required to receive a new session token after this many minutes. 

DF_JWT_TTL=720

The above setting will require a session refresh every 12 hours (720 minutes).

3. Clear config

Run this command from the root directory for your DreamFactory instance installation.

php artisan config:clear

Usage

  • A forever session is instantiated if the client sets "remember_me": true at login.
  • Forever sessions may be refreshed to receive a new session token at any time as long as the DF_JWT_REFRESH_TTL timer doesn't expire.
  • If a session is deleted or the refresh ttl is expired, the token can no longer be refreshed. Logging in again with valid credentials will be required.
Retrieved from "https://wiki.dreamfactory.com/index.php?title=DreamFactory/Tutorials/Forever_sessions&oldid=34004"