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

1. Sign in to your Square Dashboard and go to Settings > Account & Settings > My business > Security. 

2. Click Set up under Identity provider

3. 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

4. Follow the instructions to Verify your domain(s) with a TXT record. 

5. Add the TXT record via your DNS provider and return to Square to initiate verification. Confirm the verification status is Verified.

   1. If verification fails, ensure the TXT record was applied, and periodically attempt verification as replication may take up to 72 hours

6. Select which businesses you want to manage with this identity provider. This does not automatically turn on SSO for these businesses. 

7. 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

1. Sign in to your Square Dashboard and go to Account & Settings > Business > Security 

2. Click Set up under Single Sign On

3. Follow the instructions shown on squareup.com to connect single sign on to your identity provider

4. Enable SSO for individual accounts

   1. 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.

   2. When you enable single-sign on as Required, it will only allow the account to sign-in with SSO.

5. 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

6. Select which businesses to turn on Single Sign-On for. You can select from the businesses you configured the identity provider to manage.

7. 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