❗️

Clever Complete Agreement Required

This feature is included with a Clever Complete subscription. Sign up here or email your Application Success Manager to learn more.

Table of Contents

Overview
Preventing Cross-Site Request Forgery
Safeguarding Your Client Secret
Shared Devices: Session Re-authentication and Session Invalidation

Overview

Security in Single Sign-On is a shared commitment between your application and Clever. While Clever ensures the identity of the user is authenticated via modern standards like OIDC and OAuth 2.0, the security of the integration ultimately depends on how your application handles the exchange. Protecting your Client Secret, preventing cross-site request forgery, and invalidating previous SSO sessions are essential steps to prevent attacks by bad actors. By following the best practices outlined below, you ensure that student and teacher data remains protected from the moment they click "Log in with Clever" to the moment their session ends in your app.

Preventing Cross-Site Request Forgery

Cross-Site Request Forgery (CSRF) is a vulnerability that occurs when an attacker can cause a victim to perform an unintended action on a web resource. In the context of SSO, CSRF vulnerabilities can allow an attacker to force a victim to log in to an app using the attacker’s identity.

For example, an attacker could generate an SSO link for their account and then put it in the source attribute of an image of a web page. They would then force a victim to visit this page, who would unknowingly make a request to clever.com with their existing session, which would log them in with the attackers account to the application in question.

<img src="https://clever.com/oauth/authorize?type=code&client_id=123456">

Depending on the configuration of the application, this may result in a low impact threat ("the victim is logged in to the application as the attacker and may accidentally type in sensitive data") or a high impact threat ("the attacker’s identity is silently added to the victim’s account in the application").

For more information on this threat, see this blog post. For information on protecting your integration against CSRF, see Designing Your Integration.

Safeguarding Your Client Secret

Your Client Secret is the master key to your integration. It is a unique, confidential string used by your application to authenticate with Clever’s token server. If this secret is compromised, an attacker could potentially impersonate your application to exchange authorization codes for sensitive user data.

To ensure your integration remains secure, adhere to the following recommendations of secret management:

Never Store Secrets in Client-Side Code

The most common security vulnerability includes the client_secret in code that is sent to a user’s browser or mobile device.

• Web Apps: Do not include secrets in frontend JavaScript files.
• Mobile Apps: Never hardcode secrets in your app's binary. Attackers can easily decompile your app to extract them.
• The Rule: The client secret should only ever exist on your secure backend server.

Use Environment Variables

Avoid "hardcoding" the secret directly into your source files (e.g., const secret = '12345'). Instead, use environment variables to inject the secret into your application at runtime. This prevents the secret from being accidentally committed to version control systems like GitHub or GitLab.

• Pro Tip: Use a .env file for local development, but ensure it is added to your .gitignore file so it is never pushed to a public or private repository.
• Implement Server-Side Token Exchange: Your frontend should only handle the initial redirect to Clever and the receipt of the code. Once your frontend has the code, it should send it to your backend. Your backend then performs the "Server-to-Server" call to Clever’s /oauth/tokens endpoint using the client_secret.
• Rotate Secrets When Necessary: Treat your Client Secret like a high-level password. If a developer leaves your team, or if you suspect a secret might have been exposed (e.g., it was accidentally committed to a repo), rotate your secret immediately in the Clever Dashboard.

Use Secrets Managers for Scale

For enterprise-level security, use dedicated secrets management services like AWS Secrets Manager, HashiCorp Vault, or Google Cloud Secret Manager. These services provide encrypted storage, audit logs of who accessed the secret, and automated rotation capabilities.

What happens if my secret is leaked?

If you realize your secret has been exposed, navigate to your Clever Dashboard > Settings > App Settings and click Rotate Secret. Update your server environment variables with the new string immediately to restore security.

Shared Devices: Session Re-authentication and Session Invalidation

To protect user data and maintain secure access on shared devices, it is crucial to implement session re-authentication and session invalidation mechanisms. These practices help ensure that user sessions are properly terminated when switching users, preventing unauthorized access to sensitive information. This guide outlines best practices for implementing these features.

Session Re-authentication: Ensuring Secure Access Transitions

Session re-authentication requires the user to re-authenticate when necessary, such as after a certain period of inactivity or when switching users on shared devices. Re-authentication ensures that the current user is the rightful owner of the session, preventing unintended access to the data of previously authenticated users.

Key Implementation Steps:

• Prompt Re-authentication on User Switch: Ensure that when a new user attempts to access the application, the existing session is invalidated, and the new user is required to log in. This ensures that only the new user’s session is active on the device.
• Set Short Session Expiration Times: On shared devices, set short session expiration times to minimize the risk of unauthorized access. After a period of inactivity, prompt the user to re-authenticate.
• Multi-Factor Authentication (MFA): For enhanced security, consider implementing MFA during re-authentication. This ensures that even if the device is shared, only authorized users can regain access to the session.

Session Invalidation: Terminating Previous Sessions on Shared Devices

Session invalidation is critical for ensuring that only one session is active per user. If a new session is initiated (e.g., via a new login or user switch), the previous session must be terminated to avoid security risks associated with concurrent sessions on shared devices.

Key Implementation Steps:

• Invalidate Old Sessions: Implement logic to invalidate all active sessions when a new authentication occurs. This ensures that no other active session remains after the user logs in from a new instance, device, or browser.
• Clear Session Data Upon Logout: On logout, ensure that all session-related data (such as cookies or local storage) is cleared, preventing session data from being reused inappropriately.
• Immediate Revocation: Use immediate token revocation to ensure that once a session is invalidated, it cannot be used for any further requests.

Best Practices for Securing Shared Devices:

• Monitor and Limit Concurrent Sessions: Implement policies that limit the number of concurrent sessions a user can have. If a user logs in on a shared device, any other active sessions should be revoked.
• Graceful Logout: Provide a clear and visible logout option for users on shared devices, encouraging users to end their session when finished.
• Audit and Logging: Log user activities and session invalidation events to detect unusual behavior, such as multiple session creation or failed login attempts.

Security Considerations:

• Use Secure Cookies: Store session data in HTTP-only and secure cookies to prevent unauthorized access via cross-site scripting (XSS) attacks.
• Implement HTTPS: Ensure that all sessions and authentication tokens are transmitted over HTTPS to protect against man-in-the-middle attacks.
• Token Expiration and Rotation: Implement short-lived access tokens and automatic token rotation to ensure that session tokens do not persist longer than necessary.