Set up Custom OIDC

Custom OIDC lets you add your own OpenID Connect (OIDC) identity provider — an enterprise SSO, your existing auth system, or any standards-compliant IdP — as a login method in Para. Users sign in with your provider and get a Para embedded wallet, just like any other social login. In this flow Para is the OIDC client (relying party) and your provider is the identity provider. You configure it once on your partner record — from the Developer Portal or the Para CLI — and it works everywhere your app authenticates: the Para Modal renders it automatically, and your own custom UI can trigger it like any OAuth method.

Custom OIDC is for end users signing in through Para with your IdP. If your backend already authenticates users and you only need server-side wallets, see Bring Your Own Auth instead — a different pattern.

How it works

A user selects your provider on the Para login screen.
Para redirects them to your IdP to sign in.
Your IdP redirects back to Para’s callback with an authorization code.
Para exchanges the code, verifies the identity, and creates or loads the user’s Para wallet.

You give Para a client ID and client secret from your IdP; Para gives you a redirect URI to register with your IdP. That’s the whole handshake.

Before you start

An OpenID Connect provider that supports OIDC Discovery (it serves a /.well-known/openid-configuration document).
Admin access to register a new client with that provider.
A Para project and API key — create one if you haven’t.
For production API keys, an organization on the Scale or Enterprise plan. Custom OIDC is available on every plan in the beta environment, so you can build and test before upgrading.

One provider or several? This page sets up a single OIDC provider, which works on all current Para SDK versions. You can also register multiple OIDC providers as named connections — see Multiple OIDC providers below for how, and for the SDK version that requires.

1. Register Para with your provider

In your identity provider, register a new OIDC client (sometimes called an “application” or “relying party”) and note its Client ID and Client secret. Add both of Para’s redirect URIs to the client’s list of allowed redirect URIs. Sign-ins may use either one until all of your users are on the current Para SDK login flow:

https://api.getpara.com/auth/custom_oidc/callback
https://api.getpara.com/internal/v1/auth/oauth/custom_oidc/callback

https://api.beta.getpara.com/auth/custom_oidc/callback
https://api.beta.getpara.com/internal/v1/auth/oauth/custom_oidc/callback

Para uses the same redirect URIs for every project in an environment — your project context is carried in the OAuth state parameter. The exact URIs are also shown when you configure Custom OIDC in the next step.

2. Configure Custom OIDC in Para

Set up the default provider with the Para CLI. After that you can edit it in the Developer Portal, where you can also add more OIDC providers as named connections.

Para CLI
Developer Portal

Configure the same settings with the Para CLI:

# Set the provider config
para keys config oidc set <key-id> \
  --issuer https://idp.yourcompany.com \
  --client-id your-client-id \
  --scopes "openid email profile" \
  --auth-method client_secret_post \
  --label "Sign in with Acme"
# → Updated Custom OIDC on My App (production)

# Store the client secret (prompted; the value is never echoed or written to .pararc)
para keys config oidc set-secret <key-id>
# → Stored the Custom OIDC client secret on My App (production).

# Confirm Para can reach your provider
para keys config oidc verify <key-id>
# → Custom OIDC provider verified on My App (production).

# Enable Custom OIDC as a login method
para keys config auth <key-id> --oauth-methods CUSTOM_OIDC

Review the saved configuration at any time with show:

$ para keys config oidc show <key-id>
  Issuer         https://idp.yourcompany.com
  Client ID      your-client-id
  Scopes         openid email profile
  Auth method    client_secret_post
  Sign-in label  Sign in with Acme
  Client secret  set

--oauth-methods sets the full OAuth list, so include any other providers you want enabled alongside CUSTOM_OIDC.

3. Use it in your app

Once Custom OIDC is enabled, no extra SDK code is required to make it appear. The Para Modal renders a Custom OIDC button automatically, labeled with your sign-in label. Users tap it, sign in with your provider, and land back in your app with a Para wallet.

With your own UI

If you build your own login UI, trigger Custom OIDC like any other OAuth provider — pass "CUSTOM_OIDC" as the method:

