Understanding the refresh token
You can use the refresh token to retrieve new ID and access tokens. By default, the refresh token expires 30 days after your application user signs into your user pool. When you create an application for your user pool, you can set the application's refresh token expiration to any value between 60 minutes and 10 years.
The Mobile SDK for iOS, Mobile SDK for Android, Amplify for iOS, Android, and Flutter automatically refresh your ID and access tokens if a valid (unexpired) refresh token is present. The ID and access tokens have a minimum remaining validity of 2 minutes. If the refresh token is expired, your app user must re-authenticate by signing in again to your user pool. If the minimum for the access token and ID token is set to 5 minutes, and you are using the SDK, the refresh token will be continually used to retrieve new access and ID tokens. You will see expected behavior with a minimum of 7 minutes instead of 5 minutes.
Your user's account itself doesn't expire, as long as the user has logged in at least once
before the UnusedAccountValidityDays time limit for new accounts.
Getting new access and identity tokens with a refresh token
Use the API or hosted UI to initiate authentication for refresh tokens.
To use the refresh token to get new ID and access tokens with the user pools API, use
the AdminInitiateAuth or
InitiateAuth API operations.
Pass REFRESH_TOKEN_AUTH for the AuthFlow parameter. In the
AuthParameters property of AuthFlow, pass your user's refresh
token as the value of "REFRESH_TOKEN". Amazon Cognito returns new ID and access tokens
after your API request passes all challenges.
Note
To use the Amazon Cognito user pools API to refresh tokens for a hosted UI user, generate an
InitiateAuth request with the REFRESH_TOKEN_AUTH flow. This
method of token handling in your application doesn't affect users' hosted UI sessions. The
API response issues new ID and access tokens, but doesn't renew the hosted UI session
cookie.
You can also submit refresh tokens to the Token endpoint in a user pool where you have configured a domain. In the
request body, include a grant_type value of refresh_token and a
refresh_token value of your user's refresh token.
Revoking refresh tokens
You can revoke refresh tokens that belong to a user. For more information about revoking tokens, see Ending user sessions with token revocation.
Note
Revoking the refresh token will revoke all ID and access tokens that Amazon Cognito issued from refresh requests with that token.
Users can sign out from all devices where they are currently signed in when you revoke
all of the user's tokens using the GlobalSignOut and
AdminUserGlobalSignOut API operations. After the user is signed out, the
following effects happen.
-
The user's refresh token can't get new tokens for the user.
-
The user's access token can't make token-authorized API requests.
-
The user must re-authenticate to get new tokens. Because hosted UI session cookies don't expire automatically, your user can re-authenticate with a session cookie, with no additional prompt for credentials. After you sign out your hosted UI users, redirect them to the Logout endpoint, where Amazon Cognito will clear their session cookie.
With refresh tokens, you can persist users' sessions in your app for a long time. Over
time, your users might want to deauthorize some devices where they have signed in,
continually refreshing their session. To sign your user out from a single device, revoke
their refresh token. When your user wants to sign themself out from all authenticated
sessions, generate a GlobalSignOut API request . Your app can present your user with a choice like
Sign out from all devices. GlobalSignOut accepts a
user's valid–unaltered, unexpired, not-revoked–access token. Because this API
is token-authorized, one user can't use it to initiate sign-out for another user.
You can, however, generate an AdminUserGlobalSignOut API request that you authorize with your AWS credentials
to sign out any user from all of their devices. The administrator application must call this
API operation with AWS developer credentials and pass the user pool ID and the user's
username as parameters. The AdminUserGlobalSignOut API can sign out any user in
the user pool.
For more information about requests that you can authorize with either AWS credentials or a user's access token, see Amazon Cognito user pools authenticated and unauthenticated API operations.
