> ## Documentation Index
> Fetch the complete documentation index at: https://docsgetmyordo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom OAuth/OIDC

> Configure Ordo with your custom OpenID Connect (OIDC) provider.

## Overview

Ordo supports custom OAuth 2.0 and OpenID Connect (OIDC) providers, allowing you to integrate with any standards-compliant identity provider such as Keycloak, Auth0, Okta, Azure AD, or self-hosted solutions like Pocket ID.

## Configuration

To configure a custom OAuth/OIDC provider, you need to set the following environment variables in your `.env` file:

### Required Variables

| Variable | Description | Example |
| - | - | - |
| `CUSTOM_OAUTH_CLIENT_ID` | OAuth client ID from your provider | `2b1ae9df-8d25-4dbc-8cc8-f8f2c1ef6bd0` |
| `CUSTOM_OAUTH_CLIENT_SECRET` | OAuth client secret from your provider | `NzDjplDsdQyP062wTmkZ8kyiaziBag0N` |
| `CUSTOM_OAUTH_AUTHORIZATION_URL` | Authorization endpoint URL | `https://id.example.com/authorize` |
| `CUSTOM_OAUTH_TOKEN_URL` | Token exchange endpoint URL | `https://id.example.com/api/oidc/token` |
| `CUSTOM_OAUTH_USER_INFO_URL` | User info endpoint URL | `https://id.example.com/api/oidc/userinfo` |

### Optional Variables

| Variable | Description | Default |
| - | - | - |
| `CUSTOM_OAUTH_DISCOVERY_URL` | OpenID Connect discovery document URL | - |
| `CUSTOM_OAUTH_SCOPES` | Comma-separated list of OAuth scopes | `profile,email` |
| `CUSTOM_OAUTH_RESPONSE_TYPE` | OAuth response type | `code` |
| `CUSTOM_AUTH_PKCE` | Enable/disable PKCE (Proof Key for Code Exchange) | `true` |
| `CUSTOM_OAUTH_LOGOUT_URL` | Logout endpoint URL (optional) | `https://id.example.com/api/oidc/logout` |
| `CUSTOM_OAUTH_AUTO_LOGIN` | Auto-redirect to the custom OAuth provider, bypassing the login page | `false` |

## Setup Steps

### 1. Configure Your OAuth Provider

First, create an OAuth 2.0 or OIDC application in your identity provider:

1. Log in to your identity provider's admin console
2. Create a new OAuth 2.0 or OIDC application
3. Set the redirect URI to: `{Ordo_API_URL}/api/auth/oauth2/callback/custom`
   * Example: `https://api.Ordo.example.com/api/auth/oauth2/callback/custom`
4. Copy the client ID and client secret
5. Note the authorization, token, and userinfo endpoint URLs

### 2. Set Environment Variables

Add the following to your `.env` file:

```bash theme={null}
# Custom OAuth/OIDC Configuration
CUSTOM_OAUTH_CLIENT_ID=your-client-id
CUSTOM_OAUTH_CLIENT_SECRET=your-client-secret
CUSTOM_OAUTH_AUTHORIZATION_URL=https://your-idp.com/authorize
CUSTOM_OAUTH_TOKEN_URL=https://your-idp.com/oauth/token
CUSTOM_OAUTH_USER_INFO_URL=https://your-idp.com/oauth/userinfo
CUSTOM_OAUTH_LOGOUT_URL=https://your-idp.com/oauth/logout

# Optional: Use discovery URL for automatic configuration
CUSTOM_OAUTH_DISCOVERY_URL=https://your-idp.com/.well-known/openid-configuration

# Optional: Customize scopes
CUSTOM_OAUTH_SCOPES=profile,email,openid

# Optional: Disable PKCE if your provider doesn't support it
CUSTOM_AUTH_PKCE=false
```

### 3. Restart Services

After updating the environment variables, restart your Ordo services:

```bash theme={null}
docker compose down
docker compose up -d
```

## Example Configurations

### Pocket ID