const result = await para.authenticateWithOAuth({
  method: "CUSTOM_OIDC",
  redirectCallbacks: {
    onOAuthPopup: (popup) => {
      // keep a handle to the popup if you want to track it
    },
  },
});

See Build a Custom UI for the full OAuth flow. To label your own button consistently, read the configured value from para.config.authConfig?.oidcConfig?.buttonLabel. A provider added as a named connection signs in differently; see Sign in with a connection.

Custom OIDC is a CUSTOM_OIDC OAuth method on the web and in React Native. In a React Native app, follow the social login guide and pass CUSTOM_OIDC as the method. The Swift and Flutter SDKs don’t support Custom OIDC.

Multiple OIDC providers

Beyond the single provider above, you can register several OIDC providers side by side — for example, one SSO per enterprise customer. Each one is a named connection with its own handle, credentials, and sign-in button.

SDK version requirement. Your first (default) OIDC provider renders on all current SDK versions. Additional OIDC connections only render in Para Modal / React SDK version 3.20.0 and later — apps on older versions show just the default provider’s button.

Add a connection from the Authentication screen with Add custom provider, choosing the OpenID Connect provider (the same fields as above, plus a Handle: a short lowercase slug like acme-sso), or with the CLI:

# Register the connection
para keys config oauth add \
  --provider CUSTOM_OIDC \
  --handle acme-sso \
  --client-id your-client-id \
  --issuer https://idp.acme.com \
  --button-label "Sign in with Acme"

# Store the secret, verify, and enable it in the login-method list
para keys config oauth set-secret acme-sso
para keys config oauth verify acme-sso
para keys config auth <key-id> --oauth-methods GOOGLE,acme-sso

A connection uses only the current-flow redirect URI, https://api.getpara.com/internal/v1/auth/oauth/custom_oidc/callback in production (copy it from the connection dialog). If you move an existing single-provider setup to connections, keep the /auth/custom_oidc/callback URI registered with your IdP too: apps on older SDK versions continue to use it. The Para Modal renders each enabled connection as its own button. In your own UI: Sign users in through a connection with authenticateWithCustomOAuth (or the useAuthenticateWithCustomOAuth hook), not authenticateWithOAuth. Pass:

provider: "CUSTOM_OIDC" for an OpenID Connect connection, "CUSTOM_OAUTH" for an OAuth 2.0 connection.
providerConfigHandle: the connection’s handle, such as acme-sso or spotify.

The call resolves once the user is signed in and their wallets are ready. It requires Para SDK 3.20.0 or later.

React hooks
Web SDK
React Native

Call it directly from the button’s click handler. With onOAuthPopup, the SDK opens a popup right away, while the click still allows one, and sends it to the sign-in page itself. The callback only hands you the window. Without it, the SDK sends the current page to the sign-in page instead.

import { useAuthenticateWithCustomOAuth } from "@getpara/react-sdk";

export function SignInWithAcme() {
  const { authenticateWithCustomOAuthAsync, isPending } = useAuthenticateWithCustomOAuth();

  const handleClick = async () => {
    try {
      const result = await authenticateWithCustomOAuthAsync({
        provider: "CUSTOM_OIDC",
        providerConfigHandle: "acme-sso",
        redirectCallbacks: {
          onOAuthPopup: (popup) => {
            // Optional: keep the window if you want to track it
          },
        },
      });
      console.log("Signed in:", result.authInfo);
    } catch (error) {
      console.error("Sign-in failed:", error);
    }
  };

  return (
    <button onClick={handleClick} disabled={isPending}>
      Sign in with Acme
    </button>
  );
}

Call it directly from the button’s click handler. With onOAuthPopup, the SDK opens a popup right away and sends it to the sign-in page itself. Without it, the SDK sends the current page to the sign-in page instead.

import { para } from "./your-para-client";

async function signInWithSpotify() {
  const result = await para.authenticateWithCustomOAuth({
    provider: "CUSTOM_OAUTH",
    providerConfigHandle: "spotify",
    redirectCallbacks: {
      onOAuthPopup: (popup) => {
        // Optional: keep the window if you want to track it
      },
    },
  });
  console.log("Signed in:", result.authInfo);
}

