When developing a SaaS application that relies on third-party data, it's important to recognize that not all users will want to grant access to their data unless it's essential for the application's functionality.

In a recent article, I covered how you can use Clerk Single Sign On (SSO) connections to access Google Calendar data on behalf of the user. When configuring SSO, scopes are used to inform the service provider (SP) what kind of access is required for the connection that is being established. It’s important to specify only the scopes that are required and no more, a variation of the least privilege access principle, however, some users might require more access than others.

In this article, you’ll learn about the concept of least privilege access, and how to customize OAuth scopes on a per-user basis.

What is least privilege access?

Least privilege access is a security principle where users are given the minimum levels of access or permissions needed.

This approach limits potential damage from system breaches by restricting each user's ability to interact with systems, networks, and data beyond their essential requirements. By granting only the precise access rights necessary for a user's role, organizations can significantly reduce their overall cybersecurity risk and potential attack surface.

Typically least privilege access is used in the context of users accessing a system, however, the same principle can be applied when services are accessing user data in another system.

OAuth scopes allow the user to make an educated decision about what data the system should be able to access. A system that only asks for the minimum access required can not only help ease the user's concern about the data being accessed, but it could also protect the developer in situations where attackers gain access to areas of the system they shouldn’t.

For example, if you build a system that only requires access to Google Calendar data, but you simply ask for access to ALL the user's data, you could be held liable if someone deleted the user's Google Docs!

Implementing user-specific OAuth scopes with Clerk

To demonstrate how applications can be configured to only request access to the necessary permissions, we’ll use BookMate as a demo.

BookMate is a lightweight clone of popular scheduling tools like Cal.com or Calendly. Users can link their Google Calendar so visitors can request a meeting with them using a public profile. When a visitor requests a meeting, Bookmate will send both parties a calendar invite via email.

To accommodate this functionality, BookMate uses the following OAuth scopes from Google:

• https://www.googleapis.com/auth/calendar.readonly
• https://www.googleapis.com/auth/calendar.events.readonly

These scopes are defined in the Clerk dashboard under the Google SSO settings and automatically apply to all users who sign into the app.

Let’s add a feature that also allows the calendar entry to be added directly to the user’s calendar instead of just sending an invite, further streamlining the process. To accommodate this, we’ll also need the following scope to be added to the login process:

• https://www.googleapis.com/auth/calendar.events

This feature will be optional and we wouldn't want to apply this scope to all users since it allows BookMate to directly modify the user's calendar. Therefore we cannot simply add it to the list of scopes in the Clerk dashboard.

To accomplish this new functionality, we’ll take the following steps:

1. Add a toggle to the settings that allows BookMate to add events to the user's calendar. When the toggle is enabled, check the existing scopes on the Google access token for the current user.
2. If the access token does not have that scope, initiate a reauthorization that requires the user to allow access to their calendar, adding the scope to the token.
3. Storing the user-specific scopes with the user’s public metadata in Clerk.
4. Add a global provider that will automatically handle reauthorization if the scope is required.

Adding the toggle to check the user's scopes

The first step is to add a new checkbox that informs the application that the additional scope is required. This checkbox will also render a dropdown for the user to select the calendar they want to add the event to. If the external account does not have the proper scopes, the application will trigger a reauthorization process with Google SSO to gain access to the proper scopes before saving the preferences to the database.

The following snippet is for the CalendarSelector component which contains the logic described above, with notable lines commented:

Clerk has a helper function attached to every ExternalAccount object to trigger the reauthorization if needed. The additionalScopes can contain an array of scopes that will be added to the OAuth URL along with the global scopes set in the Clerk dashboard. This function will craft the required URL that the user needs to be directed to confirm access to the necessary resources:

To prevent the user from having to reauthorize manually every time they sign in, we can store these required scopes with the Clerk User object in the publicMetadata and use that data for the following steps.

The following snippet is in the server action that handles saving the calendar preferences for the user, with enabled being the parameter for the function if directBooking is set:

Add publicMetadata to the session claims

When a user authenticates with Clerk, they receive a JWT used to verify their identity on any subsequent requests to the server. The claims in this JWT can be modified to include the publicMetadata which includes the additional scopes required. This saves an extra trip to the Clerk API to check for this data, making the application more performant.

The session claims can be customized in the Clerk Dashboard under Configure > Sessions > Customize session token.

Automatically handle reauthorization if additional scopes are present

Since the claims are available to both the client and server and include the additional scopes, they can be checked on login to automatically handle reauthorization. Since the user has already approved the scopes, this appears as a simple redirect to Google and then back to the application with no user interaction required.

The following code outlines a ReauthProvider component that can wrap the application to handle all of this logic automatically, storing a flag in the browser’s localStorage to prevent it from occurring too frequently:

From this point forward, the application will now have the proper rights to add events directly to the user's calendar if needed.

Why is reauthorization required on every login?

When a user is using OAuth to sign into an application, a special URL is crafted that contains information about the application and the permissions it requires. If you are using a standard set of scopes for all users, those are configured in the Clerk dashboard and are included with the OAuth URL.

The access token stored with Clerk includes the scopes from the most recent authentication attempt. So when users who require additional scopes sign in via Clerk, their scopes will be reset to what’s defined for the entire application.

The reauthorization keeps the proper set of scopes configured at all times.

Conclusion

You now understand how to implement least privilege access in a SaaS application using Clerk's SSO. You've also learned how unique scopes per user can be stored and automatically reused throughout the application lifecycle. The approach provides granular access control and flexible permission management while minimizing potential security risks.