Skip to content
  • There are no suggestions because the search field is empty.

Okta Single Sign-On (SSO) Setup Guide

This guide shows how to set up SAML single sign-on (SSO) between Okta and Brevity, and how to require it for your organization.

Okta SSO overview

Brevity supports single sign-on through Okta. With SSO, members of your organization sign in to Brevity with their Okta account. You manage their access in Okta.

After SSO works, you can turn on Require SSO. Then members of your organization can sign in to Brevity only through Okta. See Step 5.

Requirements and considerations

Admin access

You must be an administrator of:

  • Your Okta organization
  • Your Brevity organization

Just-in-Time (JIT) provisioning

Just-in-Time (JIT) provisioning applies only to a person who has no Brevity account:

  • When a person with no Brevity account signs in through Okta, Brevity creates the account and adds it to your organization.
  • If that person has an invitation to your organization, Brevity accepts the invitation at the first Okta sign-in.

You do not need to turn this on. It applies to every organization that has SSO on.

A person who already has a Brevity account must be an active member of your organization before they can sign in through Okta. Brevity refuses an Okta sign-in from an existing account that is not an active member. Brevity does not accept an invitation for an existing account at the Okta sign-in.

To add a person who already has a Brevity account:

  1. Invite the person to your organization.
  2. Tell the person to sign in to Brevity with their usual sign-in method.
  3. Tell the person to open the invitation link and click Accept Invitation.
  4. Tell the person to sign in through Okta.

Note: If you also use SCIM, Okta controls the user accounts. Okta can replace changes that you make in Brevity. For more information, see our SCIM Okta Setup Guide.

Step 1: Add the Brevity app in Okta

  1. Sign in to the Okta Admin Console as an administrator.
  2. Go to Applications > Browse App Catalog.
  3. Search for Brevity and click it.
  4. Click Add Integration.
  5. Follow the steps of the wizard.

Assign users

  1. Click the Assignments tab of the Brevity app.
  2. Click Assign > Assign to People or Assign to Groups.
  3. Select the people or groups who use Brevity.
  4. Click Done.

Only assigned people can sign in to Brevity through Okta.

Step 2: Copy your Okta SSO values

Copy three values from the Brevity app in Okta.

Issuer

  1. In the Brevity app in Okta, click the Sign On tab.
  2. Find the SAML Signing Certificates section.
  3. Copy the full Issuer value. It looks like http://www.okta.com/exk....

X.509 certificate

  1. In SAML Signing Certificates, find the certificate with the Active label.
  2. Click Actions > View IdP metadata.
  3. In the metadata, find the <X509Certificate> element.
  4. Copy the text between <X509Certificate> and </X509Certificate>. Do not copy the tags.

Brevity also accepts the certificate in PEM format, with the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

App Embed Link (recommended)

  1. Click the General tab of the Brevity app in Okta.
  2. Find the App Embed Link section.
  3. Copy the Embed Link. It looks like https://[your-org].okta.com/home/[app]/[app id]/[link id].

This link starts an Okta sign-in to Brevity. Brevity uses it as the SSO redirect URL in Step 3.

Step 3: Set up SSO in Brevity

  1. Sign in to Brevity as an organization admin.
  2. Click your company's logo in the bottom-left of the Brevity window, then click View Organization.
  3. Make sure that All Organization is selected.
  4. Click the Settings tab.
  5. Click Sign-in and SSO.
  6. Turn on the Single sign-on (SSO) switch.
    Settings, Sign-in and SSO
  7. Paste the Issuer value from Step 2 into the Issuer URI field. (Okta calls this value Issuer. Brevity calls it Issuer URI.)
  8. Paste the certificate from Step 2 into the X.509 certificate field.
  9. Paste the App Embed Link from Step 2 into the SSO redirect URL field. This field is optional, but we recommend it.
  10. Click Save.

When the SSO redirect URL is set, Brevity sends a member to Okta at the email step of the sign-in page. This applies after the first Okta sign-in of the member, and to invited people who have no account.

