> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://helpdesk.ggcircuit.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 🔐 Using ggLeap as an OpenID Connect (OIDC) Provider

## 🔐 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.
| Environment | Issuer URL |
| ---- |
| Production | `https://api.ggleap.com/production/oidc` |
| Beta | `https://api.ggleap.com/beta/oidc` |
OIDC discovery metadata and public signing keys are automatically available under the issuer endpoint. Most OIDC libraries will retrieve this configuration automatically.
## 🔑 Required Integration Information
To integrate with ggLeap OIDC, the application developer will receive the following credentials:
| Parameter | Description |
| ---- |
| **Client ID** | Unique identifier for the application |
| **Client Secret** | Confidential key used during token exchange |
| **Redirect URI(s)** | HTTPS callback URL(s) where ggLeap sends authentication responses |
These values must be configured in the application’s OIDC client settings.
## 🔐 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}]
```
### Parameters
| Parameter | Description |
| ---- |
| `client_id` | Client ID issued for the application |
| `redirect_uri` | Must match a registered redirect URL exactly |
| `response_type` | Use `code` for authorization code flow |
| `scope` | Requested permissions |
| `state` | Optional application state value |
| `nonce` | Recommended security value |
| `center_uuid` | Required if the application supports multiple centers |
## 🧾 Available Scopes
Applications can request the following scopes during authentication.
| Scope | Description |
| ---- |
| `openid` | Required for OIDC authentication |
| `email` | Provides the user’s email address |
| `profile` | Provides basic profile information |
| `group` | Returns the user's ggLeap group information |
## 🏢 Center-Specific Authentication
Some integrations are tied to a **specific ggLeap center**, while others support **multiple centers**.
### Center Integrations
Applications supporting a single center must include:
```
center_uuid={guid}
```
in the **authorization request**.
## 🔁 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.
## 🚪 Logout (End Session)
Applications can sign users out of ggLeap sessions using the logout endpoint.
**Endpoint**
```
{issuer}/connect/logout
```
### Parameters
| Parameter | Description |
| ---- |
| `id_token_hint` | Token from the user's recent login session |
| `post_logout_redirect_uri` | Optional redirect URL after logout |
If a valid redirect URI is provided and allowed, the user will be redirected after logout.
## ⚠️ Common Integration Issues
| Issue | Resolution |
| ---- |
| Redirect URI mismatch | Ensure the redirect URI matches the registered URL exactly |
| Missing `center_uuid` | Include the parameter for multi-center applications |
| Authentication fails | Confirm correct issuer environment (production vs beta) |
| Login not completing | Ensure the application is using the authorization code flow |
## 🧪 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.