Protocol

OAuth 2.0 / OpenID Connect

Connect any OAuth 2.0 or OpenID Connect compatible identity provider to SecurePie. This guide covers OIDC Discovery, manual configuration, and custom OAuth setups.

15 min setup
OAuth 2.0 / OIDC

OIDC Discovery (Recommended)

If your IdP supports OpenID Connect Discovery, configuration is simple:

Auto-Discovery

Simply provide your IdP's discovery URL and SecurePie will automatically fetch all required endpoints and keys.

Discovery URL:
https://your-idp.com/.well-known/openid-configuration

Callback URLs

Register these callback URLs in your OAuth application settings:

SecurePie Callback URLs

// OAuth Callback URLs
Authorization Callback:  https://securepie.com/oauth/callback/YOUR_ORG_ID
Post-Logout Redirect:    https://securepie.com/oauth/logout/YOUR_ORG_ID

// For development/testing
localhost:               http://localhost:3000/oauth/callback/YOUR_ORG_ID

Manual Configuration

If your IdP doesn't support OIDC Discovery, configure these settings manually:

OAuth Configuration

// SecurePie OAuth/OIDC Configuration
{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "authorizationEndpoint": "https://idp.example.com/oauth/authorize",
  "tokenEndpoint": "https://idp.example.com/oauth/token",
  "userInfoEndpoint": "https://idp.example.com/oauth/userinfo",
  "jwksUri": "https://idp.example.com/.well-known/jwks.json",
  "issuer": "https://idp.example.com",
  "scopes": ["openid", "email", "profile"]
}

Required Settings

  • • Client ID
  • • Client Secret
  • • Authorization Endpoint
  • • Token Endpoint

Optional Settings

  • • UserInfo Endpoint
  • • JWKS URI (for ID token validation)
  • • Custom scopes
  • • Logout endpoint

Claim Mapping

SecurePie maps standard OIDC claims to user attributes:

// Standard OIDC Claims → SecurePie Attributes
OIDC Claim              →    SecurePie Attribute
─────────────────────────────────────────────────
sub                     →    externalId
email                   →    email
email_verified          →    emailVerified
given_name              →    firstName
family_name             →    lastName
name                    →    displayName
picture                 →    avatarUrl
groups (custom)         →    groups

Custom Claims

Need to map custom claims? Contact support or configure custom claim mappings in Settings → Identity Providers → Advanced.

Supported Authentication Flows

Authorization Code Flow

Recommended for web applications. Most secure option.

Recommended
  1. 1.User clicks "Sign in with SSO"
  2. 2.Redirect to IdP authorization endpoint
  3. 3.User authenticates at IdP
  4. 4.IdP redirects back with authorization code
  5. 5.SecurePie exchanges code for tokens
  6. 6.User session created

Authorization Code + PKCE

Enhanced security for public clients and SPAs.

Recommended
  1. 1.Generate code_verifier and code_challenge
  2. 2.Include code_challenge in authorization request
  3. 3.After callback, include code_verifier in token request
  4. 4.IdP validates PKCE before issuing tokens

Token Handling

ID Token Validation

  • Signature verification (RS256, RS384, RS512)
  • Issuer (iss) validation
  • Audience (aud) validation
  • Expiration (exp) check

Access Token Usage

  • UserInfo endpoint calls
  • Token refresh support
  • Secure token storage
  • Token revocation on logout

Common Issues

Invalid redirect_uri

Ensure the callback URL registered in your IdP exactly matches the SecurePie callback URL, including protocol and trailing slashes.

Invalid client credentials

Verify your Client ID and Client Secret are correct. Some IdPs require the secret to be URL-encoded.

Missing scopes

Ensure your OAuth application has permission to request theopenid,email, andprofile scopes.

Need Help?

OAuth configurations vary between providers. Our team can help you integrate any OAuth 2.0 or OIDC compatible identity provider.

Contact SupportBack to Docs