```bash theme={null}
CUSTOM_OAUTH_CLIENT_ID=2b1ae9df-8d25-4dbc-8cc8-f8f2c1ef6bd0
CUSTOM_OAUTH_CLIENT_SECRET=NzDjplDsdQyP062wTmkZ8kyiaziBag0N
CUSTOM_OAUTH_AUTHORIZATION_URL=https://4c6332d2.demo.pocket-id.org/authorize
CUSTOM_OAUTH_TOKEN_URL=https://4c6332d2.demo.pocket-id.org/api/oidc/token
CUSTOM_OAUTH_USER_INFO_URL=https://4c6332d2.demo.pocket-id.org/api/oidc/userinfo
CUSTOM_OAUTH_DISCOVERY_URL=https://4c6332d2.demo.pocket-id.org/.well-known/openid-configuration
CUSTOM_OAUTH_SCOPES=profile,email
```

### Keycloak

```bash theme={null}
CUSTOM_OAUTH_CLIENT_ID=Ordo-client
CUSTOM_OAUTH_CLIENT_SECRET=your-secret-here
CUSTOM_OAUTH_DISCOVERY_URL=https://keycloak.example.com/realms/your-realm/.well-known/openid-configuration
CUSTOM_OAUTH_LOGOUT_URL=https://keycloak.example.com/realms/your-realm/protocol/openid-connect/logout
CUSTOM_OAUTH_SCOPES=openid,profile,email
```

### Auth0

```bash theme={null}
CUSTOM_OAUTH_CLIENT_ID=your-client-id
CUSTOM_OAUTH_CLIENT_SECRET=your-client-secret
CUSTOM_OAUTH_AUTHORIZATION_URL=https://your-tenant.auth0.com/authorize
CUSTOM_OAUTH_TOKEN_URL=https://your-tenant.auth0.com/oauth/token
CUSTOM_OAUTH_USER_INFO_URL=https://your-tenant.auth0.com/userinfo
CUSTOM_OAUTH_SCOPES=openid,profile,email
```

## Usage

Once configured, users will see a "Continue with OIDC" button on the sign-in page. The system will automatically remember the last used login method for each user.

### Auto-Login (Skip the Login Page)

If you want to bypass the login page entirely and automatically redirect users to your identity provider, set:

```bash theme={null}
CUSTOM_OAUTH_AUTO_LOGIN=true
```

When enabled, users visiting the sign-in page will be immediately redirected to your custom OAuth provider without seeing the Ordo login page. This is ideal for organizations that use a single identity provider for all authentication.

## Troubleshooting

### "Invalid code verifier" Error

This error typically indicates a PKCE configuration issue. Try setting:

```bash theme={null}
CUSTOM_AUTH_PKCE=false
```

Some OAuth providers don't support PKCE or have it disabled by default.

### Missing User Information

Ensure your OAuth scopes include at least `profile` and `email`:

```bash theme={null}
CUSTOM_OAUTH_SCOPES=profile,email
```

Some providers require `openid` scope as well:

```bash theme={null}
CUSTOM_OAUTH_SCOPES=openid,profile,email
```

### Redirect URI Mismatch

Verify that your redirect URI in the OAuth provider matches exactly:

```
{Ordo_API_URL}/api/auth/oauth2/callback/custom
```

For example, if `Ordo_API_URL=https://api.Ordo.example.com`, the redirect URI should be:

```
https://api.Ordo.example.com/api/auth/oauth2/callback/custom
```

## Discovery URL

If your provider supports OpenID Connect, you can use the discovery URL to automatically configure most settings:

```bash theme={null}
CUSTOM_OAUTH_DISCOVERY_URL=https://your-idp.com/.well-known/openid-configuration
```

This will automatically discover the authorization, token, and userinfo endpoints. However, you still need to provide the client ID and secret.

## Security Notes

* Always use HTTPS in production
* Keep your client secret secure and never commit it to version control
* Enable PKCE when possible for enhanced security
* Use the most restrictive scopes necessary for your use case


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.