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. Before You Begin
2. Step 1: Verify Your Email Domain
3. Step 2: Configure Your Identity Provider
4. Step 3: Configure SSO in ScribbleMaps
5. Step 4: Test Your Configuration
6. Step 5: Enable SSO
7. Provider-Specific Guides
8. Advanced Options
9. Troubleshooting

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 SSO (OIDC/SAML) on the left side bar
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

You'll need to configure ScribbleMaps as an application in your Identity Provider. Use the following Service Provider details:

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 SSO (OIDC/SAML) > 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 (at top) switch to ON

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

Provider-Specific Guides

Okta (SAML)

1. In Okta Admin Console, go to Applications > Create App Integration
2. Select SAML 2.0
3. Configure:
   • Single sign-on URL: https://api.scribblemaps.com/saml/acs
   • Audience URI (SP Entity ID): https://api.scribblemaps.com/saml/metadata
   • Name ID format: Email Address
4. Download the X.509 Certificate from the Sign On tab
5. Copy the Identity Provider Issuer and Single Sign-On URL

Okta (OIDC)

1. In Okta Admin Console, go to Applications > Create App Integration
2. Select OIDC - OpenID Connect > Web Application
3. Configure:
   • Sign-in redirect URI: https://api.scribblemaps.com/oidc/callback
   • Sign-out redirect URI: https://api.scribblemaps.com/oidc/logout-callback
4. Copy the Client ID and Client Secret
5. Authority URL: https://YOUR-DOMAIN.okta.com

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 SSO (OIDC/SAML) > 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.