Skip to main content

Setting up SAML-based single sign-on (SSO)

Kyle Conarro avatar
Written by Kyle Conarro
Updated this week

If your team uses an identity provider like Okta, Google Workspace, or Microsoft Entra ID, you can set up SAML-based single sign-on (SSO) to allow teammates to access Ad Reform using their corporate account.

Before you begin

To set up SAML SSO, you'll need:

  1. SSO feature access — SSO is available on select plans. Contact us at support@adreform.com to enable SSO for your organization.

  2. A verified email domain — You must add and verify at least one email domain for your organization before configuring SAML SSO. This ensures only users with authorized email addresses can sign in via SSO. See Setting up a domain for SSO for instructions.

  3. Identity provider administrator access — You'll need admin access to your identity provider (Okta, Google Workspace, Microsoft Entra ID, etc.) to create and configure the SAML application.

What is SAML SSO?

SAML (Security Assertion Markup Language) is a standard protocol that allows your identity provider to authenticate users and grant them access to Ad Reform. This means your teammates can sign in with their existing work credentials without managing a separate password for Ad Reform.

Supported Identity Providers

Ad Reform's SAML SSO works with any SAML 2.0 compliant identity provider. We provide detailed setup instructions for:

  • Okta

  • Google Workspace

  • Microsoft Entra ID (Azure AD) via SAML

Using a different identity provider? Ad Reform supports any SAML 2.0 compliant provider. If you need help configuring a provider not listed above, please contact our support team at support@adreform.com.
​
​Note: If your team uses Microsoft Entra ID with OAuth, you may prefer our native Entra ID integration instead.

Setting up SAML SSO

Step 1: Access your SSO settings

  1. Navigate to your Organization Settings

  2. Go to the SSO or Authentication tab

  3. Click Add SAML Configuration

Step 2: Configure Ad Reform in your identity provider

You'll need to create a new SAML application in your identity provider. Here's what you'll need from Ad Reform:

Copy these values from Ad Reform:

  • SP Entity ID - A unique identifier for Ad Reform

  • Assertion Consumer Service (ACS) URL - Where your IdP should send authentication responses

  • SP Metadata URL (optional) - Some providers can import this automatically

⚠️ Your identity provider must be configured to send email addresses as the Name ID (NameID). This is not optional - Ad Reform uses the NameID as the primary identifier for user authentication. Non-email NameIDs (such as UUIDs, usernames, or persistent identifiers) will be rejected with an error.

The NameID setting varies by provider:

  • Okta: Set Name ID format to "EmailAddress" and Application username to "Email"

  • Google Workspace: Set Name ID format to "EMAIL"

  • Microsoft Entra ID: Ensure Name ID claim is set to user.mail

  • Other providers: Contact support@adreform.com for configuration guidance

Why this matters: Ad Reform uses the NameID from your SAML response as both the user identifier and email address. This approach ensures reliable user authentication and enables proper email domain validation for your organization. If your IdP sends a non-email NameID (like a UUID or username), authentication will fail with the error: "Invalid email address received from identity provider."

Configure your identity provider

