Integrating Next.js + next-auth with GakuNin RDM via OAuth2

Introduction

This article explains how to integrate the research data management platform “GakuNin RDM” with a Next.js application using OAuth2. Since GakuNin RDM provides an API compatible with OSF (Open Science Framework), implementation can be based on the OSF OAuth2 flow.

This article provides a detailed explanation of the implementation using next-auth and the pitfall of automatic access token refresh.

What is GakuNin RDM?

GakuNin RDM (Research Data Management) is a research data management service provided by the National Institute of Informatics (NII).

• URL: https://rdm.nii.ac.jp/
• API: OSF-compatible REST API (https://api.rdm.nii.ac.jp/v2/)
• Authentication: OAuth2 (https://accounts.rdm.nii.ac.jp/)

It is a platform where researchers can safely store, share, and publish research data, and through integration with GakuNin authentication, users from Japanese universities and research institutions can use it.

Preparation

1. Registering an OAuth Application

Register an OAuth application from the GakuNin RDM settings screen.

1. Access https://rdm.nii.ac.jp/settings/applications/
2. Click “Register a developer application”
3. Configure the following:
   • Application name: App name
   • Application homepage URL: http://localhost:3000 (for development)
   • Application description: Description
   • Authorization callback URL: http://localhost:3000/api/auth/callback/gakunin

After registration, a Client ID and Client Secret are issued.

2. Setting Environment Variables

Custom Provider Configuration with next-auth

Since GakuNin RDM is not included in next-auth’s built-in providers, it needs to be configured as a custom provider.

Basic Configuration

Key Points

1. Customizing token.request: Since GakuNin RDM expects token requests in application/x-www-form-urlencoded format, a custom request function is implemented
2. Parsing userinfo: Since the OSF API returns responses in { data: { id, attributes: { ... } } } structure, mapping is done in the profile function

Pitfall: Automatic Token Refresh

Problem

OAuth2 access tokens have an expiration time (approximately 1 hour for GakuNin RDM).

In the default implementation of next-auth, token refresh is not performed. Therefore, after being logged in for a while, the following error occurs:

This creates a confusing situation where the user is logged in but the API returns a 401 error.

Solution

Manage the token expiration in the JWT callback and automatically refresh before expiration.

Flow Diagram

Client-Side Error Handling

If the refresh token has also expired, session.error is set to "RefreshAccessTokenError". This can be detected to prompt re-sign-in.

API Usage Example

Summary

Key points when integrating GakuNin RDM with next-auth:

1. Configuration as a custom provider is required
2. Token requests must be in application/x-www-form-urlencoded format
3. Without implementing automatic access token refresh, 401 errors will occur even when logged in
4. Implement client-side error handling for cases when the refresh token also expires

The third point, token refresh, is easy to overlook, so be sure to consider it when implementing OAuth2 integration.

References

• GakuNin RDM
• OSF API Documentation
• next-auth Refresh Token Rotation