Some of the apps your team uses — wikis, help desks, learning platforms, dashboards — sign people in with SAML single sign-on instead of OpenID Connect. Kamo can be the identity provider for them. Your people then open those apps with the Kamo account they already have, and when someone leaves your organization in Kamo, they can no longer get into those apps either. Nothing changes for anyone until you add a SAML app.
Add A SAML App
Open Settings, then Security, choose Identity & Sign-In, then Connected Apps. You need the Manage Connected Apps permission. Administrators have it already.
Add an app and choose SAML as its type. The app needs two things from its own SAML settings page:
- Entity ID (some apps call it Audience, Issuer or SP Entity ID): the name the app uses for itself, often an address such as
https://wiki.example.com/saml/metadata. - Reply Address (ACS URL, Assertion Consumer Service): where Kamo sends the person back once they are signed in. It must start with
https://. You can add up to ten.
If the app offers a metadata file or metadata XML, paste it instead: Kamo reads the Entity ID, the reply addresses and the app's signing certificate from it.
The first SAML app you add turns on your organization's sign-in provider and makes its SAML signing certificate.
Give The App Kamo's Details
Each SAML app shows what to paste into the app:
- Metadata URL — most apps only need this one address. It is
https://login.<your domain>/saml/idp/metadata, orhttps://login.kamocrm.com/o/<your organization>/saml/idp/metadatawhen your organization has no domain of its own. - Identity Provider Entity ID —
…/saml/idp. - Sign-In Address (SSO URL) —
…/saml/idp/sso. Kamo accepts both the Redirect and the POST binding. - Signing Certificate — the certificate the app uses to check that the sign-in really came from you.
Every answer Kamo sends is signed, and it is made for that one app only: another app, or another reply address, will not accept it.
How People Are Identified
Choose what the app receives as the person's identifier (the NameID):
- Email Address — the member's email. Most apps want this.
- Persistent — an identifier that never changes for that person and that app. When the app is set to pairwise identifiers, each app gets a different one, so apps can't link people across each other.
- Unspecified — the email address, for apps that don't care about the format.
- Transient — a new identifier at every sign-in, for apps that should not recognise someone from one visit to the next.
Attributes
Attributes are the extra facts the app receives, each under the name the app expects. New apps send email, firstName, lastName and displayName. You can rename them and add others: member number, department, job title, roles, teams and your organization's name. Roles and teams are sent as several values.
Who May Sign In
The app's Access settings decide who may use it, exactly as for any connected app: everyone on the team, chosen departments, job titles, teams or people, and whether your customers may. Someone outside that list sees a plain explanation instead of the app.
Ask Every Person First shows a short "Sign in to <app>?" card the first time each person opens the app. Pre-Approved skips that card. Either way, each person can take the app's access back in My Profile, under Apps With Access.
Opening The App From An App Launcher
Usually the person starts at the app, which sends them to Kamo to sign in (SP-initiated). Some teams prefer to start from a list of apps instead (IdP-initiated). Turn on Can Be Opened From An App Launcher for the app and use its Launch Address (…/saml/idp/launch/<app>) as the link. You can set a Default Landing Page the app opens to. Leave it off unless the app's documentation asks for it.
Signed Requests
If the app signs its sign-in requests and you pasted its metadata, Kamo checks every request against the app's certificate, and refuses an unsigned one when the metadata says the app always signs. Every request can be used only once.
Renewing The Certificate
The signing certificate lasts ten years. Make A New SAML Certificate replaces it at once — every SAML app stops accepting sign-ins until you give it the new certificate (or it reads the metadata address again). Do it only when you have to, and update your apps straight away.
When Something Goes Wrong
People see a plain message instead of the app when:
- the app isn't one your organization added, or it is turned off;
- the app asked to send the person back to a reply address you didn't add;
- the app's request couldn't be checked against its certificate, was used before, or is too old;
- the app was opened from a launcher but isn't allowed to be.
Every sign-in to a SAML app is recorded in the access log as SAML App Sign-In.