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.
npm install scratch-auth-react
yarn add scratch-auth-react
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
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: `https://localhost:3000/api/auth`, // Required
title: `Title`, // optional
expiration: 30, // optional
newWindow: true, // optional
}
export default config
No explanation of basic knowledge such as React, etc., will be provided.
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>
</>
);
}
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>
);
}