Connect your identity provider so everyone at your owned domains signs in to Tilt Base through it. A new connection stays inactive until a test sign-in through it works and you activate it, so setting one up affects nobody.
## Before you start
- Tilt has switched SSO on for your organisation. Tilt switches this on for your organisation; contact [support@tilt.legal](mailto:support@tilt.legal).
- At least one domain is proved by DNS, as <mention-page url="https://app.notion.com/p/41b4815eed4f816cb587d2302d26a112">Verify your domains</mention-page> describes.
- You, or someone working with you, can create an application in your identity provider.
## Add a connection
Go to Settings › Organisation › SSO and directory. Under **SSO connections**, select **Add connection**, then choose your identity provider: **Microsoft Entra ID**, **Okta**, **Google Workspace**, **Another SAML provider** or **Another OIDC provider**. Set-up then has four stages: **Details**, **Identity provider**, **Test** and **Activate**.
### 1. Details
1. Check the **Name**, which starts as your organisation's name and the provider's. It can be up to 100 characters.
2. Under **Domains**, tick the owned domains this connection serves. A domain is on one connection at a time, so one another connection serves shows "Served by" and can't be ticked.
3. Select **Add connection**. Base adds the connection, inactive, and moves on.
### 2. Identity provider
Base shows your provider's steps and the values your identity provider needs. Follow them in your identity provider, in another tab, then give Base its details and select **Save and continue**.
<tabs>
	<tab icon="🔷">
		Microsoft Entra ID
		1. In the Microsoft Entra admin centre, open **Enterprise applications**, choose **New application**, then **Create your own application**. Name it Tilt Base and choose to integrate an application you don't find in the gallery.
		2. Under **Single sign-on**, choose **SAML**. In **Basic SAML Configuration**, set **Identifier (Entity ID)** to the **Entity ID** Base shows, and **Reply URL (Assertion Consumer Service URL)** to its **ACS URL**.
		3. Under **Attributes & Claims**, check the email address claim takes `user.mail`, and that the given name and surname claims are there. To send people's job titles too, add a claim from `user.jobtitle`.
		4. Under **Users and groups**, assign the people who use Tilt Base.
		5. Under **SAML Certificates**, copy the **App Federation Metadata Url** and paste it into Base under **Metadata URL**.
	</tab>
	<tab icon="🔑">
		Okta
		1. In the Okta Admin Console, open **Applications**, choose **Create App Integration**, then **SAML 2.0**, and name it Tilt Base.
		2. Set **Single sign-on URL** to the **ACS URL** Base shows, and **Audience URI (SP Entity ID)** to its **Entity ID**. Set **Name ID format** to EmailAddress and **Application username** to Email.
		3. Add the attribute statements `email` (`user.email`), `firstName` (`user.firstName`) and `lastName` (`user.lastName`).
		4. Assign the people or groups who use Tilt Base.
		5. On the **Sign On** tab, copy the **Metadata URL** and paste it into Base under **Metadata URL**.
	</tab>
	<tab icon="🟢">
		Google Workspace
		1. In the Google Admin console, open **Apps**, then **Web and mobile apps**. Choose **Add app**, then **Add custom SAML app**, and name it Tilt Base.
		2. Download the IdP metadata, and paste the file's contents into Base under **Metadata**. Then continue in Google.
		3. Set **ACS URL** and **Entity ID** to the values Base shows, and **Name ID format** to EMAIL from **Primary email**.
		4. Under **Attribute mapping**, map **Primary email** to email, **First name** to firstName and **Last name** to lastName.
		5. Under **User access**, switch the app on for the people who use Tilt Base. Google can take up to 24 hours to apply it.
		Base can't set up a directory on a Google Workspace connection, so choose another provider if you'll want directory sync.
	</tab>
	<tab icon="🔐">
		Another SAML provider
		1. In your identity provider, create a SAML 2.0 application for Tilt Base with the **ACS URL** and **Entity ID** Base shows, or give it Base's **Metadata URL**.
		2. Have it send each person's email address in the `mail` attribute, and their names as `firstName` and `lastName`.
		3. Assign the people who use Tilt Base.
		4. Give Base the identity provider's details: its metadata URL under **Metadata URL**, its metadata under **Metadata**, or its issuer, sign-on URL and signing certificate under **By hand**.
	</tab>
	<tab icon="🔐">
		Another OIDC provider
		1. In your identity provider, create an OpenID Connect web application for Tilt Base that uses the authorisation code flow, with the **Redirect URI** Base shows.
		2. Check its ID token carries the `sub` and `email` claims, and `given_name` and `family_name` if it can.
		3. Assign the people who use Tilt Base.
		4. Paste its **Discovery endpoint**, **Client ID** and **Client secret** into Base.
	</tab>
