Single sign-on

On Early access and the Business plan, members of your workspace can sign in to the Houseguest™ console through your identity provider instead of an emailed code. Houseguest supports OpenID Connect (OIDC) and SAML 2.0; both work with Okta, Microsoft Entra ID and Google Workspace. On Free and Pro, Settings › Single sign-on shows what the Business plan adds.

Single sign-on covers console members, and the people you share previews with whose address is in your domains (Preview viewers). Guests from other companies keep signing in with an emailed code.

Before you start

• A verified domain. Single sign-on applies to addresses in your company’s email domain, for example acme.com. The workspace must own that domain: add it on Domains & addresses and create its TXT record (see Domains and addresses). A verified domain also covers the names under it, so verifying acme.com lets you add eng.acme.com too. Each domain can be used for single sign-on by one workspace.
• Permission. Setting up single sign-on needs Change security settings (Owners and Admins have it).
• One identity provider per workspace: OIDC or SAML.

Set it up

Open Settings › Security › Single sign-on settings (or go to /settings/sso in the console).

1. Identity provider. Choose OpenID Connect or SAML 2.0, and copy the values shown there into your identity provider (steps for Okta, Microsoft Entra ID and Google Workspace below). Then enter what the identity provider gives you back and save:
   • OIDC: the issuer URL, client ID and client secret.
   • SAML: the identity provider’s metadata URL, or its metadata file (XML).
2. Domains. Add your email domains, for example acme.com. Each shows Domain verified once the workspace owns it.
3. Test sign-in. Click Test sign-in and sign in at the identity provider. The test checks the whole round trip and opens no session. It must pass before single sign-on can be turned on, and again after you change the identity provider.
4. Sign-in policy. Turn on Single sign-on, and choose:
   • Require SSO: members in your domains can only sign in through the identity provider. Email codes and passkeys stop for them, including sessions already open. Owners are the exception (see below).
   • Just-in-time membership: someone your identity provider signs in who is not yet a member joins the workspace with the role you choose (Member, Auditor or No workspace role). Owner and Admin are always granted by hand. Off: only people you invited get in. New members count against your seats.

Every change, test and single sign-on sign-in is recorded in the activity log.

How members sign in

On the sign-in page, members enter their work address and choose Sign in with single sign-on. If they choose Email me a code with an address in your domains, the page offers single sign-on first; while it is optional, Email me a code instead is still there.

Someone signed in through your identity provider is not asked for Houseguest’s second sign-in step in your workspace: your identity provider’s own multi-factor authentication applies. Configure it there.

Preview viewers

When someone opens one of your workspace’s previews and enters an address in your single sign-on domains, the preview’s sign-in page offers Continue with single sign-on instead of sending a code. The same applies to an invite link sent to such an address. Nothing extra is registered in your identity provider: whatever the preview’s hostname, the sign-in goes through the console’s own redirect URI or ACS URL, and comes back to the preview a moment later.

Single sign-on proves who the person is; the preview still decides who gets in. Someone your identity provider signs in who is not on the preview’s list, or holds no invite to it, is refused, and the refusal is in the activity log.

• While single sign-on is optional, viewers can choose Email me a code instead.
• With Require SSO on, viewers in your domains sign in to your previews through your identity provider only: no email codes, and invite links sent to them open the preview only after single sign-on (also for previews that skip the code). Guests outside your domains are unaffected. Viewers already signed in by code stay signed in until their session ends.
• Viewer sign-ins through single sign-on, and refusals, are in the activity log and in each preview’s request log.

Sign in with Microsoft

The console’s sign-in page and preview sign-in pages also offer Sign in with Microsoft, on every plan. It is not single sign-on: Houseguest’s own Microsoft registration proves the person’s email address, as an emailed code does, and nothing more.

• Existing accounts only. It signs in the account with that address; it never creates one.
• The address must be confirmed by Microsoft: any personal Microsoft account, or a work or school account whose organization owns the address’s domain. Otherwise the page points to the email code.
• Your second sign-in step still applies. Members with a passkey or an authenticator app are asked for it after Microsoft, as after a code.
• Require SSO wins. For addresses in your single sign-on domains, Require SSO refuses Microsoft as it refuses codes (Owners keep it as they keep the code). While single sign-on is optional, Microsoft works like the code.
• Sign-ins and refusals are in the activity log as Microsoft.

