Set up Enterprise SSO with OIDC

About Enterprise SSO with OIDC

Enterprise SSO allows your organisation to use your existing identity provider to authenticate users across all your Square businesses. The Square implementation supports service provider (SP)-initiated SSO and identity provider (IDP)-initiated SSO.

When you turn SSO on for a business, it automatically applies to all users on your verified domains for that business. This ensures consistent authentication policies across your organisation while maintaining centralised user management in your identity provider.

Before you begin

You have two 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 in to your identity providers:. 

• Domain ownership verification capabilities (DNS access or email admin access).

• The Manage Single Sign-On permission on all Square businesses that you want to turn single sign-on on for. If you have full access or are the account owner, you’ll have this automatically for that business. The account owner of each business can invite you to the Square business and give you this permission.

Important: When you turn SSO on for a business, this automatically applies SSO to all people on your verified domains who have access to that business. Turning SSO on also removes login phone numbers from all accounts on your verified domains, and passwords and passkeys from SSO-only accounts. Plan your rollout accordingly and make sure your identity provider is properly configured before turning single sign-on on. You will have the ability to test SSO with individual accounts before turning it on for the entire business.

Step 1: Configure your identity provider in Square Dashboard

You can configure this from the Square Dashboard of any business. You will be able to select whether this applies to just this business or all your businesses in Step 2.

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, make sure the TXT record was applied and periodically attempt verification again. Replication can take up to 72 hours.

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

7. Once your identity provider is ‘Active’, you can move on to turning SSO on for your business.

Step 2: Set up and enable SSO for your business

What changes when you turn SSO on

When you turn SSO on for a business, these sign-in methods change for accounts on your verified domains to make sure that the account follows the expected authentication methods:

Removed sign-in methods don’t come back if you turn SSO off.

Before you turn SSO on for an entire business: Set your break-glass accounts (backup accounts that can sign in if SSO fails) by configuring SSO as Optional to allow SSO or password sign-in. Confirm each one can sign in with its password or passkey.

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

2. Click Set up under Single Sign-On.

3. Follow the onscreen instructions to connect single sign-on to your identity provider.

4. Turn SSO on for individual accounts.

   1. When you set an account to Optional, it allows 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 set an account to Required, it only allows 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 drop-down menu.

6. Select which businesses to turn Single Sign-On on for. You can choose from the businesses your identity provider manages.

7. Select which individual accounts should have Optional single sign-on. This overrides the business-wide setting. These will be your break-glass accounts.

Important: Once Single Sign-On is turned on 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 sign in.

Setup will not automatically log accounts out. Once setup steps are complete, the next time an account with SSO Required enters their email address on the Square sign-in page, they will be redirected to the identity provider to sign in.

Step 3. Sign in via SP-initiated SSO

All accounts and users on businesses with SSO turned on will now be able to sign in with Single Sign-On across Square Dashboard and Point of Sale.  Device code and passcode sign-ins are not impacted.

Each sign-in surface reacts differently to SSO:

1. Navigate to https://app.squareup.com/login.

2. Enter your email and click Continue.

   1. Click Sign in with SSO if the account is set to Optional.

Best practices

Enable two-factor authentication

• Okta users: Turn multi-factor authentication (MFA) policies on in your Okta admin console for all users accessing Square.

• MicrosoftEntra ID users: Turn Azure AD Multi-Factor Authentication on 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

You can set up break-glass accounts by turning single sign-on on as Optional for individual accounts. Refer to Step 2 to configure this.

• 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 turning Single Sign-On on for, are good candidates for break-glass accounts.

Test before full roll-out

• Start with a pilot group of users.

• Test Single Sign-On access across different Square applications: Dashboard, Point of Sale, Square iOS and Android apps.

• Enter a SSO Required account’s email on the web sign-in page. Confirm it redirects to your identity provider.

• Verify that user permissions and roles are maintained after SSO sign-in.

• Confirm that break-glass accounts work as expected, including sign-in with their password or passkey.

• Confirm that device code sign-in still works on the devices your team use.

When a premium plan for any Square product subscription lapses

A premium plan for any Square product is required for SSO. If a business’s subscription lapses:

1. SSO turns off for that business straight away.

2. Accounts go back to Square sign-in. Required accounts no longer have to use your identity provider.

3. Required accounts had their passwords removed when you turned SSO on. After the subscription lapses, they can sign in with a one-time code sent to their email. They’ll then be asked to add a password.

4. Passkeys and login phone numbers don’t come back. Add them again.

Troubleshoot common issues

Domain verification fails

Problem: Domain verification is not completing successfully

Solutions:

• DNS method: Make sure 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

Users cannot sign in after turning Single Sign-On on

Problem: Users receive errors when trying to sign in to Square

Solutions:

• Domain mismatch: Make sure users’ email addresses match your verified domains 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

An SSO Required account can’t sign in with a password

Problem: An SSO Required account’s password doesn’t work on the Square sign-in page

Solutions:

• Expected behaviour: SSO removes passwords from Required accounts. Sign in through your identity provider instead.

• SSO turned off: Sign in with a one-time code sent to your email. You’ll then be asked to add a password.

Single Sign-On not working across all businesses

Problem: Single sign-on settings don’t apply consistently across multiple businesses

Solutions:

• Business linking: Make sure 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