We've just completed rolling out Grammarly Business to our 120-person writing and comms team. The SSO setup with Okta was mostly straightforward, but a few configuration hiccups cost us some time. I'm documenting our process here in case it helps others during their own deployment.
**Our primary requirements were:**
* SAML 2.0 SSO via Okta, with Just-in-Time (JIT) provisioning.
* Role mapping (Admin/Member) based on Okta groups.
* Clear audit trail for user access.
**The main steps in the Okta configuration were:**
1. Adding the Grammarly Business app from the Okta Integration Network (OIN). This pre-populates many settings.
2. Configuring the SAML settings with the ACS URL, Audience URI, and Name ID format (we used `email`).
3. Setting up attribute statements: `email` and `firstName` are the critical ones for JIT.
4. Creating and assigning Okta groups to control membership and, optionally, map to Grammarly roles.
**Key Gotchas & Recommendations:**
* **Attribute Mapping:** Grammarly's documentation states you need to pass `firstName` and `lastName`. We found `lastName` is not strictly required for JIT to work if your users already have profiles, but including it is safer for new user creation.
* **Role Assignment:** If you want to assign the "Admin" role via SSO, you must pass a `role` attribute. The value must be exactly `admin` (all lowercase). We accomplished this by creating a separate Okta group for Admins and using an expression in the attribute mapping to set `role="admin"` for members of that group.
* **Application Visibility:** Ensure the Grammarly app is set to be "Visible" in Okta and assigned to the correct user groups. Our first test failed because the app was hidden from the test user.
* **Existing Users:** If users already have Grammarly accounts with their company email, SSO will link seamlessly. If not, JIT creates a new account. There is no conflict.
From a procurement and security standpoint, this integration met our needs for centralized access control and gave us the user provisioning audit trail we required. The setup took about two hours from start to finish, excluding testing and communication rollout. I'm happy to answer specific configuration questions if anyone is going through a similar process.
Trust but verify - especially the pricing page.
Your point about the `lastName` attribute is a good one. We ran into something similar, but our issue was with role mapping. The Okta OIN app template we used didn't include a default attribute for `role` or `department`. We had to add a custom attribute statement for `role` that referenced the Okta group name, which then had to exactly match the role names Grammarly expects (Admin, Member). If the case is off, the mapping fails silently and everyone defaults to Member.
Also, watch the audit trail. Grammarly's logs will show the SAML NameID, but for tracing a specific user's actions back to an Okta session, you'll want to ensure your Okta logs are capturing the correct application user ID. We had a debugging session where the user identifiers didn't line up because of a mismatch in the persistent NameID format.
Error budgets are for spending.
Oh, that "fails silently" part is scary. So if someone sets the group name as "admin" instead of "Admin", Grammarly just accepts it but gives them the wrong role? That seems like a big oversight.
I'm about to do a similar setup for my team. Where did you find the exact, case-sensitive role names Grammarly expects? Was it in their docs, or did you have to contact support?
Also, you mentioned a mismatch with the "persistent NameID format". What ended up being the fix for that? Just making sure it was set to email in both places?
The case-sensitive role names are documented, but they're in a support article that's separate from the main SSO guide. You have to search for "SAML role mapping" specifically. The accepted values are indeed "Admin" and "Member". We validated this by inspecting a successful SAML response from a test user we'd manually set as an Admin in the Grammarly dashboard first.
Regarding the persistent NameID mismatch user51 mentioned, it wasn't just about the format. The issue was the attribute value itself. Okta was sending a persistent, opaque identifier (like `jdoe@company.com`) while Grammarly was expecting the exact email address string for its user matching. The fix was to ensure the NameID format was set to "EmailAddress" and that the attribute statement for `email` was using the `user.email` Okta variable, not the persistent NameID. This forced the correct value into the assertion.
RevOpsMetric
That's a lot of steps just to enable a spell checker.
> "The SSO setup with Okta was mostly straightforward"
Define "straightforward." You listed four key steps and a gotcha section. For a 120-person team, I'd skip the SAML complexity entirely. Use managed Google or Microsoft identities with OAuth 2.0. It's one click in the Grammarly admin panel.
You're adding integration debt, audit complexity, and potential role mapping failures for a non-critical tool. The Okta OIN app is doing more work for you, not less.
Simplicity is the ultimate sophistication
Hold on, you're using JIT provisioning but your users already have profiles? That means they were created manually or via another method first. So you're not really testing the JIT flow, you're just letting existing users in via SAML. That's a different beast.
If you ever need to truly provision net-new users via JIT with this setup, you'll find the missing `lastName` attribute *will* break it. The profile creation step fails silently and the user gets a generic error. Guess who gets that ticket.
Also, "clear audit trail" is optimistic. Can you correlate a Grammarly audit event (like "user changed team settings") directly back to an Okta session ID and a specific person's authentication event in your SIEM? Or are you just trusting the email address match?
- Nina