Okta setup guide for IT

This guide is for the IT team that runs your company's Okta. BloomText turns on SSO for your account, and you connect Okta once for every organization in it. Then you assign people to BloomText in Okta, and BloomText gives them the right organizations, roles and teams within 5 minutes, before they first sign in. When you deactivate someone in Okta, BloomText removes them from every organization in your account within 5 minutes. This works for everyone whose BloomText email matches their Okta email (see Assign people in Okta).

What you'll set up

• Two apps in Okta: a SAML 2.0 app for sign-in, and a SCIM 2.0 app for your directory. You create both through the setup portal of WorkOS, BloomText's sign-in partner, which shows each step for Okta. BloomText isn't an Okta Integration Network (OIN) catalog app, so you won't search the catalog for it.
• Rules in BloomText that map Okta groups or attributes to organizations, roles and teams.

What BloomText supports with Okta:

Okta comes first. Microsoft Entra ID, Google Workspace and other SAML or SCIM directories work through the same setup . Email support@bloomtext.com to ask for one.

How it fits together

• Your account is your company in BloomText. It holds your plan and every organization under it. An organization is a location or line of business, with its own patients, conversations, teams and phone numbers.
• One Okta connection serves the whole account. Every organization signs in through it.
• Rules decide where each person goes: an Okta group or a few attributes map to an organization, a role (Admin or User) and, optionally, teams.
• Memberships a rule creates are Managed by Okta. Only Okta and your rules change them.

Before you start

• You need to be an account Owner or have the account's IT role in BloomText. An Owner can give you the IT role on the Account page.
• BloomText needs to turn on SSO for your account. Email support@bloomtext.com to ask. The Okta & rules tab appears on the Account page once it's on.
• You need admin access to your company's Okta.
• Require MFA in the BloomText app's sign-on policy in Okta. BloomText doesn't text a code to people who sign in with SSO, so Okta's sign-in is the only extra check.
• Use the BloomText web app or desktop app.

1. Connect Okta and your directory

In BloomText, open Settings > Account > Okta & rules and click Set up in WorkOS. The setup portal opens one step at a time, in this order:

1. Verify your domain, such as @yourcompany.com.
2. Connect Okta: add the SAML app in Okta. WorkOS's Okta SAML guide shows the Okta screens.
3. Connect your Okta directory: add the SCIM app in Okta. WorkOS's Okta SCIM guide shows the Okta screens.

After each step the portal brings you back to Okta & rules. Click Set up in WorkOS again for the next one. The full walkthrough, with what the tab says at each step, is in Connect Okta.

2. Assign people in Okta

In Okta, open the BloomText app and assign the people who should use BloomText. Assigning Okta groups is easier to keep up than assigning people one by one. Only people assigned to the app reach BloomText.

Okta sends each assigned person to BloomText with their email, name, groups and profile attributes. BloomText matches people by email: one of the confirmed emails on a person's BloomText profile must be their Okta email. Once matched, BloomText remembers the person by their directory ID.

Someone already in BloomText under a different email, such as a personal address an admin invited years ago, isn't matched: Okta adds them as a separate user, and deactivating them in Okta doesn't remove their old one. Before you rely on Okta for offboarding:

1. Open Settings > Account > People and filter Managed by to Manual, then to API. These are the members Okta doesn't manage.
2. For each one who is also in Okta under another email, ask them to add and confirm their Okta email in their BloomText profile before you assign them in Okta. See Edit your profile, phone numbers and email.
3. Remove anyone who has left from each organization's Members tab. See Change a member's role or title, or remove them. For help, email support@bloomtext.com.

3. Choose groups or attributes

A rule's condition is one of:

• One Okta group, such as Northside-staff or Pediatrics-leads. On the BloomText app's Push Groups tab in Okta, push the groups you plan to use so BloomText can see them.
• Up to three attributes joined by AND, from Department, Office and Title. For example, department is Pediatrics AND office is Northside Clinic.

We recommend groups. Okta's own group rules can combine attributes and groups with AND, OR and NOT, so you keep the logic in Okta where you already manage it, and BloomText maps one group to one place.

Conditions in one rule are joined only by AND. For "A or B", write two rules.

What BloomText reads from Okta

Each Okta attribute arrives in BloomText's directory under the name in code below:

• Primary email (email): matches the person to a BloomText user, and is what they sign in with through SSO.
• First and last name (first_name, last_name): the name of a user BloomText creates.
• Department (department_name): what a rule's Department condition checks.
• Office (office, a custom attribute you map): what a rule's Office condition checks.
• Title (job_title): what a rule's Title condition checks.
• Pushed groups: what a rule's Okta group condition checks.
• Status (state): whether the person stays or is removed. See What the directory does.

Okta doesn't include a standard office field. If you want rules by office, map your Okta office attribute to office in the directory's attribute mapping in the setup portal. Test a person shows what BloomText reads for someone, so you can check the mapping.

BloomText doesn't read any other attribute.

4. Write rules in BloomText

Until your directory is connected, the Rules section says Connect your Okta directory to write rules.

1. On Okta & rules, click Add rule.
2. Under When someone in Okta has, choose Okta group or Attributes.
   • For a group, pick it in the Okta group list.
   • For attributes, choose an attribute, then type its value after is. To add another, click Add condition (and).
3. Under Add them to, choose the organization.
4. Under Role, choose User or Admin. Rules give the User or Admin role. Owner and IT are never given by a rule.
5. Optionally, under And to these teams (optional), tick teams in that organization.
6. Click Preview changes, check the preview, then click Save.

The editor also has Test a person, which tests the rule you're writing before you save it, and Delete rule for a saved rule.

How rules combine:

