communicationbusiness
Knowledge Base Article
Write self-service knowledge base articles that resolve customer issues without support contact — with clear titles, step-by-step solutions, troubleshooting trees, and SEO-friendly structure.
knowledge-basesupportself-servicehelp-centertroubleshooting
Works well with agents
Works well with skills
$ npx skills add The-AI-Directory-Company/(…) --skill knowledge-base-articleknowledge-base-article/
sso-setup-guide.md
Markdown
| 1 | # How to Set Up Single Sign-On (SSO) with Okta |
| 2 | |
| 3 | ## Overview |
| 4 | |
| 5 | This article walks you through connecting your Okta organization to Vaultline so your team can sign in with their company credentials. Setup takes about 15 minutes and requires admin access to both Okta and Vaultline. |
| 6 | |
| 7 | ## Applies To |
| 8 | |
| 9 | - **Vaultline plan:** Business or Enterprise |
| 10 | - **Role required:** Vaultline Organization Admin + Okta Super Admin |
| 11 | - **Supported protocol:** SAML 2.0 |
| 12 | - **Not covered:** OIDC/OpenID Connect (see "Related Articles" below), SCIM provisioning |
| 13 | |
| 14 | ## Step-by-Step Solution |
| 15 | |
| 16 | ### Part A: Configure Okta |
| 17 | |
| 18 | 1. Sign in to your Okta admin console at `https://your-domain-admin.okta.com`. |
| 19 | 2. Navigate to **Applications > Applications** in the left sidebar. |
| 20 | 3. Click **Create App Integration**. |
| 21 | 4. Select **SAML 2.0** and click **Next**. |
| 22 | - You should see the "Create SAML Integration" wizard with a "General Settings" step. |
| 23 | 5. Enter the following in General Settings: |
| 24 | - **App name:** `Vaultline` |
| 25 | - **App logo:** Upload the Vaultline logo (optional — download from `https://vaultline.io/brand/logo.png`) |
| 26 | - Click **Next**. |
| 27 | 6. In the "Configure SAML" step, enter these values: |
| 28 | - **Single sign-on URL:** `https://auth.vaultline.io/saml/acs` |
| 29 | - **Audience URI (SP Entity ID):** `https://auth.vaultline.io/saml/metadata` |
| 30 | - **Name ID format:** `EmailAddress` |
| 31 | - **Application username:** `Email` |
| 32 | 7. Under **Attribute Statements**, add: |
| 33 | - `firstName` -> `user.firstName` |
| 34 | - `lastName` -> `user.lastName` |
| 35 | - `email` -> `user.email` |
| 36 | 8. Click **Next**, select "I'm an Okta customer adding an internal app," and click **Finish**. |
| 37 | - You should land on the application's **Sign On** tab. |
| 38 | 9. On the **Sign On** tab, click **View SAML setup instructions** (or scroll to the "SAML Signing Certificates" section). |
| 39 | 10. Copy the following three values — you will need them in Part B: |
| 40 | - **Identity Provider Single Sign-On URL** |
| 41 | - **Identity Provider Issuer** |
| 42 | - **X.509 Certificate** (click "Download certificate") |
| 43 | |
| 44 | ### Part B: Configure Vaultline |
| 45 | |
| 46 | 11. Sign in to Vaultline as an Organization Admin. |
| 47 | 12. Navigate to **Settings > Security > Single Sign-On**. |
| 48 | 13. Click **Configure SSO** and select **SAML 2.0**. |
| 49 | 14. Paste the values from step 10: |
| 50 | - **SSO URL:** paste the Identity Provider Single Sign-On URL |
| 51 | - **Issuer URI:** paste the Identity Provider Issuer |
| 52 | - **Certificate:** click **Upload** and select the downloaded `.cert` file |
| 53 | 15. Under **SSO Enforcement**, choose one: |
| 54 | - **Optional:** members can use SSO or email/password (recommended during testing) |
| 55 | - **Required:** all members must use SSO (enable after confirming SSO works) |
| 56 | 16. Click **Save Configuration**. |
| 57 | - A green banner reading "SSO configuration saved" appears at the top of the page. |
| 58 | |
| 59 | ### Part C: Test the Connection |
| 60 | |
| 61 | 17. Click **Test SSO Connection** on the SSO settings page. |
| 62 | - A new browser tab opens and redirects to your Okta login page. |
| 63 | 18. Sign in with your Okta credentials. |
| 64 | - IF successful: the tab displays "SSO connection verified" and redirects back to Vaultline. |
| 65 | - IF it fails: see the Troubleshooting section below. Do not enable "Required" enforcement until the test passes. |
| 66 | 19. After a successful test, assign the Vaultline app to users or groups in Okta: |
| 67 | - In Okta, go to the Vaultline app > **Assignments** tab > **Assign** > select users or groups. |
| 68 | |
| 69 | ## Troubleshooting |
| 70 | |
| 71 | | Still seeing this? | Try this | |
| 72 | |--------------------------------------------|-----------------------------------------------------------------------------------------------| |
| 73 | | "SAML response signature invalid" | Re-download the X.509 certificate from Okta (step 10) and re-upload in Vaultline (step 14). Certificates rotate — ensure you have the active one. | |
| 74 | | "Audience URI mismatch" | Verify the Audience URI in Okta is exactly `https://auth.vaultline.io/saml/metadata` with no trailing slash. | |
| 75 | | Redirect loop after login | Clear browser cookies for `vaultline.io` and `okta.com`, then try again in an incognito window. | |
| 76 | | User gets "Account not found" after SSO | The user's Okta email must match their Vaultline account email. Check under **Profile > Email** in Vaultline. | |
| 77 | | SSO works for admin but not other users | Confirm users are assigned to the Vaultline app in Okta (**Applications > Vaultline > Assignments**). | |
| 78 | | "Certificate expired" error | Generate a new signing certificate in Okta under **Sign On > SAML Signing Certificates > Generate New Certificate**, then re-upload in Vaultline. | |
| 79 | | All troubleshooting steps failed | Contact Vaultline support at support@vaultline.io with: your Okta org URL, the error message, and a screenshot of your SAML configuration in Okta. | |
| 80 | |
| 81 | ## FAQs |
| 82 | |
| 83 | **Can I use multiple identity providers?** |
| 84 | Enterprise plans support multiple IdPs. Go to **Settings > Security > SSO** and click **Add Provider** to configure a second SAML connection. |
| 85 | |
| 86 | **What happens to existing email/password accounts when I enforce SSO?** |
| 87 | Existing users are prompted to sign in via SSO on their next login. Their accounts are linked automatically by email address. Passwords remain as a recovery fallback unless you disable password login separately. |
| 88 | |
| 89 | **Does SSO affect API keys or service accounts?** |
| 90 | No. API keys and service accounts authenticate independently and are not subject to SSO enforcement. |
| 91 | |
| 92 | **Can I require MFA in addition to SSO?** |
| 93 | MFA enforcement is handled in Okta. Configure MFA policies in your Okta org, and they apply when users authenticate through SSO. |
| 94 | |
| 95 | ## Related Articles |
| 96 | |
| 97 | - [How to set up SSO with Azure AD (SAML)](../sso-azure-ad) |
| 98 | - [How to configure SSO with OpenID Connect (OIDC)](../sso-oidc-setup) |
| 99 | - [How to set up SCIM provisioning with Okta](../scim-okta-provisioning) |
| 100 | - [How to troubleshoot "Account not found" errors during SSO login](../sso-account-not-found) |
| 101 |