Skip to main content

​
SAML SSO with OneLogin

OneLogin federates through an application built on the SAML Custom Connector (Advanced). There is no KnoxCall entry in the OneLogin catalogue, so you build 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.
  • OneLogin: an administrator who can create apps and edit certificates (Super User, or an Account Owner).
Configured KnoxCall before 8 September 2026? Re-enter the values below, or re-upload our SP metadata. KnoxCall now signs AuthnRequests (RSA-SHA256), publishes an encryption key so an IdP can encrypt assertions to us, and publishes a Single Logout endpoint. A OneLogin app built from the older document has no signature certificate of ours on file, cannot be given our encryption certificate, and has no SLO endpoint of ours to call — none of which is visible from KnoxCall’s side. See the call-out on the overview page for the whole story.

​
1. Create the app

OneLogin admin console → Applications → Applications → Add App. Search for SAML Custom Connector (Advanced) and select it. Name it (for example KnoxCall), add an icon if you like, and save. Saving creates the app and opens its tabs: Info, Configuration, Parameters, Rules, SSO, Access, Users, Privileges.

​
2. Configuration

Replace acme with your workspace slug throughout. The authoritative copy of every KnoxCall 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 rather than assembling them by hand. 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, or OneLogin’s audience will not match the one KnoxCall enforces and every assertion will be rejected.
The ACS (Consumer) URL Validator is a regular expression, not a URL — and it is the field this integration gets wrong most often. Pasting the ACS URL into it unescaped leaves every . as “any character”, which matches hosts you do not own; leaving out the ^ and $ anchors turns it into a substring test. Escape the dots and the slashes and anchor both ends, as in the table above, and change it whenever the ACS URL changes.
Check the SAML signature algorithm. Older OneLogin connectors default to SHA-1, which KnoxCall does not accept. Set it to SHA-256 on this tab before you test, or every sign-in fails signature verification with no clue as to why on the OneLogin side.
These are the default connection’s values — the connection every workspace starts with, and the one the /saml/<workspace>/… alias resolves to. If OneLogin 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 onelogin, https://acme.knoxcall.com/sso/acme/onelogin/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.
Setting Login URL to the KnoxCall login endpoint makes the OneLogin portal tile an ordinary SP-initiated sign-in, which works with IdP-initiated login switched off. Leave it blank and the tile produces an unsolicited assertion instead, which KnoxCall refuses with saml_idp_initiated_disabled unless you have deliberately opted in — see IdP-initiated sign-in.

​
3. Parameters

The Parameters tab decides what the assertion carries. It starts with one row, NameID value.

​
The NameID should be a stable identifier

Open the NameID value row. OneLogin’s default value is Email, and an email changes when a person is renamed — which gives them a second KnoxCall account, because KnoxCall recognises people by their NameID (choosing the NameID). Change the value to OneLogin ID: a number OneLogin assigns, not made from the person’s name or address, so a rename leaves it alone. Keep SAML nameID format on the email-address format from step 2 — that is the format KnoxCall’s sign-in request names, and OneLogin’s own value has to sit under it. Once step 5 is done, run a sign-in from the connection’s Test tab in KnoxCall and read the NameID in the verdict: a number means you are done; an address means the connection will keep showing its NameID notice, and it will be right to.

​
The two attributes KnoxCall reads

Add both with + on the Parameters tab, ticking Include in SAML assertion for each — a parameter without that flag is configured and not sent, which is the other common way this integration silently does nothing: Both field names are on KnoxCall’s default list, so nothing has to be named on the KnoxCall side to read them. The email parameter is required. With the NameID set to the OneLogin ID, it is the only place KnoxCall finds the person’s address — and admission is decided by that address’s domain.

​
Roles as groups (optional)

Only needed if you want group membership to decide whether a new person lands as member or readonly. Add one more parameter, field name groups, value User Roles, with Include in SAML assertion ticked. groups is one of the attribute names KnoxCall checks without being told to, and OneLogin emits one value per role the person holds. Whatever OneLogin emits — role 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.

​
4. Encrypted assertions (optional)

On the Configuration tab, tick Encrypt assertion and give OneLogin the certificate from the use="encryption" KeyDescriptor in KnoxCall’s 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 and both take exactly the same path, so this is your call, not ours — and an app configured before 8 September 2026 has no encryption key of ours to use until our metadata is read again.

​
5. Take the OneLogin values back to KnoxCall

Two routes: import OneLogin’s metadata, or type the values by hand. The import is the one that cannot be mis-transcribed.

​
Import the federation metadata

The app’s More Actions → SAML Metadata publishes OneLogin’s own metadata — one document carrying the issuer, the sign-on endpoint, the logout endpoint and the signing certificate, at https://app.onelogin.com/saml/metadata/<app-id>. Hand KnoxCall that link, or the document itself:
The call previews by default and writes nothing until you send it again with "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 gave OneLogin, it is a snapshot: nothing re-reads that URL on a schedule, so run the import again when you move the app to a new certificate.

​
Or type the values

The app’s SSO tab carries all of them. In KnoxCall, Settings → Single sign-on → your connection: Saving needs a re-authentication in the last five minutes; that is expected, and it is the same bar as changing a password.

​
6. Single Logout

OneLogin’s SLO endpoint goes into the KnoxCall connection, as in the table above, and KnoxCall’s goes into Single Logout URL on the Configuration tab — that is both directions, and step 2 has already done half of it. Leave the KnoxCall field empty if you do not want the SP-initiated direction. Empty means “this connection does not do SP-initiated Single Logout” and it never falls back to the sign-in URL. The KnoxCall field 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. Either way, signing out of KnoxCall always ends the KnoxCall session — never conditionally on the IdP leg. The full behaviour is in Single Logout.

​
7. Assign people, then test

Access on the app → add the roles that should have KnoxCall, or assign individual users from Users. OneLogin refuses sign-in to anyone unassigned before KnoxCall ever sees a request. Test with one account: open https://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.

​
Rotating the OneLogin certificate

A OneLogin certificate belongs to the account, not to this app — it is created under Settings → Certificates and each app selects one from a dropdown. So a rotation is: create the new certificate, teach KnoxCall about it, then point the app at it. Rotate add-first:
  1. In OneLogin, Settings → Certificates → New, and generate the replacement. Do not change the app yet.
  2. 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.
  3. On the app’s SSO tab, select the new certificate.
  4. Retire the old certificate in KnoxCall.
Doing it in that order means there is no instant at which the certificate OneLogin is signing with is not one KnoxCall trusts. Retiring the only active certificate is refused outright: “This is the connection’s only active IdP certificate. Add the new certificate first, then retire this one.” Because the certificate is account-wide, step 3 is per app: rotating it here does not move your other OneLogin apps, and switching them over is a separate decision for each.