SAML SSO with Okta
Okta’s SAML 2.0 app integration is the object that does this. There is no KnoxCall entry in the Okta Integration Network, so you create your own — which is fine, because everything KnoxCall needs is four URLs and a certificate. Before you start- KnoxCall: an Enterprise plan, the owner or admin role, and at least one domain verified for single sign-on — a domain you verified for sending mail is a different proof and does not admit a login.
- Okta: an administrator who can create app integrations (Super Admin, or Application Administrator).
1. Create the app integration
Applications → Applications → Create App Integration → SAML 2.0 → Next. Name it (for exampleKnoxCall), optionally add a logo, and continue to Configure SAML.
2. Configure SAML
Replaceacme with your workspace slug throughout. The authoritative copy of every value below is your own metadata document at https://acme.knoxcall.com/saml/acme/metadata — it is public, so fetch it in a browser and read the values off it.
KnoxCall’s SP entity ID is its metadata URL. That is deliberate and it is what the metadata document says; do not shorten it to the origin.
Why the application username is the Okta user ID, not the email. The application username is what Okta puts in the NameID (its SAML field reference describes the Name ID format as “The username format to send in the SAML Response”), and KnoxCall recognises a person by their NameID. An email-based username changes when the person is renamed — Okta’s own documentation notes that it can update an app username automatically “when the email address changes” — and a NameID that changes gives the renamed person a second KnoxCall account. The Okta user ID is an identifier Okta assigns, not one made from the person’s name or address, so a rename leaves it alone; Okta’s Expression Language reference documents
user.getInternalProperty("id") as returning the user’s ID. The whole argument is in choosing the NameID.
Then check what Okta actually sends. Okta documents that when a sign-in request includes a NameID policy, the application’s Name ID format “must match it”, which is why the format stays on the email-address format above. It does not document what it does with a username that is not an address under that format. So once step 4 is done, run a sign-in from the connection’s Test tab in KnoxCall and read the NameID in the verdict: an id like 00u… means you are done; an address means the connection will keep showing its NameID notice, and it will be right to.
These are the default connection’s values — the connection every workspace starts with, and the one the /saml/<workspace>/… alias resolves to. If Okta is a second identity provider for this workspace, it gets its own connection with its own handle, and its values are /sso/<workspace>/<handle>/{metadata,acs,login,slo} — for a handle of okta, https://acme.knoxcall.com/sso/acme/okta/acs and its three siblings. Open that connection under Settings → Single sign-on and its Certificates tab lists all five, each with a copy button. See more than one identity provider.
Attribute statements
KnoxCall reads a plain email and display name and nothing else. Two statements are enough:
Both names are on KnoxCall’s default list, so no configuration is needed on the KnoxCall side to read them. If your Okta profile carries the address somewhere other than
user.email, keep the statement named email and change the value — that is easier than naming an attribute on the KnoxCall connection.
The email statement is required. With the NameID set to the Okta user ID, it is the only place KnoxCall finds the person’s address — without it nobody can be admitted, because admission is decided by the address’s domain.
Group attribute statements (optional)
Only needed if you want group membership to decide whether a new person lands as member or readonly.groups is one of the attribute names KnoxCall checks without being told to. Prefer a narrow filter to .*: Okta emits every matching group name on every assertion, and an assertion is a POST body a browser has to carry.
Whatever Okta emits — group names, here — is what you type as the keys of the group map on the KnoxCall connection. The map’s values are bounded: a group mapped to anything but member or readonly is refused at save time, because “…an IdP group may only map to member or readonly…” — those two and no others. Owner and admin are granted by a human on the team page and by nothing else.
3. Advanced settings (optional, and both worth doing)
Assertion Encryption. Set Assertion Encryption toEncrypted, then upload KnoxCall’s encryption certificate. Take it from the use="encryption" KeyDescriptor in our metadata document — it is the same certificate as the signing one, published twice on purpose, because an IdP reads one descriptor for each job. KnoxCall accepts encrypted and plain assertions alike, so this is your call.
Signature Certificate. Upload the certificate from the use="signing" KeyDescriptor so Okta can verify the AuthnRequests KnoxCall signs. KnoxCall signs every one; Okta simply ignores the signature until you give it the key to check it against.
Single Logout. Tick Enable Single Logout, then:
That is the IdP→SP direction. For the other direction — signing out of KnoxCall also signing out of Okta — put Okta’s own SLO endpoint (
https://<your-org>.okta.com/app/<app-label>/<app-id>/slo/saml, shown in Okta’s SAML setup instructions) into the KnoxCall connection’s IdP single-logout URL. It must be https; KnoxCall refuses anything else at save time, because a LogoutRequest carries the person’s email address as its NameID and the browser is redirected to that URL.
4. Take the Okta values back to KnoxCall
Two routes: import Okta’s federation metadata, or type the values by hand. The import is the one that cannot be mis-transcribed.Import the federation metadata
Applications → your app → Sign On → SAML Setup Instructions publishes Okta’s own Identity Provider metadata — one document carrying the issuer, the sign-on endpoint and every signing certificate. Hand KnoxCall that link, or the document itself:"apply": true. What the preview reports, what an import never touches, and every refusal it can answer with are on the overview. Like the metadata you handed Okta, it is a snapshot: nothing re-reads that URL on a schedule, so run the import again when Okta rolls the app’s signing certificate.
Or type the values
Applications → your app → Sign On → SAML Setup Instructions (or View SAML setup instructions) gives you three things. In KnoxCall, Settings → Single sign-on → your connection:Okta’s issuer really does begin
http://www.okta.com/. That is a SAML entity ID — a name, not an address; nothing dereferences it, and KnoxCall stores it as given. The two fields that are dereferenced, the sign-in URL and the single-logout URL, must both be https and are refused otherwise.5. Assign people, then test
Assignments → Assign — to people, or to Okta groups. Okta refuses sign-in to anyone unassigned before KnoxCall ever sees a request. Test with one account: openhttps://acme.knoxcall.com/saml/acme/login, sign in, and check the person lands in the workspace with the role you expected. If it fails, the login page names the cause — every message and code is in troubleshooting.
The Okta dashboard tile
Clicking KnoxCall in the Okta End-User Dashboard is an IdP-initiated sign-in, and it is off unless you turn it on. With it off the person is bounced back to the login page withsaml_idp_initiated_disabled. See IdP-initiated sign-in for how to switch it on and what it costs.
Rotating the Okta certificate
Okta’s app signing certificate expires, and Okta lets you generate the next one before the current one goes. Rotate add-first:- In Okta, Sign On → SAML Signing Certificates → Generate new certificate. Leave the current one active.
- Copy the new certificate into the KnoxCall connection. Pasting a certificate adds it — a connection can hold several active certificates and an assertion signed by any of them verifies.
- Activate the new certificate in Okta.
- Retire the old certificate in KnoxCall.