Skip to content
RAMP Documentation

OIDC / OAuth2 Setup

This guide walks you through configuring RAMP to use OpenID Connect (OIDC) authentication with popular identity providers like Azure AD, Okta, Keycloak, or Auth0.

What is OIDC Authentication?

Section titled “What is OIDC Authentication?”

OpenID Connect (OIDC) is a modern authentication protocol that allows RAMP to delegate user authentication to your organization’s identity provider. Benefits include:

  • Single Sign-On (SSO) — Users log in once for all applications
  • Centralized user management — Manage users in one place
  • Enhanced security — MFA, conditional access, and security policies managed by your IdP
  • No password storage — RAMP never stores or handles passwords

Prerequisites

Section titled “Prerequisites”

Before you begin, ensure you have:

  • An OIDC-compliant identity provider (Azure AD, Okta, Keycloak, Auth0, etc.)
  • Admin access to register applications in your IdP
  • RAMP backend API deployed and accessible
  • RAMP frontend deployed or running in development

Quick Start

Section titled “Quick Start”

  1. Register RAMP in Your Identity Provider

    Section titled “Register RAMP in Your Identity Provider”

    You need to register RAMP as an application/client in your identity provider.

    Required Settings:

    • Application Type: Public (SPA/Browser Application)
    • Grant Type: Authorization Code with PKCE
    • Redirect URI: https://your-ramp-domain.com/_auth/callback
    • Post-Logout Redirect URI: https://your-ramp-domain.com
    • Scopes: openid profile email

    After registration, note these values:

    • Authority URL (e.g., https://login.microsoftonline.com/{tenant-id}/v2.0)
    • Client ID (e.g., abc123-def456-ghi789)

  2. Configure RAMP Frontend

    Section titled “Configure RAMP Frontend”

    Create or update .env.local (development) or .env.production in src/RAMP.Web/:

    Terminal window
    # Enable OIDC Authentication
    VITE_OIDC_ENABLED=true
    

    # Your identity provider's authority URL
    VITE_OIDC_AUTHORITY=https://your-idp.com
    

    # Client ID from Step 1
    VITE_OIDC_CLIENT_ID=your-client-id
    

    # Redirect URI (must match IdP registration)
    VITE_OIDC_REDIRECT_URI=https://your-ramp-domain.com/_auth/callback
    

    # Optional: Post-logout redirect
    VITE_OIDC_POST_LOGOUT_REDIRECT_URI=https://your-ramp-domain.com
    

    # Optional: Custom scopes (defaults to "openid profile email")
    VITE_OIDC_SCOPE=openid profile email

  3. Configure RAMP Backend (Optional)

    Section titled “Configure RAMP Backend (Optional)”

    The backend requires minimal configuration for OIDC since authentication happens in the frontend. However, you should configure the JWT validation settings.

    Update appsettings.json:

    {
      "Jwt": {
        "Secret": "YourSecretKeyAtLeast32CharactersLong!",
        "Issuer": "RAMP.API",
        "Audience": "RAMP.Web",
        "AccessTokenExpirationMinutes": 480,
        "RefreshTokenExpirationDays": 30
      }
    }

  4. Test the Configuration

    Section titled “Test the Configuration”

    Start the RAMP frontend:

    Terminal window
    cd src/RAMP.Web
    npm run dev

    Navigate to RAMP in your browser:

    • Development: http://localhost:5173
    • Production: https://your-ramp-domain.com

    Expected Flow:

    • You’re redirected to your identity provider’s login page
    • Log in with your credentials
    • After successful authentication, you’re redirected back to RAMP
    • You should see the RAMP dashboard with your name/email

    Verify in Browser Console:

    • Open Developer Tools and check the Console
    • You should see successful authentication messages
    • No CORS or redirect errors

Provider-Specific Examples

Section titled “Provider-Specific Examples”

Authority URL:

https://login.microsoftonline.com/{tenant-id}/v2.0

Configuration:

Terminal window
VITE_OIDC_AUTHORITY=https://login.microsoftonline.com/your-tenant-id/v2.0
VITE_OIDC_CLIENT_ID=your-application-client-id
VITE_OIDC_SCOPE=openid profile email User.Read

App Registration:

  1. Azure Portal -> Entra ID -> App Registrations -> New registration
  2. Add redirect URI: https://your-ramp-domain.com/_auth/callback
  3. Authentication -> Enable “Access tokens” and “ID tokens”
  4. API permissions -> Add User.Read from Microsoft Graph

Troubleshooting

Section titled “Troubleshooting”

”Invalid redirect_uri” Error

Section titled “”Invalid redirect_uri” Error”

Problem: Identity provider rejects the redirect URI.

Solution:

  • Ensure VITE_OIDC_REDIRECT_URI exactly matches what’s registered in your IdP
  • Check protocol (http vs https)
  • Check port number (include :5173 for dev, omit for production on standard ports)
  • Check trailing slashes (some IdPs are strict)
  • Check case sensitivity

”Client not found” Error

Section titled “”Client not found” Error”

Problem: Identity provider doesn’t recognize the client ID.

Solution:

  • Verify VITE_OIDC_CLIENT_ID matches exactly (case-sensitive)
  • Ensure the client/application is enabled in your IdP
  • Check you’re using the correct environment (dev vs prod client ID)

CORS Errors in Browser Console

Section titled “CORS Errors in Browser Console”

Problem: Browser blocks requests due to CORS policy.

Solution:

  • Ensure your IdP allows requests from RAMP’s origin
  • In IdP configuration, add https://your-ramp-domain.com to allowed origins
  • For development, add http://localhost:5173 to allowed origins

Infinite Redirect Loop

Section titled “Infinite Redirect Loop”

Problem: Browser keeps redirecting between RAMP and IdP.

Solution:

  • Check that VITE_OIDC_SCOPE includes openid
  • Verify the client is configured for Authorization Code flow
  • Clear browser cookies and local storage
  • Check browser console for detailed error messages

User Authenticated But Shows No Roles

Section titled “User Authenticated But Shows No Roles”

Problem: User logs in successfully but has no permissions in RAMP.

Solution:

This is expected behavior for first-time OIDC users. An administrator needs to assign roles:

  1. Log in as an administrator
  2. Navigate to Admin -> Users
  3. Find the user (search by email)
  4. Click Assign Roles
  5. Assign appropriate application roles

Alternatively, configure Bootstrap Administrators to automatically assign roles to specific users on first login.

Security Best Practices

Section titled “Security Best Practices”

Production Deployment

Section titled “Production Deployment”
  • Use HTTPS — Always use TLS/SSL certificates in production
  • Validate redirect URIs — Only register necessary redirect URIs
  • Scope minimization — Only request scopes RAMP needs (openid profile email)
  • Short token lifetimes — Configure tokens to expire within 1 hour
  • Secure client registration — Use appropriate client authentication settings
  • Monitor failed logins — Enable audit logging in your IdP

Token Storage

Section titled “Token Storage”

RAMP stores tokens in browser session storage which:

  • Clears when the browser tab/window closes
  • Is not accessible to other websites
  • Is not persisted to disk

User Provisioning

Section titled “User Provisioning”

Automatic User Creation

Section titled “Automatic User Creation”

When a user logs in via OIDC for the first time:

  1. RAMP receives claims from your identity provider (name, email, sub)
  2. RAMP checks if a user with this ProviderSubjectId exists
  3. If not, RAMP creates a new user account automatically
  4. User profile is populated from OIDC claims:
    • sub claim -> Unique identifier
    • email claim -> Email address
    • name or preferred_username -> Display name

Required Claims

Section titled “Required Claims”

Your identity provider must return these claims:

ClaimPurposeExample
subUnique user identifier248289761001
emailUser’s email addressjohn.doe@company.com
name or preferred_usernameDisplay nameJohn Doe

If these claims are missing, user creation will fail.

Next Steps

Section titled “Next Steps”

After configuring OIDC authentication:

Section titled “Related topics”
Authentication Overview Compare all authentication methods and choose the right one
LDAP Authentication Setup Authenticate against Active Directory or OpenLDAP with directory search