Step 4: Test SSO

Test with a member who is not an administrator. Then a mistake cannot lock out an administrator. The test member must be an active member of your organization, or a person with no Brevity account.

  1. Open a private (incognito) browser window.
  2. Sign in to your Okta dashboard as the test member.
  3. Click the Brevity tile.
  4. Make sure that Brevity opens and that you are signed in.
  5. If the test member had no Brevity account, make sure that Brevity created the account and added it to your organization.

Brevity starts SSO from Okta. The Brevity sign-in page has no separate SSO button.

Step 5: Require SSO (optional)

When Require SSO is on, the members of your organization can sign in to Brevity only through Okta:

  • Brevity refuses sign-in with a password, an email code, Google or LinkedIn.
  • If a person signed in to Brevity without Okta, Brevity signs them out at their next action.
  • Personal API keys continue to work. (A personal API key connects another tool to one Brevity account.)

While Require SSO is on, you cannot remove the Issuer URI or the certificate. If you turn off the Single sign-on (SSO) switch, Brevity asks you to stop requiring SSO. If you confirm, Brevity turns off both.

Before you turn on Require SSO

  • SSO is on, and the Issuer URI and the certificate are saved (Step 3).
  • The SSO test in Step 4 passed.
  • Every member who uses Brevity is assigned to the Brevity app in Okta. A member who is not assigned cannot sign in.
  • We recommend that you set the SSO redirect URL (Step 3).
  • You opened Brevity from your Okta dashboard in this browser session. You must sign in through Okta before you can turn on Require SSO.

Turn on Require SSO

  1. Open Brevity from your Okta dashboard.
  2. Click your company's logo in the bottom-left of the Brevity window, then click View Organization.
  3. Make sure that All Organization is selected.
  4. Click the Settings tab.
  5. Click Sign-in and SSO.
  6. Under Require SSO, read the list of items that are still missing, if any. Complete each item.
  7. If the section shows Save your changes first, click Save.
  8. Turn on Require SSO.
  9. Read the confirmation. It shows how many active members have not signed in through SSO.
  10. Click Require SSO in the confirmation. Brevity saves the change at once.

The Sign-in and SSO section then shows when Require SSO was turned on and who turned it on.

What members see

  • If the SSO redirect URL is set, Brevity sends a member who tries another sign-in method to Okta.
  • If the SSO redirect URL is not set, the member sees a message to open Brevity from the company's app portal. The app portal is your Okta dashboard.
  • A person with no Brevity account accepts the invitation at their first Okta sign-in.
  • A person who already has a Brevity account opens the invitation link, accepts it while signed in to Brevity, and then signs in through Okta.

Members of more than one organization

A member can belong to more than one organization that requires SSO. If two organizations require SSO for one member, Brevity uses the organization that required SSO first. That member continues to sign in through the identity provider of that organization. The Sign-in and SSO section and the confirmation show how many members this applies to.

These members do not sign in through your Okta. To remove their access, remove them from your organization in Brevity.

Turn off Require SSO

Caution: If you turn Require SSO off and then on again, more members can move to another organization. To make changes while Require SSO is on, sign in through Okta.

  1. Open Brevity from your Okta dashboard.
  2. Click your company's logo in the bottom-left of the Brevity window, then click View Organization.
  3. Make sure that All Organization is selected.
  4. Click the Settings tab.
  5. Click Sign-in and SSO.
  6. Turn off Require SSO.
  7. Click Stop requiring SSO in the confirmation. Brevity saves the change at once.

Brevity staff can turn Require SSO on or off for your organization. Contact your Brevity Customer Success Manager.

Require SSO is not available

If the Sign-in and SSO section shows that Require SSO is not available yet, contact your Brevity Customer Success Manager.

Rotate the Okta signing certificate

