I refresh_token refreshes access_token
Keycloak session management, get accessToken and refreshToken, based on the accessToken to exchange user data or participate in KeycloakAPI requests, when the accessToken expires, you can use the refreshToken to exchange the new accessToken and refreshToken. When accessToken expires, you can use refreshToken to exchange new accessToken and refreshToken.
This piece then gets a new token object based on the previous refresh_token
refresh_token and access_token expiration date configuration
- The validity period of refresh_token is generally longer than that of access_token, which is a prerequisite for exchanging a refresh_token for a new access_token, so here's how to configure a timeout period for these two tokens.
- refresh_token timeout time refresh_expires_in, in realms settings, select tokens to configure, set for SSO Session Max
Access_token timeout expires_in,In realms settings, select tokens to configure the settings for Access Token Lifespan.
This user session, corresponding to the sessionId (session_state) can be found in the browser cookie, or in the kc management background of the user - "session" view, this sessionId is accessed by the client, will be refreshed this "start" time, and the "last access" time, when your access_token expires, you will be able to access the "start" time and "last access" time. "last access" time, when your access_token expires, it will refresh the "start" time and "last access" time.When you refresh the access_token via refresh_token, this "last accessed" time will be updated as well!As shown in the figure
If a user accesses a resource and the token expires while refresh_token (sso session max) has not, you can get a new token by refreshing_token, and a new session will be generated; however, if refresh_token also expires, it will jump to the login page and authenticate from a new one, and the The session is also deleted.
III Configuration of refresh_token expiration time
There are four options in Domain Settings->Tokens to control the timeout for refresh_token
- SSO Session Idle
- SSO Session Max
- Client Session Idle
- Client Session Max
The following figure of four options, the configuration is problematic, the correct configuration should be the longest time is greater than the idle time, the following configuration does not make sense, the validity of this time to use the smallest of the four options [sso session idle time, the maximum time of the sso session, client session Idle and client session Max]
If configured normally, when the idle time and maximum time are not the same, theThe true refresh_token_expire time will depend on the value of client Session IdleThe following configurations are available
The session expires when the refresh_token expires at (session max time), and theIt doesn't clear up immediately.It will be maintained by keycloak.Automatically clears after up to session max timeAnd if the user does refresh_token before this time, it will indicate that the token is inactive, and the session will also be cleared as well, indicating that the token has expired, as shown in the following two diagrams:
When session idle and session max are not the same (sso session max and client session max), the user's session is deleted when sso session max expires, theAnd sso session max is globalSSO Session Max and Client Sesssion Max can be set by the following 6 parameters, it will be the longest one in the keycloak background cleanup session, when the session reaches the session idle time, if the user actively refresh the token, the session will also be actively deleted, it will not wait for the session max time to reach and then delete. When the session reaches the idle time, if the user takes the initiative to refresh the token, the session will be deleted, not waiting for the session max time to reach before deleting.
IV Role of Session Idle and Session Max
Idle time of the session (Idle), means in how long no refresh_token is used for refreshing, the session (session_state) will expire, and can no longer use refresh_token to change to a new token, then the user needs to go back to the login page again, to complete a new authentication; this is mainly for a long time not to operate the user, kc needs to let it complete the user name and password confirmation again. This is mainly for users who have not operated for a long time, and kc needs to let them re-confirm their username and password.
Note: If the "Remember Me" function is enabled, because if the "Remember Me" function is enabled, the "Remember Me" function will be disabled.
Your session availability is equal to "Remember my availability."If you configure "sso session idle", your "sso session idle" configuration will be invalidated. If you remember that I configured the maximum time and the idle time, then the token will be generated and verified using the remember me time, as shown in the source code in keycloak14.0.0.-services.
【
Session idle has a 2-minute error in judgmentThe main consideration is the synchronization of data in the DC cluster, for example, if the idle is valid for 5 minutes, then the real expiration time is 5+2 for 7 minutes] When it comes to 7 minutes, when you get the session whether it is online or not, the result will return false.
In the above code, the isSessionValid method will beWhen validating the token and refreshing the tokenIf we want session idle and session max to be used correctly, we need to modify the kc source code's
. () method, change the checkExpiration in the verifyRefreshToken method parameter to false, as shown:
Finally, the following figure configures the access_token to be valid for 2 minutes, the refresh_token to be up to 30 days, and the session to be idle for 7 days; the configuration serves the following purpose: the user's access_token will expire every 2 minutes, and then the user will go through the refresh_token to change to a new access_token, and if the user hasn't changed the access_token for 7 days, the session will expire. If the user hasn't changed the token for 7 days, the session expires. If the session has been created for 30 days, the session also expires, and the user returns to the login page to re-authenticate.
In fact, when session idle and session max are equal, the expiration time of your refresh_token will be decreasing all the time, from the first time you apply for this refresh_token, this expiration time will be fixed, it has nothing to do with you changing to a new token; but if session idle and session max are not equal (max>idle), every time you change to a new token, the expiration time of your new refresh_token will be counted from the beginning. max are not equal (max>idle), every time you change a new token, the expiration time of your new refresh_token is counted from the beginning, and its size is equal to the size of the session idle, which is also the reason why the session will expire if you don't refresh the token within the session idle time. Please note: we need to replace the old refresh_token with the new refresh_token, because the old one has already expired.
Five offline_access roles to make refresh_token never expire
For the user to log in, if the authorization code mode, if you want to refresh_token never expire, you can use offline_access this kind of scope , provided that you in the authentication interface call, scope place need to add the option of offline_access, and you are the authorization code of the authentication method, such as Figure:
In the current client template, you also need to add this offline_access client template
Add the offline_access role for the specified user, if this role is not present, you need to add it manually.
When Offline session Max limit is not turned on, your refresh token just never expires, as shown here
If you wish to control the expiration date of refresh_token, you can turn on the restriction
The timeout for the generated refresh_token will be 5 minutes, 300 seconds, or the 4 configurations above, whoever is small enough to use it, as shown:
Refresh_token's JWT string, after parsing Typ there are two types, Refresh and Offline, the former's is through SSO Session Max to control its validity period, while the latter Offline is to apply for the token, the use of the scope contains the offline_access, it corresponds to the The corresponding refresh_token has no expiration date.