🔐 Using ggLeap as an OpenID Connect (OIDC) Provider

ggLeap supports OpenID Connect (OIDC) to allow third-party applications to authenticate users using their ggLeap accounts. This enables integrations such as "Login with ggLeap" for partner applications, websites, or services.
OIDC is built on top of OAuth 2.0 and allows applications to securely verify user identity and obtain basic profile information.

🧠 Overview

By integrating with ggLeap's OIDC provider, applications can:

• Allow users to sign in using their ggLeap account
• Enable Single Sign-On (SSO) across supported apps
• Retrieve user information such as email, profile, and group membership
• Support center-specific authentication when needed
  Applications authenticate users through ggLeap and receive a token response that confirms identity and requested permissions.

🌐 OIDC Issuer Endpoints

Applications must use the appropriate issuer URL depending on the environment.

Note: The discovery endpoint does not support dynamic client registration. Client credentials cannot be self-issued and must be requested from ggCircuit (see below).

🔑 Required Integration Information

To integrate with ggLeap OIDC, the application developer will receive the following credentials:

📝 Requesting OIDC Credentials

Client IDs and Client Secrets are issued by ggCircuit. To get them, send one request to ggCircuit Support that includes all of the following:

Application name: My Rewards Site
Center name: My Gaming Lounge
Scopes: email (required), profile (optional)
Redirect URI: https://example.com/auth/callback
Post-logout redirect URI: https://example.com/
Email for credentials link: admin@example.com
Once the request is processed, ggCircuit sends a one-time link to the contact email. The link can only be opened once, so copy the Client Secret into a secure location (such as a password manager or secrets vault) right away. If the link is lost or expired, contact support to have new credentials issued.
Test client (optional)
During development, you should not use your production redirect URL for testing. You can request a second, separate client for your own test or development environment, with its own test redirect URLs (for example, http://localhost:3000/auth/callback). A test client has its own Client ID and Client Secret. Mention in your request that you want a test client and include the test redirect URL(s).

🏢 Center-Bound and Network-Wide Clients

There are two types of OIDC clients, and which one you get depends on how your app will be used.
Center-bound client (most common)
The client is tied to one center, and the center is stored in the client settings. Your app does not need to send center_uuid in authorization requests, and you do not need to know your center's GUID. Just give us your center name in the credentials request.
Network-wide client
One client is shared across several centers, so users from any of those centers can sign in to the same app. Because the client is not tied to a single center, your app must include center_uuid={guid} in each authorization request, with the GUID of the center the user belongs to. Your app is responsible for determining which center that is, for example by asking the user to pick their center before redirecting to ggLeap. We can look up each center's GUID from its center name, so list every center name in your credentials request.

🔐 Authorization Request

Applications initiate login by sending users to the ggLeap authorization endpoint.
Endpoint
{issuer}/connect/authorize
Example Authorization Request

{issuer}/connect/authorize
?client_id={client_id}
&redirect_uri={encoded_redirect_uri}
&response_type=code
&scope=openid%20email%20profile
&state=abc
&nonce=xyz
[&center_uuid={guid}]

center_uuid is only needed for network-wide clients.
Parameters

🧾 Available Scopes

Applications can request the following scopes during authentication.

🔁 Token Exchange

After the user successfully signs in, ggLeap redirects the user back to the application with an authorization code.
The application then exchanges this code for tokens using the token endpoint.
Endpoint
{issuer}/connect/token
Standard OAuth Authorization Code Flow should be used for this step. Send the exchange request from your server (never from browser code), since it uses the Client Secret.

🚪 Logout (End Session)

Applications can sign users out of ggLeap sessions using the logout endpoint.
Endpoint
{issuer}/connect/logout
Parameters

⚠️ Common Integration Issues

🧪 Basic Integration Test

To verify the integration is working:

1. Construct an authorization request using your Client ID and Redirect URI.
2. Open the URL in a browser.
3. Sign in with a ggLeap account.
4. Confirm the application receives an authorization code in the redirect URL.
5. Exchange the code using the token endpoint.
   If successful, the application will receive access and identity tokens confirming the user's login.