Set up Enterprise SSO with OIDC
About Enterprise SSO with OIDC
Enterprise SSO allows your organization to use your existing identity provider to authenticate users across all your Square businesses. With OIDC (OpenID Connect), employees can sign in to Square using their corporate credentials, eliminating the need to manage separate Square passwords.
When you enable SSO for a business, it automatically applies to all users on your verified domains for that business. This ensures consistent authentication policies across your organization while maintaining centralized user management in your identity provider.
Before you begin
You have 2 options for Identity Providers:
Okta as your identity provider
Microsoft Entra ID (formerly Azure AD) as your identity provider
You also need:
Administrative access to your identity provider (Okta or Entra ID). Make sure you are signed into your Identity Provider.
Domain ownership verification capabilities (DNS access or email admin access).
The Manage Single Sign-On permission on all Square businesses that you want to enable single-sign on for. If you have Full Access or are the Account Owner, you’ll have this automatically for that business..
Important: When you turn on SSO for a business, this automatically enables SSO for all people on your verified domain who have access to that business. Plan your rollout accordingly and ensure your identity provider is properly configured before enabling Single Sign-On. You will have the ability to test SSO with single accounts before turning it on for the entire business.
Step 1: Configure your identity provider in Square Dashboard
Sign in to your Square Dashboard and go to Settings > Account & Settings > My business > Security.
Click Set up under Identity provider
Select Okta or Microsoft Entra ID and provide a name for this identity provider configuration. This name is only for your reference as you set this up
Follow the instructions to Verify your domain(s) with a TXT record.
-
Add the TXT record via your DNS provider and return to Square to initiate verification. Confirm the verification status is Verified.
If verification fails, ensure the TXT record was applied, and periodically attempt verification as replication may take up to 72 hours
Select which businesses you want to manage with this identity provider. This does not automatically turn on SSO for these businesses.
Once your Identity Provider is ‘Active’, you can move on to enabling SSO for your business.
Step 2: Set up and enable SSO for your business
Sign in to your Square Dashboard and go to Account & Settings > Business > Security
Click Set up under Single Sign On
Follow the instructions shown on squareup.com to connect single sign on to your identity provider
-
Enable SSO for individual accounts
When you enable single-sign on as Optional, it will allow the account to sign-in with SSO or traditional login methods. This overrides any business-wide setting, and can be used for Break-glass accounts.
When you enable single-sign on as Required, it will only allow the account to sign-in with SSO.
When you are ready to roll out single-sign on as Required to the whole business, select `Manage SSO for businesses` from the dropdown menu
Select which businesses to turn on Single Sign-On for. You can select from the businesses you configured the identity provider to manage.
Select which individual accounts should have Optional single-sign on, that overrides the business-wide setting. These will be your Break-glass accounts.
Important: Once Single Sign-On is enabled for a business, all users employed by that business with email addresses on your verified domains will be required to use Single Sign-On to login.
Set up will not automatically log accounts out. Once setup steps are complete, the next time an account with SSO Required log in, they will be redirected to the Identity Provider to sign in after entering their email address.
Best practices
Enable two-factor authentication
Okta users: Enable multi-factor authentication (MFA) policies in your Okta admin console for all users accessing Square.
Entra ID users: Enable Azure AD Multi-Factor Authentication for all users in your conditional access policies.
Strong authentication at the identity provider level is crucial since SSO bypasses Square's native login security.
Maintain break-glass access
Test break-glass account access regularly.
Document break-glass procedures for your IT team.
Store break-glass credentials securely and separately from your main systems.
Account Owner or Full Access accounts, who have access to all the businesses you’re enabling Single Sign-On for, are good candidates for Break Glass accounts.
Test before full rollout
Start with a pilot group of users.
Test Single Sign-On access across different Square applications (Dashboard, Point of Sale, etc.).
Verify that user permissions and roles are maintained after SSO login.
Confirm that break-glass accounts work as expected.
Troubleshoot common issues
Domain verification fails
Problem: Domain verification is not completing successfully
Solutions:
DNS method: Ensure the TXT record is added correctly to your domain's DNS settings. DNS propagation can take up to 72 hours
Multiple domains: If you have multiple domains, verify each one separately
Single Sign-On connection test fails
Problem: The "Test Connection" step fails during setup
Solutions:
Discovery URL: Verify the URL is correct and accessible from the internet
Client credentials: Double-check that the Client ID and Client Secret are copied correctly with no extra spaces
Application settings: Ensure your OIDC application is configured with all required redirect URIs (both web and mobile app callbacks)
PKCE requirement: Verify that PKCE is enabled in your identity provider application settings
Network access: Ensure your identity provider and users can reach Square's authentication endpoints
Users cannot sign in after enabling Single Sign-On
Problem: Users receive errors when trying to sign in to Square
Solutions:
Domain mismatch: Ensure users' email addresses match your verified domain exactly
User assignment: Check that users are assigned to the OIDC application in your identity provider
Account status: Verify that user accounts are active in your identity provider
Browser issues: Clear browser cache and cookies, or try an incognito/private browsing session
Application permissions: Ensure the OIDC application has the necessary permissions to read user profile information
Single-sign on not working across all businesses
Problem: Single Sign-On settings don't apply consistently across multiple businesses
Solutions:
Business linking: Ensure all businesses are properly set up in the identity provider settings and Single Sign-On settings from Square Dashboard
Domain verification: Verify that all domains used are verified from Square dashboard
Propagation time: Allow up to 30 minutes for Single Sign-On settings to propagate across all businesses