If the identity provider is down: owners keep a way in

When Require SSO is on, Owners of the workspace can still sign in with an emailed code, followed by their second sign-in step: on the sign-in page, open Owner without access to the identity provider and choose Email an owner code. Members get no code that way. Make sure at least one Owner has a passkey or an authenticator app.

If every Owner is locked out, contact Houseguest support: support can turn single sign-on off for the workspace, and your setup is kept.

Okta

OIDC

1. In the Okta Admin Console: Applications › Create App Integration, sign-in method OIDC - OpenID Connect, application type Web Application.
2. Grant type: Authorization Code. Sign-in redirect URI: the Redirect URI shown in Houseguest (https://console.houseguest.dev/sso/oidc/callback).
3. Assign the people or groups who use Houseguest.
4. In Houseguest, enter the issuer URL (your Okta domain, for example https://acme.okta.com, or your authorization server’s issuer, such as https://acme.okta.com/oauth2/default), the client ID and the client secret.

SAML

1. Applications › Create App Integration › SAML 2.0.
2. Single sign-on URL: the ACS URL from Houseguest. Audience URI (SP Entity ID): the Entity ID. Name ID format: EmailAddress. Application username: Email.
3. Assign people or groups. On the app’s Sign On tab, copy the Metadata URL into Houseguest.

Microsoft Entra ID

OIDC

1. In the Microsoft Entra admin center: App registrations › New registration. Supported account types: Accounts in this organizational directory only. Redirect URI: platform Web, the Redirect URI from Houseguest.
2. Certificates & secrets › New client secret; copy its value.
3. Token configuration › Add optional claim › ID › email, so the ID token carries the address.
4. In Houseguest, enter the issuer URL https://login.microsoftonline.com/<your tenant ID>/v2.0, the Application (client) ID and the secret.

SAML

1. Enterprise applications › New application › Create your own application (non-gallery).
2. Single sign-on › SAML. Identifier (Entity ID): the Entity ID from Houseguest. Reply URL (Assertion Consumer Service URL): the ACS URL. Leave Sign on URL empty, or use the console’s sign-in page.
3. Under Attributes & Claims, keep Unique User Identifier as user.mail (or user.userprincipalname when that is the address) with the email address name format.
4. Assign users or groups. Copy the App Federation Metadata Url into Houseguest.

Google Workspace

OIDC

1. In the Google Cloud console for your organization: APIs & Services › OAuth consent screen, user type Internal.
2. Credentials › Create credentials › OAuth client ID, type Web application. Authorized redirect URI: the Redirect URI from Houseguest.
3. In Houseguest, enter the issuer URL https://accounts.google.com, the client ID and the client secret. Only addresses in the domains you added can sign in.

SAML

1. In the Google Admin console: Apps › Web and mobile apps › Add app › Add custom SAML app.
2. Download the IdP metadata file (you upload it to Houseguest).
3. ACS URL: the ACS URL from Houseguest. Entity ID: the Entity ID. Name ID format: EMAIL, Name ID: Basic Information › Primary email.
4. Turn the app On for the organizational units that use Houseguest. Upload the metadata file in Houseguest.

Good to know

• Sign-in starts from Houseguest. An app tile in your identity provider’s dashboard should open the console’s sign-in page; sign-in started at the identity provider (IdP-initiated SAML) is refused.
• SAML responses or assertions must be signed. Houseguest does not sign its requests and does not take encrypted assertions.
• When your identity provider’s signing certificate changes, open Single sign-on and click Fetch metadata again (metadata from a URL), or upload the new file, then run the test again.
• Changing the identity provider turns single sign-on off until a new test passes. A new OIDC client secret alone does not.
• If your plan changes to one without single sign-on, the setup is kept and stops working: members sign in with emailed codes and passkeys until it is turned back on.
• Group claims and SCIM provisioning are not available yet; groups are managed in Houseguest.