Build in Single-Sign-On (SSO) with Piezas

"Single sign-on" (SSO) lets people sign in to your app with an account they already have: Google, Apple, or their company's Microsoft account. No new password to remember, and for business apps, staff use the work account their IT team already manages.

This article explains how it works on Piezas and walks you through each provider. You do two kinds of work yourself: get a few IDs from the provider (Google, Apple or Microsoft), and save them as your app's private settings on Piezas. Your AI tool does the rest.

How it works

• Piezas holds your app's user accounts and runs your app. Each person who signs in gets an account in your app on Piezas, the same as people who sign up with an email and password.
• Your app does the "handshake" with the provider. When someone clicks "Sign in with Microsoft" (or Google, or Apple), they're sent to that provider, sign in there, and come back to your app with proof of who they are. A small piece of your app's server code checks that proof and signs them in. Your AI tool writes that code for you, following the Piezas rules.
• The provider's IDs and secrets live in your app's private settings on Piezas, never in your app's code and never in the AI chat.

Before you start

• A Piezas app, deployed at least once, so you know its address, for example https://your-app.apps.piezas.ai. Providers need this address.
• Access to the provider's console:
  • Google: a Google account that can use Google Cloud Console.
  • Apple: a paid Apple Developer account.
  • Microsoft: an administrator of your organization's Microsoft Entra ID (formerly Azure Active Directory), or someone who can register apps there.
• A privacy policy page for your app. Google and Apple ask for its address.

Step 1: Ask your AI tool to add sign-in

Start here, so you know the exact addresses to give each provider. In your app's folder, tell your AI tool, for example:

Add "Sign in with Google" and "Sign in with Microsoft" to this app using Piezas. Tell me the redirect address I need to give each provider, and the names of the settings I need to set.

It will add the sign-in buttons and the server code, and tell you:

• the redirect address for each provider. It usually looks like https://your-app.apps.piezas.ai/auth/google/callback or https://your-app.apps.piezas.ai/auth/entra/callback. Use exactly what it gives you.
• the setting names it expects, for example ENTRA_CLIENT_ID.

Step 2: Get the IDs from your provider

Google

1. Open Google Cloud Console and create a project for your app (or pick an existing one).

2. Go to APIs & Services → OAuth consent screen. Choose External (anyone with a Google account) or Internal (only your Google Workspace organization). Enter your app's name, support email and privacy policy address. Add the scopes email and profile (and openid).

3. Go to APIs & Services → Credentials → Create credentials → OAuth client ID. Choose Web application.

4. Under Authorized redirect URIs, paste the Google redirect address from Step 1, exactly.

5. Click Create. Copy the Client ID and the Client secret.

Values to save on Piezas: the Client ID and the Client secret (use the setting names your AI tool gave you, for example GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET).

For an iPhone or iPad app, Google uses an iOS client type instead of Web application, and there is no client secret. Tell your AI tool it's an iOS app.

Apple

Sign in with Apple needs a paid Apple Developer account.

1. In Apple Developer → Certificates, Identifiers & Profiles → Identifiers, open your app's identifier (or create one) and turn on Sign in with Apple.

2. For a website, also create a Services ID (this becomes the ID your web app signs in with). Under its Sign in with Apple settings, add your app's domain (for example your-app.apps.piezas.ai) and the Apple redirect address from Step 1.

3. Go to Keys, create a key with Sign in with Apple turned on, and download the key file (.p8). Apple lets you download it only once, so keep it safe.

4. Note the Key ID (shown with the key) and your Team ID (top right of the developer site, or under Membership).

Values to save on Piezas: the Key ID, the Team ID, the contents of the .p8 key file, and the Services ID (website) or your app's bundle ID (iPhone/iPad app).

If your app is on the App Store and offers Sign in with Apple, Apple requires that deleting an account also revokes the person's Apple sign-in. Ask your AI tool to include this; it uses the same key.

Microsoft Entra ID (company accounts)

1. In the Microsoft Entra admin center, go to Identity → Applications → App registrations → New registration.

2. Enter a name. Under Supported account types, choose Accounts in this organizational directory only for staff of one organization.

3. Under Redirect URI, choose the platform Web (not "Single-page application") and paste the Microsoft redirect address from Step 1. Click Register.

4. On the app's Overview page, copy the Application (client) ID and the Directory (tenant) ID.

5. Go to Certificates & secrets → New client secret. Choose an expiry, click Add, and copy the secret's Value right away (it's shown only once).

Values to save on Piezas: the Application (client) ID, the Directory (tenant) ID and the client secret value (for example ENTRA_CLIENT_ID, ENTRA_TENANT_ID, ENTRA_CLIENT_SECRET).

Who can get in. Being in your organization's directory isn't always enough. Apps built on Piezas can keep a list of which staff may sign in and what each person can do; people not on the list are refused. Tell your AI tool who should have access.

Step 3: Save the values on Piezas

Secrets go in your app's private settings, never into the AI chat. The Piezas extension stops pasted keys before the AI sees them.

Two ways to save them:

• In the Piezas console: open your app at app.piezas.ai → Hosting → Environment, and add each setting with the name your AI tool gave you. [Screenshot: Piezas console → app → Hosting → Environment]
• In your own terminal: npx piezas env set ENTRA_CLIENT_ID=... (one setting at a time).

Then ask your AI tool to deploy the app again so it picks up the new settings.

Step 4: Test it

1. Open your app's address and click the new sign-in button.
2. Sign in with the provider. You should come back to your app, signed in.
3. Try an account that shouldn't get in (for example, someone outside your organization, or not on your list) and check it's refused.

If something doesn't work

• "redirect_uri_mismatch" or "The reply URL does not match": the redirect address saved at the provider must match your app's exactly, including https:// and the path. Copy it again from your AI tool.
• Microsoft says the account isn't allowed: check Supported account types, and that the person is in your directory and on your app's access list.
• Sign-in stopped working after months: a Microsoft client secret expires on the date you chose. Create a new one and update the setting.
• Apple sign-in fails after you made a new key: update the Key ID and the .p8 contents in your settings.
• The sign-in button doesn't appear: the app hides a provider until its settings are saved. Check the setting names and deploy again.
• Anything else: email support@piezas.ai with your app's name and what you saw.