The X.509 certificate field holds up to three certificates. Use this procedure to change the certificate without a lockout.

  1. In Okta, create or get the new signing certificate of the Brevity app.
  2. In Brevity, open Settings > Sign-in and SSO.
  3. Put the current certificate in PEM format. Add -----BEGIN CERTIFICATE----- above it and -----END CERTIFICATE----- below it.
  4. Paste the new certificate in PEM format below the current certificate.
  5. Click Save.
  6. In Okta, make the new certificate active.
  7. Sign in to Brevity from your Okta dashboard.
  8. Make sure that the sign-in works.
  9. In Brevity, remove the old certificate from the X.509 certificate field.
  10. Click Save.

Troubleshooting

Most SAML errors show on a Brevity page with the title SSO Login Failed. Membership refusals show on an access-denied page.

"We can't find an organization with the issuer you provided."

  • Make sure that the Issuer URI in Brevity is the same as the Issuer on the Sign On tab in Okta.
  • Make sure that there are no spaces before or after the value.
  • Make sure that the Single sign-on (SSO) switch is on and saved.

"Issuer provided certificate does not match the one we have."

  • Make sure that you copied the full certificate, with no extra characters.
  • Make sure that the certificate is the Active certificate in Okta.

"Unexpected or bad SAML response."

  • Make sure that the Audience URI of the Brevity app in Okta is https://app.brevitypitch.com/users/saml2/acs/, with the slash at the end.
  • If you cannot change it, contact your Brevity Customer Success Manager.

"Enter one or more PEM X.509 certificates, one after another, with no other text."

Brevity did not accept the certificate when you saved. Paste the text between the <X509Certificate> tags only, or paste full PEM certificates only. Do not mix the two formats.

"Enter no more than 3 certificates."

The X.509 certificate field holds up to three certificates. Remove a certificate that you no longer use, then click Save.

"Your account is not a member of this organization. Ask its administrator to invite you."

The person already has a Brevity account and is not a member of your organization. Invite the person. The person must accept the invitation in Brevity before they sign in through Okta. See "Just-in-Time (JIT) provisioning".

"Open your invitation link and accept it while signed in to your Brevity account, then sign in with single sign-on."

The person already has a Brevity account and has an invitation that is not accepted. Tell the person to sign in to Brevity, open the invitation link and click Accept Invitation. Then they sign in through Okta.

"This account already belongs to an organization that requires its own single sign-on. Ask your administrator."

Another organization requires SSO for this person, and it required SSO first. The person signs in through the identity provider of that organization. Brevity does not add the person to your organization.

"Your account access has been suspended. Please contact your administrator."

The membership of the person in your organization is inactive. Reactivate the membership. If you use SCIM, assign the person to the Brevity app in Okta again.

A user cannot sign in

  • Make sure that the user is assigned to the Brevity app in Okta. If the user is not assigned, Okta shows its own error, and Brevity shows nothing.
  • Make sure that the user opens Brevity from the Okta dashboard.

A member sees "Open Brevity from your company's app portal"

Require SSO is on and the SSO redirect URL is not set. The member must open Brevity from the Okta dashboard. To send members to Okta automatically, set the SSO redirect URL (Step 3).

The Require SSO switch is not available

The Sign-in and SSO section lists what is still missing:

  • SSO is off, or the Issuer URI or the certificate is not saved. Complete Step 3.
  • You did not sign in through Okta in this session. Do these steps:
    1. Save your changes.
    2. Sign out of Brevity.
    3. Open Brevity from your Okta dashboard.
    4. Go back to Settings > Sign-in and SSO.
  • The page has unsaved changes. The section shows Save your changes first. Click Save.
  • Require SSO is not available yet. Contact your Brevity Customer Success Manager.

Members are locked out

Contact your Brevity Customer Success Manager. Brevity staff can turn off Require SSO for your organization.

Additional resources

  • SCIM Okta Setup Guide: automatic user provisioning and user lifecycle management.
  • Need help? Contact your Brevity Customer Success Manager.