Configuring Single Sign-On (SSO) with SAML or OIDC

ScribbleMaps supports enterprise Single Sign-On using either SAML 2.0 or OpenID Connect (OIDC). This allows your team members to authenticate using your organization's Identity Provider (IdP) such as Okta, Microsoft Entra ID (Azure AD), Google Workspace, or Auth0.

SSO configuration is available at team.scribblemaps.com and is completely free.

Table of Contents

1. Supported Features
2. Before You Begin
3. Step 1: Verify Your Email Domain
4. Step 2: Configure Your Identity Provider
5. Step 3: Configure SSO in ScribbleMaps
6. Step 4: Test Your Configuration
7. Step 5: Enable SSO
8. SP-Initiated SSO
9. OIN Universal Logout
10. Provider-Specific Guides
11. Advanced Options
12. Troubleshooting

Supported Features

The ScribbleMaps SSO integration supports the following features:

Before You Begin

• You must be a Team Owner to configure SSO
• You need access to your organization's Identity Provider admin console
• Have your email domain ready (e.g., yourcompany.com)

Step 1: Verify Your Email Domain

Before configuring SSO, you must verify ownership of your email domain. This security measure ensures only authorized organizations can configure SSO for their domains.

1. Log in to team.scribblemaps.com
2. Navigate to Settings > Single Sign-On
3. Go to the Domains tab
4. Click Add Domain and enter your email domain (e.g., yourcompany.com)
5. Choose a verification method:

Option A: DNS TXT Record (Recommended)

Add a TXT record to your domain's DNS settings:

Note: DNS changes can take up to 48 hours to propagate.

Option B: File Upload

1. Create a text file named scribblemaps-verify.txt
2. Add your verification code as the only content
3. Upload to: https://yourcompany.com/.well-known/scribblemaps-verify.txt

After adding the verification, click Verify Domain to confirm ownership.

Step 2: Configure Your Identity Provider

Add ScribbleMaps as an application in your Identity Provider. If you are using Okta, you can add ScribbleMaps directly from the Okta Integration Network (OIN) catalog — the SAML SSO URL, SP Entity ID, ACS URL, and OIDC Redirect URI are pre-configured automatically.

For SAML 2.0

For OIDC

Step 3: Configure SSO in ScribbleMaps

Configuring SAML 2.0

1. In ScribbleMaps, go to Settings > Single Sign-On > SAML tab
2. Enter the following information from your Identity Provider:

3. Click Save Settings

Configuring OIDC

1. In ScribbleMaps, go to Settings > Single Sign-On > OIDC tab
2. Select your Provider Type (Google, Microsoft, Okta, Auth0, or Custom)
3. Enter the following information:

4. Click Save Settings

Step 4: Test Your Configuration

Before enabling SSO for all users, test your configuration:

1. Click the Test Connection button
2. A new window will open to simulate the SSO login flow
3. Complete authentication with your Identity Provider
4. Verify you're successfully redirected back to ScribbleMaps

If the test fails, review the error message and check your configuration settings.

Step 5: Enable SSO

Once testing is successful:

1. Toggle the Enable SSO switch to ON
2. Choose your enforcement option:
   • Optional: Users can choose SSO or password login
   • Enforced: Users with verified email domains must use SSO (password login disabled)

Note: Team Owners can always use password login as a backup, even when SSO is enforced.

SP-Initiated SSO

ScribbleMaps supports SP-initiated SSO, which allows users to start the sign-in process from the ScribbleMaps login page. Here's how it works:

1. Navigate to scribblemaps.com/account/login
2. Enter your email address (e.g., [email protected])
3. Click Sign in with SSO
4. You will be redirected to your organization's Identity Provider (e.g., Okta) to authenticate
5. After successful authentication, you are automatically redirected back to ScribbleMaps and signed in

If your organization has SSO enforced, entering your email on the login page will automatically redirect you to your Identity Provider — no password field will be shown.

OIN Universal Logout