</tabs>
For a SAML provider, choose how you give Base its details: **Metadata URL**, **Metadata**, or **By hand** with the **Issuer (entity ID)**, **Sign-on URL** and **Signing certificate**. Base never shows a certificate, metadata or client secret again. When you come back to this step, leave the field blank to keep the one you gave.
### 3. Test
1. Select **Start a test sign-in**, then **Open the test sign-in**.
2. In the new tab, sign in through your identity provider as someone it assigns to Tilt Base. A test signs nobody in to Tilt Base.
3. Back in Base, **Latest test sign-ins** shows whether it **Worked** or **Failed**. A failed test says what to fix. **Start another** tries again.
4. Once a test has worked, select **Continue**.
### 4. Activate
Base activates a connection only after a test sign-in through it has worked. Select **Activate**, or **Not yet** to leave it inactive. Once it's active:
- everyone with an address at its domains must sign in through your identity provider, in Tilt Base and in their AI platforms' connections;
- members who already have accounts keep them, linked to your identity provider by their verified email address;
- people who sign up at its domains sign in through it instead of being invited.
## Connection badges and menu
<table header-row="true">
<tr>
<td>Badge</td>
<td>What it means</td>
</tr>
<tr>
<td><span color="green_bg">Active</span></td>
<td>People at its domains sign in through it.</td>
</tr>
<tr>
<td><span color="yellow_bg">Not active</span></td>
<td>Set up, but not activated, so nobody signs in through it.</td>
</tr>
<tr>
<td><span color="yellow_bg">Set-up unfinished</span></td>
<td>Base doesn't have enough of the identity provider's details yet.</td>
</tr>
<tr>
<td><span color="blue_bg">Directory</span></td>
<td>A directory belongs to this connection.</td>
</tr>
</table>
Each connection's **…** menu has **Identity provider**, **Test sign-in**, **Activate** until it's active, the just-in-time sign-up switch, and **Remove connection**. To change its name or domains, select its card and go back to **Details**.
## Just-in-time sign-up
Just-in-time sign-up gives someone at the connection's domains who has no Tilt Base account an account, and a membership of your organisation, the first time they sign in through it.
- It's on for a new connection while your organisation has no directory. Use **Switch just-in-time sign-up off** or **Switch just-in-time sign-up on** in the connection's **…** menu.
- While you have a directory, it's off on every connection and can't be switched on: your directory adds your people.
- It stops only new accounts. Someone who already has a Tilt Base account at your domains, from another organisation for example, still joins when your identity provider signs them in. Your identity provider decides who signs in.
## Change an active connection
<callout icon="⚠️" color="yellow_bg">
	**Changes to an active connection apply at once.** If the identity provider's details are wrong, nobody at its domains can sign in until they're put right.
</callout>
If your identity provider changes its signing certificate, paste its new metadata under **Metadata**, or the certificate under **By hand**. Saving the same metadata URL again doesn't re-read it.
## Remove a connection
<callout icon="🗑️" color="red_bg">
	**Removing a connection unlinks everyone's SSO sign-in.** People at its domains no longer sign in through your identity provider. Anyone who signed in only through it chooses a password with <mention-page url="https://app.notion.com/p/41b4815eed4f81e89f97f6cd96efb8a9">Set a password</mention-page> on the sign-in page, and Base tells you how many people that is before you confirm.
</callout>
1. In the connection's **…** menu, select **Remove connection**.
2. Read what Base says will happen, then select **Remove connection**.
- Base refuses while a directory uses the connection, because removing it would delete the directory too. Remove the directory first, as <mention-page url="https://app.notion.com/p/41b4815eed4f81238c01c7fdfb1374e4">Pause or remove a directory</mention-page> describes.
- Once an active connection is removed, Base adds back each of its domains that no other active connection serves as a verified domain. People who sign up there are invited again, unless you have a directory.
- If any domain is still missing afterwards, the page asks you to add it back as a verified domain. Select **Add back**.
## Troubleshooting
- **"No owned domain is proved by DNS yet."** Prove one under **Domains** first.
- **"Another SSO connection in Base already serves one of those domains."** A domain is on one connection at a time. Take it off the other connection first.
- **"Give the identity provider's address without a user name or password in it."** Enter the address on its own.
- **A test sign-in fails.** **Latest test sign-ins** says what to fix. Google Workspace can take up to 24 hours to apply a new app.
- **Activate is refused.** A test sign-in through the connection has to work first.
- **People can't sign in after your identity provider changed its certificate.** Paste its new metadata under **Metadata**, or the certificate under **By hand**.
## Related
- <mention-page url="https://app.notion.com/p/41b4815eed4f816da432c280738cffe2">SSO and directory sync</mention-page>
- <mention-page url="https://app.notion.com/p/41b4815eed4f816cb587d2302d26a112">Verify your domains</mention-page>
- <mention-page url="https://app.notion.com/p/41b4815eed4f81ad9bf2c175e15637d2">Set up directory sync</mention-page>
- <mention-page url="https://app.notion.com/p/41b4815eed4f81268723e757397eb959">Sign in</mention-page>
- <mention-page url="https://app.notion.com/p/41b4815eed4f81e89f97f6cd96efb8a9">Set a password</mention-page>