• Every matching rule applies. Someone who matches two rules for two organizations joins both.
• The higher role wins. If two rules put someone in the same organization, one as Admin and one as User, they're an Admin. Their teams from both rules are combined.
• Rules never grant Owner or IT. Those account roles are set only on the Account page.

The last rule: everyone else

The last rule in the list reads If Okta assigns anyone else → your default organization as User. It catches everyone you assign in Okta whom no other rule matches. Its editor is titled Edit everyone else and says Everyone in Okta whom no other rule matches. You can change its organization, role and teams, but you can't delete it, and it always stays last.

Because this rule always points at an organization, everyone you assign to the BloomText app in Okta gets access somewhere. Who reaches BloomText at all is decided by who you assign in Okta.

Preview before saving

Saving a rule changes real people's access right away, so BloomText shows Preview changes first:

• N people will be added to an organization.
• N memberships will be managed by Okta. These were added by hand or by an API key. Okta will manage them from now on.
• N people will be removed: Okta-managed people who no longer match any rule for that organization. People an admin or an API key added stay.
• N role changes, collapsed, with each person's old role.
• N people skipped, collapsed, with the reason for each:
  • Their email belongs to more than one BloomText user.
  • Their email is in use by a patient or was never confirmed.
  • They have no email in Okta.

If the change removes anyone, BloomText asks again in a window titled Remove N people from their organizations? Click Remove N people to save, or Cancel to change nothing.

After saving, a bar says what happened, for example Rule saved. 12 changes made, 3 still in progress, 1 failed and will be retried at the next sync.

If something changed in Okta or BloomText while you were looking at the preview, nothing is saved. Check the updated preview, then save again.

Test a person

Click Test a person under the rules. Type their Email in Okta and click Test. BloomText shows:

• Their Department, Office, Title and Groups as Okta sends them.
• Each rule, and whether each of its conditions matches.
• Where they'd land: each organization, role and team, or No organization: no rule matches them.

5. Test with one person

Before you assign everyone:

1. In Okta, assign one test person to the BloomText app.
2. In BloomText, run Test a person for them and check Where they'd land.
3. Within 5 minutes, open Settings > Account > People, filter Managed by to Okta, and check that they're there with the organizations, role and teams you expect.
4. Have them click Sign in with SSO and sign in.
5. Then assign your groups.

What the directory does

BloomText checks your directory for changes every 30 seconds, and checks everyone in it again every 3 minutes, so a change takes effect within 5 minutes.

Removal works only for people BloomText matched to their Okta email or directory ID. Remove anyone else by hand.

When a membership is removed, any team memberships in that organization go with it, including teams an admin added by hand.

Member history records these changes with Okta directory as who made them.

If the directory disconnects, Okta & rules shows Directory disconnected: people removed in Okta won't be removed from BloomText until it's reconnected. Click Set up in WorkOS to reconnect it.

What admins see

Organization Admins see Okta-managed people on the Members tab with an Okta badge and 🔒 Managed by Okta. They can't change their role or remove them; change the person's groups or attributes in Okta instead. Admins can still add an Okta-managed person to more teams by hand. See Work with people Okta manages.

The BloomText API can't change Okta-managed memberships either. It answers 409 managed_by_identity_provider.

If you deactivate an Owner or IT person

Deactivating someone in Okta removes their Owner or IT role along with their memberships. If they were the account's only Owner, your account's IT people and BloomText staff are also alerted, and BloomText staff appoint a new Owner after checking with you. The Account page warns ahead of time: Your only Owner is managed by Okta. If they leave, Bloom staff will need to appoint a new Owner. Add a second Owner.

People outside Okta

Contractors and others who aren't in Okta can still be added by an organization Admin, an Owner, IT or an API key. Okta leaves those memberships alone. If you later add the person to Okta and a rule matches them, their membership stays as it is until you next save a rule. That save's preview lists it, and saving hands it to Okta.

To stop organization Admins inviting people Okta doesn't manage, turn off Allow Admins to invite people outside Okta. See Invites outside Okta.

People who sign in before their access is set up

Someone Okta lets in who isn't a member of any organization in your account yet, for example because a rule hasn't placed them, becomes a pending join request to your account's default organization, labeled via SSO on its Members tab. An Admin can approve or decline it. See People who join through SSO.

Known limits

• People are matched by email first. A BloomText user whose confirmed emails don't include their Okta email isn't matched (see step 2).
• Owners and IT are set only in BloomText. Rules skip people who hold the Owner or IT role: their memberships come from the Account page. Deactivating them in Okta still removes them.
• One identity provider per account.
• Rules read only email, name, department, office, title and groups.
• Takeover happens only when you save a rule. A membership an admin or an API key made becomes Okta's only when a rule save lists it.

Troubleshooting

To see what happened, look at Okta's System Log and the BloomText app's Provisioning tab in Okta, and in BloomText at Settings > Account > People (filter Managed by) and each member's history.

Checklist

1. BloomText has turned on SSO for your account.
2. Your domain, Okta and your directory are connected on Okta & rules, and its banner says Okta connected · directory syncing.
3. People or groups are assigned to the BloomText app in Okta, and the groups your rules use are pushed.
4. Each organization has a rule, and the last rule points where you want everyone else to go.
5. You tested with one person (step 5).
6. Okta requires MFA in the BloomText app's sign-on policy.
7. On Settings > Account > People, everyone labelled Manual or API is a contractor or other person you manage by hand. If it lists someone who is in Okta, email support@bloomtext.com to merge their users.
8. The account has at least two Owners.
9. Optional: Require SSO is on, and invites outside Okta are set the way you want. See Require SSO.

Related

• Set up single sign-on for your account
• Sign in with Okta single sign-on (SSO)
• Work with people Okta manages
• Change a member's role or title, or remove them
• Invite teammates and choose their role
• Create, edit and delete teams