Universal logout by Okta is supported. For configuration instructions please visit this link.

Provider-Specific Guides

Okta

1. In the Okta Admin Console, go to Applications > Browse App Catalog
2. Search for ScribbleMaps and click Add Integration
3. The SSO URL, Entity ID, and Redirect URI are pre-configured automatically
4. Go to the Sign On tab to find your IdP configuration details:
   • Download the X.509 Certificate
   • Copy the Identity Provider Issuer (Entity ID)
   • Copy the Single Sign-On URL
5. Enter these values into ScribbleMaps SSO settings (see Step 3)

Microsoft Entra ID (Azure AD)

1. In Azure Portal, go to Microsoft Entra ID > App registrations > New registration
2. Configure:
   • Redirect URI: https://api.scribblemaps.com/oidc/callback (Web platform)
3. Go to Certificates & secrets > Create a new Client secret
4. Copy the Application (client) ID and Client secret value
5. Authority URL: https://login.microsoftonline.com/YOUR-TENANT-ID/v2.0

Google Workspace

1. In Google Cloud Console, go to APIs & Services > Credentials
2. Click Create Credentials > OAuth client ID
3. Select Web application
4. Add Authorized redirect URI: https://api.scribblemaps.com/oidc/callback
5. Copy the Client ID and Client Secret
6. Authority URL: https://accounts.google.com

Note: To require MFA for Google Workspace, configure it in your Google Workspace Admin Console.

Auth0

1. In Auth0 Dashboard, go to Applications > Create Application
2. Select Regular Web Applications
3. Configure:
   • Allowed Callback URLs: https://api.scribblemaps.com/oidc/callback
   • Allowed Logout URLs: https://api.scribblemaps.com/oidc/logout-callback
4. Copy the Client ID and Client Secret from the Settings tab
5. Authority URL: https://YOUR-DOMAIN.auth0.com

Advanced Options

Just-In-Time (JIT) Provisioning

When enabled, users are automatically created in ScribbleMaps on their first SSO login. Their profile information (name, email) is populated from the Identity Provider.

Require Multi-Factor Authentication (OIDC only)

Enable this option to require MFA verification before allowing login. ScribbleMaps will verify that your IdP has enforced MFA for the user.

For Okta, you can specify custom ACR values such as:

• urn:okta:loa:2fa:any - Any second factor
• phr - Phishing-resistant authentication
• phrh - Phishing-resistant hardware-bound authentication

Attribute/Claim Mapping

Customize how user attributes from your IdP map to ScribbleMaps user fields:

Troubleshooting

Common Issues

"Domain not verified"

• Ensure your DNS TXT record or verification file is correctly configured
• DNS changes can take up to 48 hours to propagate
• Verify there are no typos in the verification code

"Invalid certificate"

• Ensure you're using the complete certificate including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----
• Check that the certificate hasn't expired
• Make sure you copied the signing certificate, not an encryption certificate

"Invalid signature"

• Verify the certificate matches your IdP's current signing certificate
• Check that the signature algorithm matches (SHA-256 vs SHA-1)

"User not found" or "Email mismatch"

• Ensure the email returned by your IdP matches a verified domain
• Check that the NameID format is set to Email Address
• Verify attribute/claim mapping is correct

"Security error: Your Identity Provider is not authorized for this email domain"

• This occurs when the IdP configuration doesn't match the verified domain
• Ensure the email domain is verified under your team
• Check that you're logging in with an email from a verified domain

Viewing Audit Logs

Monitor SSO activity in Settings > Single Sign-On > Audit Logs. You can:

• Filter by event type (Login, Logout, Failed Login)
• Filter by date range
• Export logs as CSV for compliance reporting

Need Help?

If you're experiencing issues with SSO configuration, please contact our support team with:

• Your Team name
• The Identity Provider you're using
• Any error messages you're seeing
• Screenshots of your IdP configuration (with sensitive data redacted)

We're here to help you get SSO configured for your organization.