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) or Mobile App for an iPhone, Android or desktop app. Back-End Service, for a program that signs in as itself, is coming later.

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.

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.

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.

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.