OpenID Connect

Quran.Foundation's OAuth 2.0 APIs can be used for both authentication and authorization.

In this guide, we have briefly explained what OAuth2 is and how to integrate with Quran.Foundation's OAuth2 server.

Besides OAuth2, Quran.Foundation also supports OpenID Connect standards by providing the UserInfo Endpoint to get more information about the user.

OIDC Discovery & JWKS

Quran.Foundation provides standard OIDC Discovery endpoints for automatic configuration:

Environment	Discovery URL
Production	https://oauth2.quran.foundation/.well-known/openid-configuration
Pre-Production	https://prelive-oauth2.quran.foundation/.well-known/openid-configuration

The discovery document includes:

• issuer — The issuer identifier (use for iss claim validation)
• authorization_endpoint, token_endpoint, userinfo_endpoint
• jwks_uri — URL to fetch public keys for JWT verification
• Supported scopes, grant types, and signing algorithms

Verifying ID Tokens

To verify id_token signatures:

1. Fetch the JWKS from the jwks_uri in the discovery document
2. Use the kid (key ID) from the token header to select the correct key
3. Verify the signature using the public key
4. Validate standard claims: iss, aud, exp, iat

// Example using jose library
import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(
  new URL("https://oauth2.quran.foundation/.well-known/jwks.json")
);

const { payload } = await jwtVerify(idToken, JWKS, {
  issuer: "https://oauth2.quran.foundation/",
  audience: "YOUR_CLIENT_ID",
});

console.log("Verified user:", payload.sub);

To be able to access OpenID Connect's endpoints, make sure to include openid in the list of requested scopes. Once this is done, besides access_token, the authorization callback will also contain a JWT id_token parameter.

The ID Token (id_token) contains information about the user and can be decoded using one of the JWT libraries to know more about the identity of the user. Below is an example of a decoded id_token:

{
  "at_hash": "tGJSmRygf5HXuZx1YDP1",
  "aud": ["quran-demo"],
  "auth_time": 1675234788,
  "email": "[email protected]",
  "exp": 1677591803,
  "first_name": "Muhammad",
  "iat": 1677588203,
  "iss": "https://oauth2.quran.foundation/",
  "jti": "a144b79e-3e50-40b8-8053c462000",
  "last_name": "Muhajir",
  "rat": 1677588190,
  "sid": "ce2fe21b-87hd-40fb-b4c54dc898df7",
  "sub": "a4f5a01d-a641-4b23-ba002f704cfaa"
}

Stable User Identifier (sub)

The sub (subject) claim is the stable, unique user identifier you should store in your database. This UUID:

• Never changes for a given user
• Is unique across all Quran.Foundation apps
• Should be used as your primary key for user data
• Is the same across all sessions and devices for that user

Use sub as Your User ID

Don't store email addresses as user identifiers—users can change their email. The sub claim is guaranteed to be stable and unique.