Scratch Auth for React

English / 日本語

Introduction

Scratch Auth is a simple OAuth service for Scratch. It provides developers with an easy-to-understand API and users with a smooth login experience. By using scratch-auth-react, you can easily implement OAuth functionality into your site.

This guide explains the usage using Next.js's Approuter and TypeScript, but it should work similarly in Pagerouter or React, so adjust the code to make it work in your environment.

[!NOTE] Versions labeled as pre, beta, alpha, etc., may be unstable. We recommend using the release versions. If you encounter any issues, please report them here.

Installation

npm install scratch-auth-react

yarn add scratch-auth-react

Setup

Secret Key

Set the secret key used for signing Scratch Auth cookies. This value should be a random, long string.

SCRATCH_AUTH_COOKIE_SECRET_KEY=your_secret_key_here

Configuration

[!NOTE] The setup file should be created in the root directory of your project. This file is used to set the OAuth redirect URL. Create it with the name scratch-auth.config.ts as shown below.

redirect_url Redirect URL When publishing a website, please change the URL from the development environment to the production environment.

title By default, it is Scratch Auth, but you can optionally decide your own title.

expiration Sets the session storage period. By default, it is 30 days. You can freely set the storage period as an option. If -1 is set, the storage period is permanently (200 years).

newWindow Allows you to set whether the login page is displayed in a pop-up when the login button is pressed. Defaults to false.

import { ScratchAuth_config } from "scratch-auth-react/src/dist/config"

// Perform necessary configurations within the setup file
const config: ScratchAuth_config = {
  redirect_url: `http://localhost:3000/api/auth`, // Required
  title: `Title`, // optional
  expiration: 30, // optional
  newWindow: true, // optional
}

export default config

Pages

No explanation of basic knowledge such as React, etc., will be provided.

Home

By executing await ScratchAuthGET_session(), the user's name is returned if logged in, otherwise null is returned.

'use client'

import { useAuthSession, ScratchAuth_Login, ScratchAuth_Logout } from 'scratch-auth-react';

export default function Home() {
  const session = useAuthSession();

  return (
      <>
        <div className='flex flex-col gap-3 text-center'>
          {session?
            <>
              <h1>{session}</h1>
              <button onClick={() => ScratchAuth_Logout()}>
                Logout
              </button>
            </>:<>
              <button onClick={() => ScratchAuth_Login()}>
                Login
              </button> 
            </>
          }
        </div>
      </>
  );
}

Authentication

In the example code, we use Next.js's useSearchParams to get parameters, but it's fine to use another method as long as you can get the value of privateCode.

[!NOTE] This process needs to be executed on the page with the redirect URL set up in the Setup.

/*
 * page.tsx
 * This file is the component of the authentication page.
 * It retrieves the privateCode from the redirect URL and performs the authentication process.
 */

'use client'

import React, { useEffect } from 'react';
import { useSearchParams } from 'next/navigation'
import { ScratchAuthSET_session } from 'scratch-auth-react';

export default function AuthPage() {
  const searchParams = useSearchParams();
  const privateCode = searchParams.get('privateCode');

  useEffect(() => {
    async function auth() {
      await ScratchAuthSET_session(privateCode); //A uthenticate account
      if (typeof window !== 'undefined') {
        window.location.href = `/`; // Redirect to home
      }
    }
    auth()
  }, []); // Pass an empty dependency array to execute only on initial render

  return (
    <span>Processing...</span>
  );
}