wmantly
4e5a2aa4f9
- New docs/concepts-{accounts,oauth-apps,api-tokens}.md -- plain-language
guides aimed at less technical readers, each linking onward to the
existing schema/protocol-level doc for anyone who wants that detail.
Card help links (Users, Groups, OAuth cards, My groups, Members of
<uid>'s group) now point here instead of straight at the technical
docs; the LDAP-protocol-wiring cards (raw connection details for
connecting a 3rd-party app) stay pointed at the technical ldap.md,
since that's genuinely the right depth for that task.
- The "New API Token" card had no help link at all -- added, pointing to
the new API Tokens doc.
- Fixed the in-app docs viewer rendering every docs/*.md page with a
garbled heading + stray <hr> at the top: Jekyll front matter (meant
only for the GitHub Pages build) was never stripped before being
handed to the markdown renderer. Also fixed: cross-doc links
(ldap.html, index.html, etc.) never resolved in-app, since this
viewer serves docs at /docs/<slug> with no .html suffix -- rewritten
to the correct in-app URL, same idea as the existing image-path fix.
Bumps to v1.1.12.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KDEx8ghuZR61pqPXc6da9C
80 lines
3.6 KiB
Markdown
80 lines
3.6 KiB
Markdown
---
|
|
layout: default
|
|
title: Connecting Apps (Single Sign-On)
|
|
description: A plain-language guide to OAuth/OIDC clients and single sign-on in SSO Manager.
|
|
---
|
|
|
|
# Connecting Apps (Single Sign-On)
|
|
|
|
This page explains, in plain language, what happens when you "connect" an
|
|
app to your SSO Manager so people can log into it with their existing
|
|
account. For the technical endpoint/token detail, see the
|
|
[OAuth reference](oauth.html).
|
|
|
|
## What does "single sign-on" actually mean?
|
|
|
|
Instead of every app you run having its own separate list of usernames and
|
|
passwords, they all check with this SSO Manager instead. You log in once,
|
|
here, and any connected app trusts that login — no separate password to
|
|
remember or manage for each one. If you ever need to lock someone out
|
|
everywhere at once, you do it in one place (deactivate their account here)
|
|
instead of hunting down every app individually.
|
|
|
|
The technology behind this is called **OAuth 2.0** and **OpenID Connect
|
|
(OIDC)** — you'll see both names used, often together, referring to the
|
|
same thing. You don't need to understand the protocol to use this page;
|
|
what matters practically is the handful of concepts below.
|
|
|
|
## What's a "client"?
|
|
|
|
Every app you connect is registered here as a **client** — a single entry
|
|
on the Integrations page representing that one app. Registering a client
|
|
gives you a **Client ID** and **Client Secret**: think of these like a
|
|
username and password, but for the *app itself* rather than for a person.
|
|
You paste them into the other app's own "Single Sign-On" or "OIDC" setup
|
|
screen, along with the discovery URL shown at the top of this page, and
|
|
that app is now able to ask this SSO Manager to authenticate people on its
|
|
behalf.
|
|
|
|
**Treat the Client Secret like a password** — anyone who has it can
|
|
impersonate that app when talking to your SSO Manager. If you ever suspect
|
|
it's leaked, rotate it from the client's card.
|
|
|
|
## What are "scopes"?
|
|
|
|
**Scopes** control what information a connected app is allowed to ask for
|
|
about the person logging in — their username, email, group memberships,
|
|
and so on. Most apps tell you exactly which scopes they need in their own
|
|
setup instructions; when in doubt, the default set (`openid`, `profile`,
|
|
`email`, `groups`) covers what nearly every app expects.
|
|
|
|
## "Restrict to Groups"
|
|
|
|
By default, *any* account with an SSO Manager login can sign into a
|
|
connected app. If that's not what you want — say, a home automation
|
|
dashboard that only certain family members should reach — set **Restrict
|
|
to Groups** on that client to one of your [groups](concepts-accounts.html).
|
|
Only members of that group will be allowed to log into that particular
|
|
app; everyone else gets turned away at the login step, even though their
|
|
SSO Manager account still works everywhere else.
|
|
|
|
## Redirect URIs
|
|
|
|
A **Redirect URI** is the exact web address the connected app wants people
|
|
sent back to once they've logged in here — it's a security measure so an
|
|
attacker can't trick the login flow into redirecting somewhere else. The
|
|
app's own setup instructions will tell you this value; copy it in exactly
|
|
as given. If the app is reachable via more than one hostname (for example,
|
|
because it sits behind [theta42/proxy](https://theta42.github.io/proxy/)),
|
|
this field supports wildcard patterns — see the inline help under the
|
|
field itself for the exact syntax.
|
|
|
|
## Want more detail?
|
|
|
|
This page intentionally skips the protocol-level detail (exact endpoint
|
|
URLs, token formats, claim names). If you're troubleshooting a connection
|
|
or building something against the API directly, see the
|
|
[OAuth reference](oauth.html).
|
|
|
|
[← Back to Home](index.html)
|