For Okta:

  1. In Okta admin, go to Applications → Create App Integration

  2. Choose SAML 2.0

  3. Enter "Ad Reform" as the app name

  4. Paste the ACS URL from Ad Reform into Single sign on URL

  5. Paste the SP Entity ID from Ad Reform into Audience URI (SP Entity ID)

  6. Set Name ID format to "EmailAddress" (critical - this becomes the user's identifier in Ad Reform)

  7. Set Application username to "Email" (ensures the email address is sent as NameID)

  8. Save and assign users/groups to the application

  9. From the Sign On tab, copy the Metadata URL

Critical: The NameID format must be EmailAddress and Application username must be Email. Ad Reform treats the NameID as both the unique user identifier and the user's email address.

For Google Workspace:

  1. In Google Admin, go to Apps → Web and mobile apps

  2. Click Add app → Add custom SAML app

  3. Enter "Ad Reform" as the app name

  4. Download or copy the IdP metadata

  5. Paste the ACS URL from Ad Reform

  6. Paste the SP Entity ID from Ad Reform

  7. Set Name ID format to "EMAIL" (critical - this becomes the user's identifier)

  8. Save and assign users/groups

  9. Copy the metadata XML or SSO URL

For Microsoft Entra ID:

  1. In Azure AD, go to Enterprise Applications → New Application

  2. Click Create your own application, name it "Ad Reform"

  3. Under Single sign-on, select SAML

  4. Paste the SP Entity ID into Identifier (Entity ID)

  5. Paste the ACS URL into Reply URL

  6. Under Attributes & Claims, ensure the Name ID claim is set to user.mail (critical - this becomes the user's identifier)

  7. Download the Certificate (Base64)

  8. Copy the Login URL

  9. Assign users/groups to the application

Critical: The NameID claim must be configured to send the user's email address (user.mail). Ad Reform uses this as both the unique identifier and email address for the user.

Step 3: Complete configuration in Ad Reform

Return to Ad Reform's SAML configuration form:

  1. Name: Give your configuration a friendly name (e.g., "Okta Production")

  2. Vendor: Select your identity provider from the dropdown

  3. Metadata: Either:

    • Paste the Metadata URL from your IdP, OR

    • Paste the Metadata XML directly

  4. Status: Set to Enabled to activate this configuration

  5. Click Save

Ad Reform will automatically parse your IdP's metadata and configure the connection.

Just-in-Time Provisioning

Ad Reform supports Just-in-Time (JIT) provisioning, which means users are automatically created in Ad Reform when they sign in via SAML for the first time. This eliminates the need to manually create user accounts before teammates can access Ad Reform.

How JIT provisioning works

  1. First sign-in: When a user signs in via SAML for the first time:

    • Ad Reform creates a new user account using the email address from the NameID

    • The user is automatically added to your organization as a member

    • If there's a pending invitation for that email address, the user will be added with the invitation's role instead

  2. Subsequent sign-ins: When the same user signs in again:

    • Ad Reform recognizes them by their NameID and signs them into their existing account

    • No new account is created

Important considerations

  • Email domain validation: JIT provisioning respects your SAML configuration's allowed email domains. Users can only be automatically created if their email domain is authorized for your organization.

  • Email addresses are only synced during account creation: Ad Reform uses the email address from the NameID to create your account during first-time SAML sign-in. After your account is created, your email address in Ad Reform becomes the source of truth. If your email address changes in your identity provider after your account has been created, Ad Reform will treat the new email as a different user and create a new account. To avoid duplicate accounts, update your email address in Ad Reform directly, or contact your organization administrator to update it for you.

  • Name and profile information: Ad Reform extracts first name and last name from SAML attributes during account creation (if provided by your identity provider). Other profile information like job title is not automatically synced. After account creation, name fields are not updated from subsequent SAML logins.

  • Role assignment: New users are added as members by default. To give users different roles (like admin or owner), you can either:

    • Send them an invitation with the desired role before they sign in via SAML

    • Update their role in Ad Reform after they've signed in

Managing JIT provisioned users

Users created through JIT provisioning appear in your organization's Members section, where you can:

  • Update their roles and permissions

  • View their sign-in activity

  • Remove them from the organization if needed

Step 4: Test the connection

Before requiring SSO for your team:

  1. Open an incognito/private browser window

  2. Go to https://app.adreform.com/sso

  3. Enter your work email address

  4. You should be redirected to your identity provider

  5. Sign in with your corporate credentials

  6. You should be redirected back to Ad Reform, signed in

Requiring SSO for increased access control

Once configured and tested, you can optionally choose to require SSO, which means your team can only access Ad Reform by signing in via your identity provider. This can be helpful for larger teams who want additional access controls.

To make SSO required:

  1. Go to your SAML configuration

  2. Check the Force SSO Login option

  3. Save your changes

Important: Once required, any teammate who tries to log in with a password will be prompted to use SSO instead. Make sure all teammates have been added to your IdP application before enabling this option.

Using SSO to sign in

Once SAML SSO is configured, teammates can sign in two ways:

Option 1: Email-based SSO login (Recommended)

  1. Go to https://app.adreform.com/sso

  2. Enter your work email address

  3. Click Continue with SSO

  4. You'll be redirected to your identity provider

  5. Sign in with your corporate credentials

Option 2: Identity provider initiated login

If your IdP supports it, teammates can also sign in by:

  1. Opening their IdP portal (e.g., Okta dashboard)

  2. Clicking on the Ad Reform application tile

Managing your SAML configuration

Viewing configuration details

From your SAML configuration page, you can:

  • View connection status and metadata

  • See which teammates have signed in via SSO

  • Copy SP Entity ID and ACS URL for IdP updates

  • View the last time the configuration was modified

Updating your configuration

To update your SAML settings:

  1. Go to your SAML configuration

  2. Click Edit

  3. Make your changes (update metadata, change name, etc.)

  4. Click Save

Changes take effect immediately.

Disabling or removing SAML SSO

To temporarily disable SAML SSO:

  1. Go to your SAML configuration

  2. Change Status to Disabled

  3. Save

To permanently remove SAML SSO:

  1. Go to your SAML configuration

  2. First, uncheck Force SSO Login if enabled

  3. Click Delete Configuration

  4. Confirm deletion

Warning: Deleting a configuration will remove all associated authentication records. Teammates will need to sign in with their password or set up a new SSO method.

Troubleshooting

"Your email domain is not authorized for SSO access"

  • Your email domain hasn't been added or verified for this organization

  • Contact your organization administrator to add your email domain

  • See Setting up a domain for SSO for more information

"SAML configuration not found"

  • Make sure your configuration is Enabled in Ad Reform

  • Verify you're using the correct work email address

  • Check that your email domain is verified for the organization

  • Check that you're part of the correct organization

"SSO not enabled" or "User not found"

  • Ensure you've been assigned to the Ad Reform application in your identity provider

  • Verify your email address in your IdP matches your Ad Reform account email

  • Contact your organization administrator to be added to the application

"Invalid SAML response"

  • Check that your IdP's metadata is up to date in Ad Reform

  • Verify the SP Entity ID and ACS URL are correctly configured in your IdP

  • Ensure the IdP certificate hasn't expired

  • Check your IdP's logs for specific error messages

"Invalid email address received from identity provider"

If you see this error when signing in:

  • This means your IdP is sending a non-email NameID (such as a UUID, username, or persistent identifier)

  • Fix: Update your IdP configuration to send email addresses as the NameID:

    • Okta: Set Name ID format to "EmailAddress" and Application username to "Email"

    • Google Workspace: Set Name ID format to "EMAIL"

    • Microsoft Entra ID: Set Name ID claim to user.mail (not user.userPrincipalName or other attributes)

    • Other providers: Contact support@adreform.com for configuration guidance

  • After updating your IdP configuration, test the connection again

  • If you continue to see this error, verify that your IdP's metadata reflects the email NameID format

Clock synchronization errors

If you see errors about timestamps:

  • This usually indicates a clock difference between your IdP and Ad Reform's servers

  • Contact Ad Reform support - we may need to adjust clock drift tolerance

Multiple configurations

Organizations can configure multiple SAML providers, but only one can be active at a time. This can be useful for:

  • Testing a new IdP before switching

  • Maintaining separate configurations for different environments

  • Having a backup configuration ready

To switch between configurations:

  1. Disable the currently active configuration

  2. Enable the configuration you want to use

Security considerations

  • SAML responses are cryptographically signed and validated

  • All connections use HTTPS/TLS encryption

  • When Force SSO Login is enabled, password-based authentication is blocked for your organization

  • IdP administrators control which teammates can access Ad Reform

  • Authentication sessions respect your IdP's session timeout policies

Frequently Asked Questions

What happens to existing Ad Reform accounts after SAML SSO is enabled?

If you already have an Ad Reform account before SAML SSO is enabled, you can continue signing in with both your password and via SSO. Your existing account will be linked to your SSO identity when you first sign in via SAML, provided the email address from your identity provider matches your Ad Reform account email.

If your organization enables Force SSO Login, you'll need to use SSO exclusively to access Ad Reform.

Can I change my email address after my account is linked to SAML?

Yes, but it's important to update your email in Ad Reform first before changing it in your identity provider. Here's why:

Ad Reform uses the email address from the SAML NameID to identify you during sign-in. If you change your email in your identity provider without updating it in Ad Reform first, the system will see the new email as a different user and create a duplicate account.

To safely change your email:

  1. Update your email address in your Ad Reform account settings first

  2. Then update it in your identity provider

  3. Or contact your organization administrator to update it for you

Can teammates be restricted to only logging in via SAML SSO?

Yes! You can enable the Force SSO Login option in your SAML configuration. When enabled, teammates must sign in via your identity provider and cannot use password-based authentication.

Before enabling this:

  • Make sure SAML SSO is working correctly by testing it

  • Ensure all teammates have been assigned to the Ad Reform application in your identity provider

  • Consider informing your team about the change

What happens if my organization changes its email domain?

Changing your organization's email domain requires coordination between your identity provider and Ad Reform:

  1. Add the new domain: Add your new email domain in Ad Reform and request verification (see Setting up a domain for SSO)

  2. Before changing the domain: All teammates should update their email address in Ad Reform to use the new domain

  3. Update your identity provider: Configure your IdP to use the new domain

  4. Remove the old domain (optional): Once all users have migrated, you can remove the old domain from Ad Reform

Important: Changing the domain in your IdP before adding it to Ad Reform can lock teammates out or create duplicate accounts.

I need to disable SAML SSO or switch to another identity provider. What should I do?

To temporarily disable SAML:

  1. Go to your SAML configuration in Organization Settings

  2. First, disable Force SSO Login if it's enabled

  3. Set the configuration Status to Disabled

  4. Save your changes

Teammates will be able to sign in with their passwords after this. Anyone who only ever used SAML (and never set a password) will need to use the "Forgot password" flow to create one.

To switch to a different identity provider:

  1. Disable Force SSO Login on your current configuration

  2. Keep the current configuration enabled while you set up the new one

  3. Create a new SAML configuration for your new identity provider

  4. Test the new configuration thoroughly

  5. Once confirmed working, disable the old configuration and enable the new one

What should I do when my SAML SSO certificate expires?

If your identity provider's SAML certificate is about to expire:

  1. Before the certificate expires:

    • Disable Force SSO Login in your Ad Reform SAML configuration (to prevent lockouts)

    • Generate a new certificate in your identity provider

    • Download the updated metadata (XML or URL)

    • Update your SAML configuration in Ad Reform with the new metadata

    • Test the connection to ensure it works

    • Re-enable Force SSO Login if desired

  2. If the certificate has already expired:

    • Teammates won't be able to sign in via SSO

    • They can sign in with passwords if Force SSO Login is disabled

    • Follow the steps above to update the certificate

    • Contact support@adreform.com if you need assistance

Can I have multiple SAML configurations?

Yes, you can create multiple SAML configurations (useful for testing or switching providers), but only one can be active at a time.

To switch between configurations:

  1. Set your current active configuration to Disabled

  2. Set the configuration you want to use to Enabled

All existing user sessions will remain active when you switch configurations.

What happens if I rename my organization?

Renaming your organization in Ad Reform does not affect your SAML SSO configuration. All connections, metadata URLs, and authentication will continue to work as before.

How does Ad Reform handle session expirations for SAML SSO?

Ad Reform respects the session timeout policies configured in your identity provider. When your IdP session expires, you'll need to re-authenticate through your identity provider to continue using Ad Reform.

For the best experience, ensure your identity provider's session timeout is configured appropriately for your team's security requirements.

Can I add guests or external collaborators after SAML SSO is enabled?

Yes! Even with SAML SSO enabled, you can still invite external users or guests who don't have accounts in your identity provider. They'll be able to sign in with their email and password.

However, if you've enabled Force SSO Login, only users with email addresses from your verified domains can access Ad Reform. Users with email addresses outside your allowed domains will be unable to sign in.

What happens if I delete a SAML configuration?

Deleting a SAML configuration will:

  • Remove all SAML authentication settings

  • Remove the association between your IdP and Ad Reform

  • Not delete user accounts - teammates will still exist in Ad Reform

  • Require teammates to sign in with their passwords (or reset their password if they never set one)

Before deleting a configuration:

  1. Make sure Force SSO Login is disabled

  2. Inform your team that they'll need to use password authentication

  3. Consider disabling the configuration first to test the impact before permanently deleting it

Need help?

If you're having trouble setting up SAML SSO or have questions about which authentication method is right for your team, please contact our support team at support@adreform.com.

Related Articles
Using Microsoft Entra ID for single sign-on (SSO)
Did this answer your question?