Providers: Chess.com

[devashish2024]

Goals

1. Add a Chess.com provider to allow developers to authenticate users' chess.com accounts
2. Verify the ownership of a chess.com username to the correct user by saying them to authorize

Non-Goals

No response

Background

There should be an auth provider for Chess.com. Remember, to get Chess.com OAuth access, you have to apply for them.

As well as, they may or may not provide Client Secret. I wonder why, but when I requested, they gave a client ID and specificed the allowed redirect URIs and said there is no need of client secret but therefore keep it safe.

Proposal

Visit here for the official tutorial to setup Chess.com OAuth. I might re-documentate it in my own words here with some snippets to make things easier.

Chess.com OAuth Process

1. Generate a code verifier and challenge

For added security, [Chess.com](http://Chess.com) supports the [Proof Key for Code Exchange](https://tools.ietf.org/html/rfc7636) (PKCE) protocol. While the use of PKCE is required only for public clients that cannot keep a secret, for example single-page or mobile apps, it is highly recommended for confidential clients as well for helping protect against authorization code injection attacks.

To implement the protocol, for every authorization request create what is known as a "code verifier", which is a high-entropy cryptographic random string of length between 43 and 128 characters. It can only contain [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" characters.

The second part is to create a "code challenge", by Base64URL encoding the resulting SHA256 hash of the code verifier: Base64UrlEncode(SHA256Hash(code_verifier)). Code challenge is sent to the authorization server in the next step.

1. codeVerifier is a high-entropy cryptographic random string consisting of 43 to 128 characters, allowing only [A-Z], [a-z], [0-9], "-", ".", "_", and "~" characters.
2. codeChallenge is the Base64Url-encoded SHA-256 hash of the codeVerifier.

Code verifier can be generated in way like:

import * as crypto from 'crypto';

function generateCodeVerifier(length: number = 64): string {
    const allowedChars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~';
    let codeVerifier = '';

    for (let i = 0; i < length; i++) {
        const randomIndex = Math.floor(Math.random() * allowedChars.length);
        codeVerifier += allowedChars[randomIndex];
    }

    return codeVerifier;
}

Similarly, code challenge can be generated from code verifier:

function generateCodeChallenge(codeVerifier: string): string {
    const sha256Hash = crypto.createHash('sha256').update(codeVerifier).digest();
    const codeChallenge = Buffer.from(sha256Hash).toString('base64')
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=/g, '');

    return codeChallenge;
}

2. Send an authentication request to Chess.com

Parameter	Description
response_type	Must be code for the default authorization flow.
client_id	Required The client ID for your application. Provided to clients upon creation.
redirect_uri	Required Determines where Chess.com redirects users after they authorize access to your app.
scope	Optional A space-seperated list that the user consent is needed for. Include openid scope in order to obtain ID token.
state	Recommended Randomly generated unique value used for preventing cross-site request forgry attacks. Provided value will be returned in the token response.
code_challenge	Recommended (required for public clients) Encoded code_verifier that will be used as a challenge during authorization code exchange.
code_challenge_method	Recommended (required for public clients) The method used to encode the code_verifier for the code_challenge parameter. Must be S256.

Send a authentication request to https://oauth.chess.com/authorize with these URL parameters.

For this, we could assume these default URL parameters: ?response_type=code&scope=openid+profile&code_challenge_method=S256 and then the client_id, redirect uri, code_challenge & state.

3. User approves authentication request

No developer action required here.

4. User is redirected to redirect_uri

The user will be redirected to the redirect_uri with a code parameter in URL and an state if it was provided in the first step.

https://myapp.com/auth?code=def502006a48c2895c2630e537987b273bac96ecb1a080a4…&state=.....

5. Exchange authorization code

Your application can now exchange the code for ID Token (OpenID), an Access Token (OAuth), and a Refresh Token (OAuth) by sending a POST request to the token endpoint at: https://oauth.chess.com/token with the following parameters:

Parameter
grant_type	Required Must be authorization_code
client_id	Required The client ID for your application. Provided to clients upon creation.
client_secret	Required (for confidental clients) Created by the client and provided to us for client creation.
redirect_uri	Required The same full URL sent when requesting an authorization code
code	Required The authorization code obtained from the initial request
code_verifier	Recommended The same code_verifier that was encoded to make code_challenge