document.getElementById("spotify-button")!.addEventListener("click", signInWithSpotify);

Pass your appScheme and open the sign-in page from onOAuthUrl in an in-app browser, as in the social login guide.

import { openAuthSessionAsync } from "expo-web-browser";
import { para } from "../your-para-client";

const APP_SCHEME = "your-app-scheme";

const result = await para.authenticateWithCustomOAuth({
  provider: "CUSTOM_OIDC",
  providerConfigHandle: "acme-sso",
  appScheme: APP_SCHEME,
  redirectCallbacks: {
    onOAuthUrl: async (url) => {
      await openAuthSessionAsync(url, APP_SCHEME);
    },
  },
});

To render one button per connection, read the enabled connections from para.config.authConfig.oauthConnections. Each entry has a handle, a provider, a label and logoUrl for the button, and an oidc flag. Pass "CUSTOM_OIDC" when oidc is true. An entry whose provider is a built-in name such as GOOGLE is your own credentials for that provider, so keep signing in with authenticateWithOAuth. Any other entry is a custom OAuth 2.0 connection, so pass "CUSTOM_OAUTH". The Swift and Flutter SDKs don’t support custom connections.

Token endpoint authentication methods

Token endpoint authentication controls how Para authenticates to your provider’s token endpoint when it exchanges the authorization code:

Method	Behavior
`client_secret_post`	Default. Para sends the client ID and secret in the request body.
`client_secret_basic`	Para sends the client ID and secret as an HTTP Basic auth header.
`none`	Public client — no secret. Use only if your provider issued a public (PKCE) client.

Choose the method your provider expects for the client you registered. client_secret_post and client_secret_basic require a client secret; none requires none.

Security

Your client secret is write-only. Para stores it with KMS envelope encryption and never returns it. The CLI prompts for it without echoing, and it’s never written to .pararc.
The issuer must be https with no query string — this keeps credentials out of the stored issuer and any logs. A path is fine (https://idp.yourcompany.com/tenant-123).
Para validates your provider’s discovery document over the network when it connects; private and internal addresses are rejected.

Troubleshooting

The redirect fails with a redirect_uri mismatch

The redirect URIs registered with your provider must exactly match Para’s callbacks for the environment you’re using. Register both the /auth/custom_oidc/callback and the /internal/v1/auth/oauth/custom_oidc/callback URI for https://api.getpara.com (production) or https://api.beta.getpara.com (beta); a sign-in fails on whichever one is missing. Re-copy them from the Custom OIDC configuration.

The Issuer URL is rejected

The issuer must be https with no query string, fragment, or credentials — just https://host/path. Para fetches your discovery document from {issuer}/.well-known/openid-configuration.

Verify says Para can't reach your provider

Para couldn’t load your discovery document. Confirm the issuer is publicly reachable over HTTPS and serves a valid /.well-known/openid-configuration.

Custom OIDC vs Bring Your Own Auth

Both let you use your own identity system, but they’re different integrations:

	Custom OIDC	Bring Your Own Auth
Who authenticates the user	Your OIDC provider, through the Para login flow	Your backend, before it calls Para
Where it runs	Client — the Para Modal or your own UI	Server-to-server, over the REST API
Use when	You want a login button for your IdP or SSO	You already authenticate users and want server-side wallets

Getting Started

Choose a Path

Project Setup

Go Live

How Para Works

Shared Guides

Migrations

Set up Custom OIDC

How it works

Before you start

1. Register Para with your provider

2. Configure Custom OIDC in Para

3. Use it in your app

With your own UI

Multiple OIDC providers

Token endpoint authentication methods

Security

Troubleshooting

Custom OIDC vs Bring Your Own Auth

Next steps

How it works

Before you start

1. Register Para with your provider

2. Configure Custom OIDC in Para

3. Use it in your app

With the Para Modal

With your own UI

Multiple OIDC providers

Sign in with a connection

Token endpoint authentication methods

Security

Troubleshooting

Custom OIDC vs Bring Your Own Auth

Next steps