Set up single sign-on with Okta

Before you start

• You are an owner or admin of the Farside workspace.
• You can create application integrations in the Okta Admin Console.
• You know the workspace ID. People will need it to sign in.

Start in Farside

1. Open Settings, then Security, then Single sign-on, and add a provider. Choose SAML.
2. Leave the page open. Farside now shows the Entity ID and ACS URL for this provider, and you will paste them into Okta in a moment.

Values Farside gives you

When you add a provider, Farside generates a provider ID and shows the values below with a copy button next to each. Use the ones Farside displays. The placeholders here stand in for your own provider ID.

Create the SAML app in Okta

1. In the Okta Admin Console, go to Applications and choose Create App Integration. Pick SAML 2.0.
2. Name the app Farside and continue to Configure SAML.
3. Paste the Farside ACS URL into Single sign-on URL.
4. Paste the Farside Entity ID into Audience URI (SP Entity ID).
5. Set Name ID format to Persistent or EmailAddress. Do not use Unspecified or Transient.
6. Leave the signature settings at their defaults, or make sure the assertion is signed with SHA-256.
7. Add attribute statements: email mapped to user.email, firstName mapped to user.firstName, and lastName mapped to user.lastName. Add a group attribute statement only if you want to send groups.
8. Finish the wizard. On the Assignments tab, assign the people or groups who should be able to sign in to Farside.

Give Farside the Okta metadata

1. In Okta, open the app's Sign On tab and copy the Metadata URL.
2. In Farside, choose to import metadata by URL and paste it. If you would rather upload a file, download the metadata XML from Okta and upload that.
3. Check the attribute mapping in Farside matches the names you used in Okta: email, firstName and lastName.

Name ID and attributes

Farside accepts a persistent or email address Name ID. Transient Name IDs are rejected, since they change on every sign-in and Farside could not tell who came back.

Send the user's email address as an attribute named email. It is required. First name, last name, display name and groups are optional. If your provider uses different attribute names, edit the attribute mapping on the provider in Farside.

Test, then activate

Editing the trust settings of an active provider (certificates, issuer, client ID or secret, endpoints) takes it offline until you test it again. Plan those changes for a quiet hour, or set up a second provider as a draft, test it, and switch over.

1. Back in Farside, choose Test connection. Farside sends you through your identity provider and checks the response.
2. Fix anything the test reports, then run it again. The test has to pass after every configuration change before Activate is allowed.
3. Choose Activate. Only one provider can be active in a workspace at a time. To switch providers, disable the live one first, then activate the new one.

Using OpenID Connect instead

If you would rather not use SAML, Okta can connect over OpenID Connect. Pick one protocol per provider in Farside.

Okta must sign ID tokens with an RS, PS or ES algorithm, which is its default. Farside refuses sign-in when email_verified is false.

1. In Farside, add a provider and choose OpenID Connect. Copy the redirect URI it shows.
2. In Okta, go to Applications and choose Create App Integration. Pick OIDC, then Web Application.
3. Paste the Farside redirect URI into Sign-in redirect URIs. Assign the people or groups who should have access.
4. Copy the client ID and client secret Okta shows you into Farside.
5. Set the issuer to your Okta org URL, for example https://<org>.okta.com. Farside reads the rest from Okta's discovery document.
6. Farside picks basic or post client secret authentication automatically from your provider's discovery document. The scopes are openid, email and profile.
7. Test the connection, then activate.

How people sign in

On the Farside login page, people choose Sign in with SSO and enter the workspace ID. Farside sends them to your identity provider and brings them back signed in.

Once your workspace has verified its email domain, people can enter their work email address instead of the workspace ID. Until then, the workspace ID is the way in, so share it with your team.

Accounts, linking and new users

Someone who already has a Farside account is asked for their Farside password the first time they sign in with SSO, plus their authenticator code if they have one set up. That happens once, and it links the two. Farside never links an account on a matching email address alone.

New accounts are created on first sign-in only for email addresses on a domain your workspace has verified. They get the provider's default role, either Member or Admin, which you choose when you set it up.

Someone you invited from outside a verified domain accepts the emailed invitation first, then signs in with SSO.

MFA and offboarding

If your identity provider enforces multi-factor authentication, turn on the Your IdP enforces MFA toggle. Farside then skips its own authenticator prompt, but only for people who belong to no other Farside workspace. Anyone who also belongs to another workspace still gets the prompt, because that workspace has not agreed to your provider's policy.

Disabling a provider signs out every session that was started through it. Once people have signed in through a provider it stays as a disabled record, and only an unused provider can be deleted. If you use SCIM provisioning, anyone it has deprovisioned is refused at SSO sign-in as well.

Farside warns in the SSO panel when your provider's signing certificate expires within 30 days. To renew, re-import the metadata. The import URL is remembered, so it is one click. If the metadata lists both the current and the new certificate, sign-in stays on. If it only has the new one, Farside turns single sign-on off until you run a passing test and activate it again.

Troubleshooting

Next: automate provisioning

Single sign-on controls who can get in. SCIM controls who exists. Set up both and people lose access to Farside when they leave your directory.

• SCIM provisioning overviewHow users and groups are provisioned and deprovisioned.