Connect An App
Connecting an app takes seven short steps. Open Settings, then Security, choose Identity & Sign-In, then Connected Apps, and press Connect An App. You need the Manage Connected Apps permission.
Nothing is saved until Connect The App on step 6, and nobody is affected until someone signs in to the app.
Connect An App
On the right of steps 2, 4 and 6 you see a picture of the page people will see the first time they sign in, drawn from your choices. It changes as you do.
Step 1: Pick What You Are Connecting
Pick the product: WordPress, Grafana, Discourse, Moodle, Nextcloud, Mattermost, Zapier or Make. Kamo then knows its return address, the permissions it usually needs and the exact steps to finish in it.
Not in the list? Choose Custom Website for a website with its own server, Single-Page App for a web app that runs in the browser (React, Vue and so on), Mobile App for an iPhone, Android or desktop app, TV Or Device for a TV, a meeting-room screen or a command-line tool, or SAML App for an app that signs in with SAML single sign-on. Back-End Service, for a program that signs in as itself, is coming later.
A TV or device app and a SAML app take slightly different steps, described below.
Step 2: Name And Logo
The name and logo people see on the sign-in and permission pages, so they know which app is asking. The logo is optional: give the https:// address of a square picture, or leave it empty to use the product's own mark. A one-line description is shown the first time people sign in.
Step 3: Return Addresses
After someone signs in, Kamo sends them back to the app, but only to an address listed here, compared letter for letter. That stops anyone pretending to be your app and catching a sign-in on the way.
Addresses must start with https://. Mobile and desktop apps may also use their own address, such as com.yourcompany.app:/callback, or http://127.0.0.1 on any port.
Your Site’s Address
For WordPress, Grafana, Discourse, Moodle, Nextcloud and Mattermost, type the address people use to reach the product, for example https://blog.yourcompany.com. Kamo builds the exact return address the product uses from it. For Make there is nothing to type. For Zapier, a custom website, a single-page app or a mobile app, paste the return address the app or your developer gives you.
You can add more addresses, for example for a test copy of the site.
Sign-Out Addresses
Under More Sign-Out Settings: where people may be sent after they sign out through the app. Leave it empty if the app doesn't sign people out of Kamo. For Grafana, Kamo fills it in for you.
Sign-Out Notifications
Also under More Sign-Out Settings, for websites: when someone signs out of Kamo, Kamo can tell the app at this address so it signs them out too. The app must support back-channel logout; most don't, and it is fine to leave it empty.
Sign In On A TV Or Device
At the bottom of step 3, for a website, a single-page app or a mobile app: turn on Sign In On A TV Or Device to let people also sign in to the same app on a TV, a screen or a command-line tool, by approving a short code on their phone. Leave it off unless the app's developer asks for it. See Sign In On A TV Or Device for what people see.
How The App Sends Its Secret
For websites: how the app proves who it is when it collects a sign-in. Leave it on Basic, unless the app's instructions say "client secret post".
Step 4: What The App Can See
Each switch is one thing the app may learn about the person signing in:
- Sign-In: that it is the same person each time. Always on.
- Name And Profile: their name, user name, time zone and language.
- Email: their email address. Most apps need it to recognise people who already have an account there.
- Phone: the phone number on their profile.
- Organization: which organization they belong to, and whether they are on its team or a customer.
- Roles And Teams: their roles, department, job title and teams, so the app can give them the right access.
- Stay Signed In: the app may keep working for them when they are away, until access is taken back. Zapier, Make and mobile apps need it.
Give the app only what it needs. People see this list the first time they sign in.
Work With Kamo Data
Under the sign-in permissions, Work With Kamo Data lets the app read or change Kamo data for the person who signed in, through the Kamo API or an AI assistant. It is optional; most apps that only sign people in need none of it. Each kind of data (contacts, leads, calendar, email, notes and checklists, documents, the knowledge base and meetings) has a See switch and a Change switch, and each one says which Kamo permission a person needs, for example Needs View Contacts.
- An app can never do more than the person could do in Kamo. Someone without the permission simply doesn't give the app that part, and nothing breaks.
- If someone loses a Kamo permission later, the app loses it too.
- An app can never delete anything.
Developers will find the full list of these permissions, with their technical names, in Build An App On Your Organization's Sign-In.
TV Or Device Apps
A TV Or Device app has no return addresses: nobody types a password on the device. It shows a short code and an address; the person opens the address on their phone or computer, checks the code and presses Allow, and the device finishes signing in by itself. Its step 3 is How It Signs In, which shows the address people type the code at.
People always see the code-check screen, even for an app you pre-approve, so nobody can be tricked into approving a device they don't have.
Can The Device Keep A Secret?
Most TVs and command-line tools can't keep a secret safe, because anyone with the device could read it. Choose No, It Can't for those. Choose Yes, In The Header (or Yes, In The Form, if the device's software says "client secret post") only for a device you control that stores a secret securely. This can't be changed after the app is connected.
SAML Apps
A SAML App has its SAML Settings step instead of return addresses and permissions. Copy what it needs from the app's own SAML or single sign-on settings page:
- Type The Details: the app's Entity ID (also called Audience, Issuer or SP Entity ID) and its Reply Address (ACS URL), which must start with https://. You can add up to ten.
- Or Paste The App’s Metadata (below).
- Identify People By: Email Address (what most apps want), Persistent, Unspecified or Transient.
- Attributes: the facts the app receives, each under the name the app expects. New apps send email, firstName, lastName and displayName.
- Sign The Whole Response (on) and Can Be Opened From An App Launcher (off), below.
Who may use it, and asking first or pre-approving, work as for any app. The last step shows what to give the app; see Use Your Organization As A SAML Identity Provider.
Paste The App’s Metadata
Many apps offer their SAML settings as a metadata file or XML text. Paste the whole thing and Kamo reads the Entity ID, the reply addresses and the app's signing certificate from it. When you change an app later, leave the box empty to keep what it has.
Identify People By
What the app receives as the person's identifier. Email Address is the person's email; Persistent is a number that never changes for that person and that app; Unspecified sends the email for apps that don't mind the format; Transient is a new number at every sign-in.
Attributes
Each row is one fact the app receives: the Name In The App (no spaces, exactly as the app's documentation says) and What It Carries (email, first, last or full name, member number, department, job title, roles, teams or your organization's name). Back To The Usual Four restores the defaults.
Sign The Whole Response
Every sign-in Kamo sends is signed. With this on, the whole answer is signed too, which most apps expect. Turn it off only if the app's documentation says to.
Can Be Opened From An App Launcher
Usually people start at the app, which sends them to Kamo to sign in. Turn this on to let people open the app from a link or a launcher instead, using its Launch Address, and choose a Default Landing Page if you like. Leave it off unless the app's documentation asks for it.
Step 5: Who May Use It
For your team, choose Everyone, Some People or Nobody. With Some People, pick departments, job titles and teams, and add people by name; someone may use the app if they match any of them.
Customers
Customers are the people your organization serves who are not on your team, such as borrowers or patients. The usual choice is No Customers. Choose All Customers or Some Customers for an app meant for them, such as a customer portal.
Step 6: Ask First Or Pre-Approve
Ask Each Person First shows people what the app will learn and lets them say no, the first time. Pre-Approve For Everyone skips the question because you have decided for everyone. Pre-approve your own company tools; ask first for anything customers use.
A Private Member Number
Normally every app sees the same number for a person. Turn on Give This App A Private Member Number and this app gets its own number for each person instead, so two apps can't match up the same person. Most apps don't need it.
Press Connect The App (or Save Changes when you are editing).
Step 7: Finish In The App
The app is connected. The last screen shows:
- The Client ID, which names your app to Kamo. It isn't secret.
- The Client Secret for a website (see below).
- The exact steps to finish in the product, with every value filled in and a copy button beside each one.
- Code Samples in Node, Python and PHP (and the browser, for a single-page app) for a website or app of your own; for a TV or device app, the code sign-in on the command line and in Node.
- For a SAML app, instead of a client ID and code: the metadata address and the other details to give the app, and its signing certificate.
The Client Secret
The secret is the app's password, and it is shown only now. Copy it into the app or download the .env file before you close the window, then tick I’ve Saved The Secret. If it is lost, use Rotate Secret on the app's card to make a new one. Single-page apps and mobile apps have no secret.
The .env File
Download .env File saves a small text file with every value the app needs (the sign-in address, the discovery address, the client id, the secret, the return address and the permissions) in the format most frameworks read. Keep it out of source control: it contains the secret.
Code Samples
Working sign-in code for a website or app of your own. Each sample reads the .env file, so the same file works with all of them. They use well-known open-source libraries: openid-client for Node, Authlib for Python, and OpenID Connect PHP for PHP.
