Using Scratch Auth in your website

There are many possible ways of integrating Scratch Auth into your website, and the solution you choose will depend on your service's architecture. But don't be discouraged, the process is quite simple! If you ever get stuck along the way, feel free to reach out to @Looky1173 on Scratch.

Let's get started!

First and foremost...

...it is very important that you understand the nature of Scratch Auth and how it works. When you send a user to Scratch Auth, they will be required to verify their identity, that is to say who they are on Scratch. Once they do that (either through cloud data or by commenting), Scratch Auth will redirect them back to your service and tell you whether they have successfully verified their identity or not. Now, you can do anything you want with this information, and now it is up to you to handle your users' sessions.

Scratch Auth tells you whether your users have successfully completed the authentication process (and if yes, their Scratch identity), but nothing more!

In conclusion, how you handle your users' sessions is your choice, and it will depend on a lot of factors, such as what programming languages you use, how you structure your frontend and backend, and more. The next section will introduce you to a general overview of how authentication on the web works; then we will look at implementing Scratch Auth in more specific programming languages and scenarios (backends and databases).

The principles of authentication on the web

The two most common authentication systems are

• session based authentication: Session based authentication is one in which the user state is stored on the server's memory. When using a session based auth system, the server creates and stores the session data in the server memory (commonly in a database) when the user logs in and then stores the session ID in a cookie on the user browser. The session ID is then sent on subsequent requests to the server and the server compares it with the stored session data and proceeds to process the requested action.

• token based authentication: Token based authentication is one in which the user state is stored on the client. In token based authentication, the user data is encrypted into a JWT (JSON Web Token) with a secret and then sent back to the client. The JWT is then stored on the client side (with localStorage or in a cookie) and sent as a header for every subsequent request. The server receives and validates the JWT before proceeding to send a response to the client.

Session based authentication requires a database or any other method for the server to store session data.

Let's take now a look at using Scratch Auth with session or token based authentication!

Using Scratch Auth in your website

It is recommended that you opt for the token based authentication, as it doesn't require a database and is quickly becoming a standard for RESTful APIs.

You can horizontally scroll code boxes on this documentation with Shift + Mouse wheel (or by tapping and dragging on mobile).

With session based authentication

JavaScript pseudo-code:

1/*
2 *JavaScript pseudo-code for using Scratch Auth with session based authentication
3 */
4
5// STEP 1: Redirect the user to Scratch Auth (could happen on the frontend as well as the backend)
6// The redirect location is the Base64 encoded URL that Scratch Auth will redirect the user to once they finish authenticating
7// This should be the endpoint of your website that will handle Scratch Auth's response
8let redirectLocation = new Buffer('https://api.example.com/handle').toString('base64');
9res.redirect(`https://auth.itinerary.eu.org/auth/?redirect=${redirectLocation}&name=Scratch Auth Tutorial`);
10
11// STEP 2: The user was redirected to `https://api.example.com/handle`, your API endpoint (happens on the backend)
12import crypto from 'crypto';
13
14// Scratch Auth will add some query parameters to your API endpoint, for example, `privateCode`
15const { privateCode } = req.query;
16
17// You have to verify whether the user has successfully completed the authentication process
18fetch(`https://auth.itinerary.eu.org/api/auth/verifyToken?privateCode=${privateCode}`, { method: 'GET' })
19    .then((response) => response.json())
20    .then((data) => {
21        // The `data` object sent by Scratch Auth will contain notably a `valid` property and a `username` property
22        // If `valid` is `true`, the user has successfully completed authentication process
23        // We also check the redirect location to prevent a malicious site from tricking users into authenticating
24        // to a seemingly innocent portal while in reality logging in to our site.
25        if (data.valid === true && data.redirect === 'https://api.example.com/handle') {
26            // Generate a session document for the user and store it in the database
27            let sessionId = crypto.randomUUID();
28            Database.collection('sessions').insertOne({ sessionId: sessionId, username: data.username });
29            // Respond to the client with the designated session ID
30            // The client should store this in a session cookie
31            res.status(200).json({ sessionId: sessionId });
32        } else {
33            // Respond to the client with an error
34            res.status(403).json({ error: 'Authentication failed' });
35        }
36    });

Finally, whenever the client makes a request to the backend that requires authentication, send the session ID and make the server verify that that session actually exists!

Always verify the redirect location to prevent a malicious website from compromising your users' accounts. Thank you to @god286 for pointing this out!

With token based authentication

This approach essentially follows the same two steps (outlined above) as session based authentication, except instead of inserting a record into a database with a session ID, the server generates a "token" encrypted with a secret key and sends that to the client. Then, when the client needs to make a request to a protected API endpoint (one that requires authentication), it sends its locally stored token to the server for verification.

An excellent library to implement token based authentication is iron-session. Scratch Incubator uses it too!

Celebrate

Congratulations, you have successfully implemented Scratch Auth in your website! Don't forget to leave a comment on @Looky1173's Scratch profile with your website's address to get it added to the About section of the docs.

Examples

The following are functional implementations of an authentication system that uses Scratch Auth:

• NFlex23's JWT Auth Demo: website | source code

• Chiroyce's Auth Site: website | source code

• NotFenixio's ScratchAuth Demo: website | source code