How installations decide where an app can sign people in

An installation records that one app is installed in one organization. It is per organization: installing an app in one organization does nothing for another, and an app has at most one installation in an organization.

An installation holds:

• A ceiling. The permissions of the app that the organization consented to. It can only name permissions the app currently has as active, so a ceiling can never name another app's permission.
• The manifest version consented to, the version of the app's description the organization agreed to.
• A switch for the explain surface, which lets the app's callers ask why a decision came out as it did in that organization.
• A status, active or suspended.

The ceiling narrows and never grants. A permission outside it is denied there whatever roles or grants exist, and a ceiling that shrinks later switches the permission off without any role being edited. The exception is the platform's own identity and authz namespaces, which need no installation. See Authorization for where this sits among the other checks, and Permissions and roles for the vocabulary.

The platform's first-party apps are installed automatically. A personal workspace gets them when it is created, with the ceiling set to every permission those apps currently have. See The personal workspace. Other installations are made by administrators, with a ceiling chosen at that time. Changing the ceiling, the consented version or the explain switch later is an update, and each change is recorded in the audit log with the old and new ceiling.

Suspension is the reversible switch and has two independent sides: the organization's own, and the app's side, which the platform (or the app's publisher) throws. The installation counts as suspended while either side is held, and restoring one side leaves it suspended while the other still holds it. Removing an installation deletes it. Installing again starts with a fresh ceiling, because the old one is not kept.

An absent installation and a suspended one are treated as the same thing by the checks that matter, so a caller cannot learn which it is.

One predicate decides whether a client may enter an organization. It answers yes when any of these holds:

A client that is neither of the first two and has no app is refused. A suspended installation does not count as active.

For a person the rule is combined with an active membership into one answer. "The app is not installed", "this is another organization's client", "you are not a member" and "your membership is suspended" are all the same single answer, so the refusal says nothing about which it was. At sign-in that answer is the access_denied error described on Organizations. It runs before the organization's own sign-in rules are read.

The same rule is applied again later, not only at sign-in:

• Tokens. Redeeming an authorization code, refreshing a token and exchanging a token all fail once the client may no longer enter the organization, for example because its installation was suspended. A person's token also needs a live membership at that moment.
• Resources. When a request names a resource server by its address, that resource's app must also be installed in the organization, whoever the client is. A request for a resource that does not exist, one the client may not use and one that is not installed all get the same invalid_target error.
• Delegated calls. When a service acts for someone, every client in the chain of who is acting must itself be allowed into the organization, or the decision is refused. See Delegation and token exchange.

When single sign-on enforcement is on for an organization, its check sits between the installation half and the membership half, so a member and a non-member get the same answer there as well. See Single sign-on and managed accounts.

• An installation is not a role. It says an app may act in an organization, not what any person may do with it.
• A suspended organization is refused by its own checks, not by this rule. See Organizations.
• It does not replace consent. A third-party application still needs the person's consent. See Consent.

• Organizations
• Authorization
• Permissions and roles
• Installations and the entry rule, the same rule seen from a client you build