Skip to content
BILLETKnowledge Base

Create a tenant and connect single sign-on

Create the organization people belong to, connect it to your identity provider over SAML 2.0, and optionally provision people automatically with SCIM.

For
Administrators
Applies to
Billet 1.0
Updated

A tenant is the boundary everything else sits inside: its own people, desktops and settings. People in one tenant cannot see or reach another tenant's desktops.

People sign in through your organization's identity provider over SAML 2.0. Billet never sees their passwords. Each tenant can have more than one sign-on connection, for example one per directory.

1. Create the tenant

  1. In the console, open Tenants and choose Create a tenant.
  2. Fill in:
    • Id: letters, digits, hyphens and underscores, for example acme. It is recorded in every audit entry and every desktop's credential, so it cannot be changed afterwards.
    • Name: what people see, for example Acme Corporation.
    • Address: optional. What names the tenant in its own host name, and what its people may type for their organization. Left empty, one is made from the name. It can be changed later.
    • Host enrollment secret: required. What a desktop presents to join this tenant. Use a long random value, for example from openssl rand -hex 24. It is stored and never shown again.
  3. Press Create tenant.

2. Add a sign-on connection

  1. Open Settings for the tenant, find Single sign-on, and choose to add a connection.
  2. Choose your Provider: Microsoft Entra ID, Okta, Google Workspace, or Another SAML provider.
  3. Fill in:
    • Name: on the button people press to sign in, for example Acme staff.
    • Email domains: optional, for example acme.com, acme.co.uk. Someone who types an address at one of these is shown this connection first.
    • Short id: part of the addresses your provider is given, so it cannot be changed afterwards. Lower-case letters, digits and dashes.
  4. Press Add connection.

3. Set up the application at your provider

The connection's page lists, under Give these to your provider, everything your identity provider asks for, and steps for the provider you chose:

The connection's page says Your provider may call it
Entity id Identifier, Audience URI, Entity ID
Reply address ACS URL, Single sign-on URL
Sign-in address Sign on URL, Start URL
Sign-out address Logout URL, Single Logout URL

It also offers This connection's metadata to download, if your provider takes a metadata file instead.

In short, for each provider:

  • Microsoft Entra ID: Enterprise applications, New application, Create your own application (not in the gallery), then set up SAML single sign-on with the addresses above. Copy the App Federation Metadata Url back to Billet. Billet fetches it now and every six hours, so a certificate Entra rolls over is followed. Assign the people who may sign in under Users and groups.
  • Okta: Applications, Create App Integration, SAML 2.0. The reply address goes in Single sign-on URL (and Recipient and Destination), the entity id in Audience URI, and Name ID format is EmailAddress. Copy the Metadata URL from the Sign On tab back to Billet. Assign the people who may sign in.
  • Google Workspace: Apps, Web and mobile apps, Add app, Add custom SAML app. Download Google's metadata file and paste it into Billet. Name ID format is EMAIL, from Primary email. Google has no single sign-out for these apps, and does not provision custom SAML apps with SCIM.
  • Another provider: give it the metadata address, or the entity id, the reply address (HTTP-POST) and the sign-out address (HTTP-Redirect). Have it send the person's email address in the attribute the page names (or as the NameID), and sign the assertion or the response with SHA-256.

Then, under From your provider, give Billet your provider's metadata address, or paste its metadata, or its entity id, sign-in address, sign-out address and signing certificate.

Note: If the connection's page says the portal does not know its own public address, set BILLET_PUBLIC_HOST in the portal's service. See Install the portal.

4. Provision people automatically (optional)

With SCIM 2.0, your provider creates, updates and deactivates people in Billet itself. Billet takes users from SCIM; it does not take groups.

  1. On the connection's page, find Provisioning (SCIM) and press Make a token. It is shown once. Making another stops the old one.
  2. At your provider, set up SCIM provisioning with the connection's Provisioning (SCIM) address and that token.

A person's username is their email address.

Without SCIM, you can still assign a desktop to someone by their sign-in address before they first sign in.

5. Try it

Open https://portal.example.com/portal, choose your organization, and sign in with the new connection. Then assign a desktop to yourself and connect.

Tenant administrators

To let someone manage just this tenant, create them as a tenant_admin for it. See Roles. A tenant administrator signs in at the people's page (/portal) and is taken to their tenant's console.