Maintain User Session

Maintain user session locally and in AuthN

After the authentication results have been received and processed, the approach you take to require authentication for restricted-access areas in your app will depend on factors such as security requirements, scalability concerns, and the specific use case of your application.

Local session

After receiving confirmation of user authentication at Pangea, you can maintain the user session in your application, either client-side or server-side.

You can base your solution on session cookies, which are automatically supported by user agents, including browsers. Your application will check whether a session cookie is attached to the request before allowing the user to access a protected resource.

Alternatively, you can include cryptographically signed tokens in the Authorization header in requests to a protected resource. A signed JWT received from Pangea and verified by your application (as described in the Verify JWT signature chapter) can serve as tamper-proof confirmation of user authentication by Pangea and can be used for user identification in subsequent requests.

For example:

/protected

const getProtected = async (id) => {
  const response = await fetch(`/protected`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${JSON.parse(localStorage.getItem('pangea-session')).user.active_token.token}`
    },
    body: JSON.stringify({ id })
  });

  if (response.status === 401) {
    signIn();
    return;
  }

  if (!response.ok) {
    throw new Error(`Error: ${response.statusText}`);
  }

  result = await response.json();

  return result;
}

The protected route in your application will check for the presence of a valid token in the Authorization header. If no valid token is found, the route will either redirect the user to the login page or respond with an HTTP/1.1 401 Unauthorized error and the WWW-Authenticate header.

For example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example", error="invalid_token", error_description="The token expired"

note

Cookie-based session management and authorizing requests with a bearer token are common techniques used for maintaining user sessions and securing API requests. Implementing these and other session management and access control techniques securely requires adhering to best practices and standards that are beyond the scope of this document.

Pangea session

While maintaining the local user session, you can verify, renew, and terminate the corresponding user session in your Pangea project. To keep both sessions synchronized, use the /v2/client/token/check, /v2/client/session/refresh, and /v2/session/logout endpoints in the AuthN APIs.

Validate active token

Check for the active user session at Pangea by validating the active_token.token value received in user profile and session information from the /v2/client/userinfo endpoint. You need to send your request to the AuthN domain and authorize it with an AuthN service token specific to your Pangea project.

Diagram

App creates local User session and allows User to access protected areas

Annotations

The application establishes and maintains a local user session, using session cookies or tokens to authorize the user's requests.
The authenticated user attempts to access a protected area within the application.
The application checks if the user's request is authorized.
The application checks if the user session on the Pangea server is active by submitting the active token value to the AuthN /v2/client/token/check endpoint.
```
export PANGEA_DOMAIN="aws.us.pangea.cloud"
export PANGEA_AUTHN_TOKEN="pts_2lusaf...dj47sy"
```
/v2/client/token/check active token
JavaScript
```
// Set PANGEA_DOMAIN and PANGEA_AUTHN_TOKEN
// ...

const check = async (token) => {
  const response = await fetch(`https://authn.${PANGEA_DOMAIN}/v2/client/token/check`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${PANGEA_AUTHN_TOKEN}`
    },
    body: JSON.stringify({
      'token': 'eyJhbG...ldUIn0.eyJpc3...c2V9fQ.bBh-fQ...nDJuOA'
    })
  });
  const responseBody = await response.json();

  // ...
}
```
note
You could also check for the existence of a valid user session using the active_token.id value as the active_token_id parameter at the /v2/session/list endpoint.
If the user session is found and the active token is valid, the Pangea server responds with the success status and user information.

You can check the status and/or result.expire fields within the response to verify the token validity and expiration.

Valid token:
/v2/client/token/check response success
json
```
{
  "status": "Success",
  "summary": "Token validated",
  "result": {
    "email": "example.user@example.com",
    "enabled": true,
    "expire": "2024-05-24T04:18:17.645214Z",
    "id": "pmt_2ues3vt43l4mbiymr764du26tv2xqnuw",
    "identity": "pui_yldeniqvvxk4yhirapuhw6bs7nt6l5gn",
    "intelligence": {
      "domain_intel": {
        "is_bad": false,
        "reputation": {
          ...
        }
      },
      "embargo": false,
      "ip_intel": {
        "geolocation": {
          ...
        },
        "is_bad": false,
        "is_proxy": true,
        "is_vpn": false,
        "reputation": {
          ...
        }
      },
      "user_intel": false
    },
    "life": 26693,
    "owner": "example.user@example.com",
    "profile": {
      "email": "example.user@example.com",
      "first_name": "Example",
      "last_name": "User",
      "phone": "907...",
      ...
    },
    "type": "user",
    ...
  },
  ...
}
```
If the user session does not exist on the Pangea server or the active session token is invalid, the application terminates the local user session.

Expired token:
/v2/client/token/check response expired
json
```
{
  "status": "ExpiredToken",
  "summary": "The token is no longer valid",
  "result": null,
  ...
}
```
Non-existent/terminated session:
/v2/client/token/check response not-found
json
```
{
  "status": "InvalidToken",
  "summary": "The token does not exist",
  "result": null
}
```
The user is allowed to access protected areas within the application as long as their requests are authorized and their session is active.

Refresh user session

Use the refresh_token.token value received in user profile and session information to renew the user session using the /v2/client/session/refresh endpoint:

Diagram

App refreshes User session at Pangea

Annotations

Optionally, if the active token is expired, the application attempts to refresh it using the refresh token at the /v2/client/session/refresh endpoint.
```
export PANGEA_DOMAIN="aws.us.pangea.cloud"
export PANGEA_AUTHN_TOKEN="pts_2lusaf...dj47sy"
```
/v2/client/session/refresh user session
JavaScript
```
// Set PANGEA_DOMAIN and PANGEA_AUTHN_TOKEN
// ...

const refresh = async (refresh_token) => {
  const response = await fetch(`https://authn.${PANGEA_DOMAIN}/v2/client/session/refresh`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${PANGEA_AUTHN_TOKEN}`
    },
    body: JSON.stringify({
      'refresh_token': refresh_token
    })
  })
  userinfo = await response.json();

  if (userinfo?.status === 'Success') {
    setSession(userinfo);
  } else {
    return false;
  }
}
```
If the user session exists at Pangea and the refresh token is valid, the Pangea server responds with user profile and session information - in the same way as the /v2/client/userinfo endpoint responds.
The application establishes and maintains a local user session, using session cookies or tokens to authorize the user's requests.
If the user session does not exist on the Pangea server or the refresh token is invalid, the application terminates the local user session.

Terminate user session

You can terminate the user session using the /v2/client/session/logout endpoint by providing the active_token.token value received in user profile and session information as the "token" parameter:

User signs out

Diagram

Annotations

The user clicks the application logout button.
The application terminates the local user session.
The application attempts to terminate the user session at Pangea using the active token value at the /v2/client/session/logout endpoint.
```
export PANGEA_DOMAIN="aws.us.pangea.cloud"
export PANGEA_AUTHN_TOKEN="pts_2lusaf...dj47sy"
```
/v2/client/session/logout user session
JavaScript
```
// Set PANGEA_DOMAIN and PANGEA_AUTHN_TOKEN
// ...

const logout = async (active_token) => {
  const response = await fetch(`https://authn.${PANGEA_DOMAIN}/v2/client/session/logout`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${PANGEA_AUTHN_TOKEN}`
    },
    body: JSON.stringify({
      'token': active_token
    })
  })
  const responseBody = await response.json()

  // ...
}
```
Response for a successful logout:
/v2/client/token/check response not-found
json
```
{
  "status": "Success",
  "summary": "Logged out the current user login session",
  "result": {},
  ...
}
```
note
You can use the /v2/session/logout endpoint to terminate all user's sessions at Pangea by providing the result.active_token.identity value received in user profile and session information as the "user_id" parameter. You cannot use the AuthN client token for this request.

Was this article helpful?

Maintain User Session

Maintain user session locally and in AuthN

Local session​

Pangea session​

Validate active token​

Diagram​

App creates local User session and allows User to access protected areas

Annotations​

Refresh user session​

Diagram​

App refreshes User session at Pangea

Annotations​

Terminate user session​

User signs out

Diagram​

Annotations​

Local session

Pangea session

Validate active token

Diagram

Annotations

Refresh user session

Diagram

Annotations

Terminate user session

Diagram

Annotations