Skip to main content

Configuring OIDC-Based Single Sign-On (SSO)

Overview​

This document explains how to enable OpenID Connect (OIDC)-based SSO for seamless access to Paperbox. OIDC is an identity layer on top of OAuth 2.0, designed to verify a user’s identity and provide profile information in an ID token.

login screen

Prerequisites​

  • You must have administrator (or equivalent) privileges in your identity provider (IdP).
  • You must be able to create or configure an OIDC application in your IdP.

1. Summary​

When you set up Paperbox as the Service Provider (SP) inside your IdP, you’ll be asked for:

1.1 Service Provider (Paperbox) Info​

When you configure an OIDC application for Paperbox, you’ll need the following:

  1. Redirect URI (Callback URL)

    https://paperbox-<env>.firebaseapp.com/__/auth/handler
    • <env> can be acc (acceptance) or prd (production).
    • Often entered in the “Redirect URIs” or “Reply URLs” section of your IdP’s configuration.

  2. Enable ID Tokens

1.2 Identity Provider (IdP) Info​

Paperbox will need the following from your IdP:

  1. Client ID

    • A unique identifier for your Paperbox application in the IdP.

  2. Issuer / Authority URL

    • Typically looks like https://login.microsoftonline.com/<tenantId>/v2.0 for Microsoft Entra, or a similar URL for other providers.
    • This tells Paperbox where to direct OIDC authentication requests and retrieve your identity provider’s configuration.

1.3 User Roles​

By default, Paperbox recognizes the roles:

  • user
  • admin

2. Setting Up OIDC in Your Identity Provider​

Below are example steps using Microsoft Entra (Azure AD). Other providers (Okta, Auth0, etc.) will have a similar process.

2.1 Create a New OIDC App​

  1. Open your IdP’s Admin Console
    • In Microsoft Entra: go to App Registrations → New Registration. app list

      Microsoft Entra → App Registration

  2. Name the Application (e.g., “Paperbox OIDC SSO”). app registration settings

    Microsoft Entra → App Registration → New Registration

  3. When forgotten in step 2, Enter the Redirect URI (under “Web” type). Use:
    https://paperbox-<env>.firebaseapp.com/__/auth/handler
    app registration settings

    Microsoft Entra → App Registration → Authentication

2.2 Gather OIDC Configuration Details​

  1. Locate the Client ID

    • In Microsoft Entra, this is listed under “Application (client) ID.” app registration

      Microsoft Entra → App Registration

  2. Find the Issuer / Authority

    • This might be shown in your application’s endpoints or “Well-known openid-configuration” URL.

    • Example (Azure AD): https://login.microsoftonline.com/<tenantId>/v2.0 app registration

      Microsoft Entra → App Registration

      app registration

      Microsoft Entra → App Registration → Endpoints

  3. Ensure ID Token Issuance is Enabled

    • In Microsoft Entra, under “Authentication,” ensure ID tokens are checked if required. app registration authentication

      Microsoft Entra → App Registration → Authentication

2.3 Role/Group Assignments (Optional)​

If you wish to assign roles (e.g., user, admin) via OIDC:

  1. Configure App Roles in your IdP’s application settings.
  2. Assign those roles to users or groups.
  3. Enable them as claims in the ID token or pass them as group membership. app registration settings

    Microsoft Entra → App Registration → Roles

Note: Paperbox can map these roles from the ID token claims if configured correctly.

3. Provide Paperbox Your OIDC Details​

Once your OIDC application is created, share the following with Paperbox:

  • Client ID
  • Issuer URL (or the full /.well-known/openid-configuration endpoint; which we can infer it from)

Paperbox will configure the Service Provider side to trust your IdP.

4. Testing & Validation​

  1. Test Log In: Attempt to sign in to Paperbox using OIDC.
  2. Verify the Redirection to your IdP’s login page.
  3. Check the Issued ID Token: Confirm the user claims (email, sub) are correct.
  4. Role/Group Validations: If using roles, confirm they show up in Paperbox correctly or that your admin settings in Paperbox map them.

app registration settings

Microsoft Entra → Enterprise Apps → Users and Groups (Roles or group assignments are similar in OIDC)

Conclusion​

Enabling OIDC-based Single Sign-On (SSO) in Paperbox improves security and simplifies the user login experience. By creating an OIDC application in your identity provider, configuring the Redirect URI, Client ID, Issuer, and ensuring ID tokens include the user’s email, your Paperbox environment will be ready to authenticate users via your IdP.

If you have questions or encounter issues, reach out to Paperbox Support for further assistance. We’ll help verify the final steps and ensure a smooth login experience for your users.