Manage sessions

Manage sessions to allow your users to securely access your application, without needing to reauthenticate for every request. This provides a better identity experience with no cost to security (see Session management).

There are many ways to implement sessions, which may depend on factors like if the app is highly secure. This describes only one example, which includes the basic tasks you'll need to do as part of any session management flow you create. See Session cookie for security recommendations for creating a session cookie.

Step 1: Create session

When a user requests to login, create a new session by authenticating the user using our Authentication API. Regardless of authentication method, an access token and refresh token are returned. For example:

{
  "message": "email link verified successfully",
  "access_token": "user-access-token",
  "id_token": "user-id-token",
  "refresh_token": "user-refresh-token",
}

Step 2: Validate tokens

The access token is a JWT (Json Web Token) signed by Transmit (see Token reference for the claim structure). We strongly recommend validating it using these guidelines before you can use it to grant the user access.

Here's an example of a decoded token:

{
  "tid": "",
  "app_name": "Acme",
  "app_id": "8flFllgrd1Wqiru4IGai0",
  "roles": [
    "smP3MD65l7hKXG6qJ-S5d"
  ],
  "jti": "IJMTqbmijVG7_LsJz-y5U",
  "sub": "bb8dc75.8AEM5PpWyJBH6opzIOrJ2.transmit",
  "iat": 1658056533,
  "exp": 1658060133,
  "scope": "offline_access",
  "client_id": "bb8dc75.8AEM5PpWyJBH6opzIOrJ2.transmit",
  "iss": "https://userid.security",
  "aud": "userid-api"
}

Step 3: Store session

Once the access token is validated, you'll need to store it together with the refresh token so that it can be used to grant access in subsequent requests.

Step 4: Extend access

When a user returns to your website, you'll want to try to provide them access without requiring them to login. Start by checking for a session cookie, which indicates a local session already exists. If not found, redirect the user to login. If found, send the cookie to your backend and use to retrieve the tokens you stored in Step 3.

• If the access token is still valid, you can allow the user to continue to your website without having to login again.
• If the access token is expired but the refresh token is not, refresh your access token, as described below.
• If both tokens are expired, delete your session cookie and redirect the user to the login page to authenticate.

To refresh an expired access token, send a request like this one and store the new tokens:

curl --location --request POST 'https://api.transmitsecurity.io/oidc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=[CLIENT_ID]' \
--data-urlencode 'client_secret=[CLIENT_SECRET]' \
--data-urlencode 'refresh_token=user_refresh_token'

where [CLIENT_ID] and [CLIENT_SECRET] should be substituted with your app's client credentials.

Step 5: Logout session

When the user requests to logout from your app, the session cookie should be deleted and the user should be taken back to the login page (or a page that doesn't require authentication). Since the stored session is bound to the cookie, it should no longer be accessible. However, as a precaution, it's recommended to also logout of the IdP session. This will terminate all user's sessions for this application and revoke the corresponding refresh tokens.

To logout the user from the session, use the logout API:

curl -i -X POST \
  'https://api.transmitsecurity.io/cis/v1/auth/logout' \
  -H 'Authorization: Bearer [TOKEN]'

where [TOKEN] is the access token you received upon successful authentication.