Policies
Directory → Policies (/admin/policies) is where a realm sets the rules
it holds people to: passwords, sign-in, passkeys, language, the attributes a
person must carry, what a service account may do, and what somebody is asked
to do after they sign in. How a policy relates to the person and the
application that name it is the Directory chapter.
Each kind is a directory entry in its own container, with a tab of its own.
GET /admin-api/policies answers every kind. The
OpenAPI document (GET /admin-api/openapi.json) lists
each save. The fields of a kind are on the page linked from the table below;
this page is how a realm chooses which profile applies.
XACML policies are a different store. They live under Protocols → XACML,
in ou=policies, and a PDP evaluates them. See
Authorization and XACML.
The seven kinds
The console draws the tabs in this order. All profiles, last, lists every profile of every kind.
| Tab | Id | What default governs |
Where the fields are |
|---|---|---|---|
| Password policy | password |
the next password set in this realm | Passwords |
| Authentication policy | authn |
which ways of signing in are accepted, and when a second factor is required | The authentication policy |
| Service-account policy | serviceAccount |
what a service account may do, and how its password rotates | Service accounts |
| Passkey policy | passkey |
how passkeys behave at the next sign-in and the next enrolment | The passkey policy, Passkeys |
| Locale policy | locale |
the language a page falls back to, and the language a new person is given | Languages |
| Attribute policy | attributes |
the attributes every person must hold, and the realm’s custom attributes | The attribute policy |
| Post-login activity policy | postLogin |
what a person is asked to do after signing in | Post-login activities |
A profile applies to the next password, sign-in, page or create. A password already stored, a session already started and a person already created keep what they have. The password policy and the attribute policy are enforced in product mode only. The others are asked in both modes. What is not checked is the full line between the modes.
Named policies
Beside default, a realm may keep named policies of any kind. A named
policy holds the same fields as default and a precedence, a whole
number from 1 to 1000. Leave it out and it is 100.
The policy lists nobody. What it covers names it, with one single-valued
attribute on the holder. default and an empty value both mean “no
preference”. A named policy belongs to the realm it was created in and is
never inherited by another realm.
Who names which kind
| Kind | Application | Group | Person |
|---|---|---|---|
| Password | appPasswordPolicy |
stsPasswordPolicy |
|
| Authentication | appAuthnPolicy |
stsAuthnPolicy |
|
| Service account | stsServiceAccountPolicy |
||
| Passkey | appPasskeyPolicy |
stsPasskeyPolicy |
|
| Locale | appLocalePolicy |
stsLocalePolicy |
|
| Attribute | stsAttributePolicy |
stsAttributePolicy |
|
| Post-login | appPostLoginPolicy |
stsPostLoginPolicy |
An application’s reference is a field of its Configuration tab, Every
protocol, or POST /admin-api/applications/set with attribute and
value. A group’s is on the group’s page under Policies this group
names, or POST /admin-api/groups/set-policy with group, attribute
and policy. A person’s is on the Policies sub-tab of Attributes
(and on Users → New user), or POST /admin-api/users/set-attribute.
Only a service account may hold stsServiceAccountPolicy.
Each write accepts default or the name of a named policy this realm holds.
Anything else is refused. A value written with an LDAP client can still name
a policy the realm does not hold; what that does is
below.
How one is chosen
When a decision needs a profile, the candidates are:
- the policy the application names, when this kind has an application attribute and an application is in hand;
- the policy the person names, when this kind has a person attribute;
- the policy each of the person’s groups names.
An empty reference and default are not candidates. Of the policies that
are, the lowest precedence number applies. A precedence of 10 beats 50.
A tie goes to the name that sorts first. Where nothing names a policy,
default applies.
Two moments have fewer candidates, because less is known:
- Before the person is known — the first draw of a sign-in screen — only the application’s policy can apply. Once the person is known, the choice is made again.
- With no application — the portal, a reset link, activation, the
console,
/admin-api, an LDAP write, a reminder mail — the person’s reference and their groups’ references are the candidates. Registration of a passkey on/portal/keysis one of these.
A group that should be held to a stricter profile names that profile and gives it the lower number. A group or an application that should be left out names a profile that switches the behaviour off, again at a lower number than the profile that would otherwise reach them. The post-login page walks through that for one kind; the ranking is the same for every kind.
A name the realm does not hold
A reference to a name this realm has no policy of is not a candidate. The
console and the API refuse to write one. An ldapmodify, or a policy
deleted by hand, can leave one behind. What it means depends on the kind,
because some kinds can fall through to default and one cannot:
| Kind | What a dangling name does | Logged as |
|---|---|---|
| Authentication | That sign-in allows no mechanism, until the policy exists or the reference changes. The authentication policy fails closed: a missing name must not widen what a sign-in allows. | STS-AUTHN-0536 |
| Password | That reference is dropped. The references that remain still rank. default applies only when none remain. |
STS-AUTHN-0539 |
| Passkey | That reference is dropped. default applies when nothing else names a profile. |
STS-AUTHN-0537 |
| Locale | That reference is dropped. default applies when nothing else names a profile. The policy only chooses a fallback language. |
STS-I18N-0013 |
| Attribute | That reference is dropped. The references that remain decide, and default when none remain. |
STS-LDAP-0196 |
| Post-login | That reference is dropped. The references that remain decide. | STS-AUTHN-0542 |
| Service account | The account follows default. |
STS-SVCACCT-0047 |
Each of those is logged, and none of them is sent to a client. Error codes has the record.
Writing and deleting
A name is lower-case letters, digits and hyphens, starting with a letter or
a digit. It is at most 64 characters. A named authentication policy is
at most 63 (STS-AUTHN-0532). The name default is the realm’s own profile
and is refused as a named policy.
Save a named profile with POST /admin-api/policies/save-<id>-policy and a
profile other than default, and remove it with reset-<id>-policy and
the same profile. The authentication policy is the exception: its named
policies use save-named-authn-policy and delete-named-authn-policy,
because a named authentication policy stores two lists (mechanisms and
secondFactors) beside the realm’s own profile.
A named policy that any holder still names is not deleted. Point each
holder at default or at another policy first. The Named policies
sub-tab lists who names it (namedBy: applications, groups and people).
| Kind | Refused while a holder names it |
|---|---|
| Password | STS-AUTHN-0540 |
| Authentication | STS-AUTHN-0534 |
| Service account | STS-SVCACCT-0049 |
| Passkey | STS-AUTHN-0538 |
| Locale | STS-I18N-0014 |
| Attribute | STS-LDAP-0197 |
| Post-login | STS-AUTHN-0543 |
On the console each tab has three sub-tabs: Default, Named policies and New policy. The attribute policy adds Custom attributes. The passkey policy adds Learned clients.
The default profile, and what is inherited
default is cn=default in the kind’s container. For every kind except the
password policy, a realm with no default of its own follows the default
realm’s profile, and the built-in defaults where that realm has none
either. Saving the form writes this realm’s own profile, which then applies
here only. Removing it puts the realm back to following.
The password policy does not follow another realm. Until this realm saves one, the built-in defaults are in force (minimum length 12, one symbol, an uppercase letter, a digit, and none of the last five).
Named policies are never part of that fallback. A realm that has not created
admins does not see another realm’s admins.
Password policy
ou=passwordPolicies. A group names one in stsPasswordPolicy; an
application names one in appPasswordPolicy. The application’s policy
applies to a password chosen while signing in to that application (the
forced change after a reset). A password set on the portal, through a reset
or activation link, on the console, through /admin-api or by an LDAP write
of userPassword has no application, so the person’s groups decide, and
default where they name none.
The same profile decides the length of a password the service generates and how the password is hashed. Product mode enforces it at every door that sets a password. Development mode records the history and enforces nothing.
The rules, the generator and the API body are under Different password rules. The directory entry is under LDAP.
Authentication policy
ou=authnPolicies. A named policy narrows the realm’s: it lists the
first-factor mechanisms and the second factors a sign-in may use. Nothing
ticked in a list allows every mechanism the realm allows. A mechanism the
realm has switched off stays off.
An application names one in appAuthnPolicy. A group names one in
stsAuthnPolicy. For a sign-in to an application, the two compete by
precedence. An application naming a policy this realm does not hold allows
no mechanism, and so does a group naming one, for every member
(STS-AUTHN-0536).
Named authentication policies has the lists, the re-prompt and the API. An application’s page is Sign-in mechanisms.
Service-account policy
ou=serviceAccountPolicies. Only a service account names one, in
stsServiceAccountPolicy on its own entry. A group has no attribute for
this kind, and neither does an application. An account that names nothing
follows default. Writing the attribute on anybody else is refused
(STS-SVCACCT-0048).
Named policies has the fields and the rotation.
Passkey policy
ou=passkeyPolicies. An application names one in appPasskeyPolicy; a
group names one in stsPasskeyPolicy. At a sign-in the two compete. A
registration on /portal/keys has no application, so the groups decide.
Different rules for different applications or groups has the save body. An application’s own page shows which profile a sign-in gets before the person is known: The passkey policy that applies to it.
Locale policy
ou=localePolicies. An application names one in appLocalePolicy; a group
names one in stsLocalePolicy. The lowest precedence chooses the fallback
language, and the language a new person is given when the application caused
the create. A page drawn before anybody is known follows the application
alone.
Named profiles has the two fields and an example. A named profile used to list its applications itself. Those lists are not read any more: name the profile from the application and the group.
The attribute policy
ou=attributePolicies. uid, cn and sn are always required. By default
givenName and mail are too. The Default sub-tab lists every
attribute a person may be given, with a Required box.
A named attribute policy is a required list and a precedence. A person
names one in stsAttributePolicy on their own entry. A group names one with
the same attribute on the group. There is no application attribute for this
kind. Of the person’s reference and their groups’ references, the lowest
precedence applies, and default when they name none.
At a create the policy is the reference the create writes, together with
any group that already lists the new DN. At an edit it is the reference
the entry will hold after the edit, together with the groups the person is
in. SCIM maps no attribute to stsAttributePolicy, so a SCIM create is held
to a group that already lists the person. A replace or a PATCH is held to
the policy the person’s own reference and their groups then select. See
Configuring SCIM.
Product mode refuses a create that lacks a required attribute, at every
door, and refuses an edit that would take one away. Development mode stores
the policy and does not enforce it. A person created before an attribute
became required is not refused for lacking it.
GET /admin-api/policies?missing=count counts those people, each against
their own policy. A service account and the bootstrap administrator are
exempt.
Custom attributes are defined on the same tab: a name, a label, a syntax
and whether the attribute holds one value or several. They belong to the
realm (ou=attributeDefinitions) and are not inherited. A custom attribute
cannot be removed while anybody holds a value of it, or while any profile of
this realm requires it. POST /admin-api/policies/define-person-attribute
and remove-person-attribute are the same acts.
Each custom attribute has two user portal settings, both off by default:
Show it to the person on the portal and Let the person change it on
the portal. The person then sees, or edits, their own values on the
portal’s Overview (User-facing pages;
POST /account-api/attributes). Letting the person change an attribute also
shows it, and hiding it also stops the editing. Change on the attribute’s
row edits its label, description and the two settings, as does
POST /admin-api/policies/update-person-attribute. The syntax and whether it
holds several values cannot be changed (STS-LDAP-0208).
The directory shape is under LDAP schema.
Post-login activity policy
ou=postLoginPolicies. A group names one in stsPostLoginPolicy; an
application names one in appPostLoginPolicy. At a sign-in the two compete.
A reminder mail and the progress report have no application, so they follow
the person’s groups.
A named profile with the activity switched off, given a lower precedence than the profile that would otherwise apply, keeps those people out. One a group names keeps them out of the mails as well. One an application names keeps them out of a sign-in to that application only.
Which profile applies has the fields and a worked example.
All profiles
The last tab lists every profile of every kind: the kind, the name, where it
is stored, and how many problems the profile has. A row that is stored shows
its DN. A default this realm has not saved shows either that it is
inherited from the default realm, with that realm’s DN, or that nothing is
stored and the built-in defaults are in force. The list is paged.
GET /admin-api/policies is the same list.
Export and import
The Export and import tab moves a realm’s policies as one signed JSON document: to another realm of this service, to another installation, or back into the same realm as a restore.
What an export holds. Every kind on this page, and of each only what the
realm stores: its own default profile and its named policies. A profile
the realm inherits from the default realm, or the built-in defaults, is not
the realm’s and is left out. Each profile is carried as the body its kind’s
Save takes, so an import goes through the same checks a Save from this page
does.
How it is signed. The document is a JWS in the flattened JSON
serialization (RFC 7515 section 7.2.2): three members, protected, payload
and signature. Any JOSE library can verify it. Every export is signed with
a fresh key that this realm’s Policy Export Signing CA certifies. That
Issuing CA is a use case of its own on the PKI page. The protected
header carries typ policy-export+json and the whole chain in x5c: the
signing certificate, the Policy Export Signing CA, the realm’s Intermediate
and the service Root. The service keeps no copy of the private key.
pki.policyExportAlgorithm chooses the algorithm: RS256 by default (the
algorithm of the realm’s own JOSE signing key), or PS256, ES256, ES384,
ES512, EdDSA, ML-DSA-44, ML-DSA-65 or ML-DSA-87.
What an import trusts. Check the signer verifies the signature with
the key in x5c and holds the chain to full PKI validation, whatever the
mode: validity, key usage, the path and revocation of every certificate. This
is the policy-signer row of paranoid PKI mode, on by
default, and while it is on the checks run in development mode too. Then:
| The signer | What happens |
|---|---|
| this realm’s own Policy Export Signing CA, under this service’s Root | trusted; Import it writes the document |
| another realm whose chain this realm’s signer truststore holds for policy imports | trusted the same way |
| any other realm, of this service or another | the page shows the chain and asks whether to trust it |
The question. Yes: trust this chain and import adds the chain’s three certificate authorities to this realm’s signer truststore, for policy imports and no other use, and imports the document. The next export from that realm is trusted without asking. The answer names the Issuing CA it was shown. Every realm of one service shares the Root, so trusting the Root alone would trust every realm’s exports. The yes is therefore pinned to that one Issuing CA, and another realm of the same service is still asked about. To withdraw the trust, remove those entries on PKI → Trust.
What is written. Each profile goes through its kind’s own Save. A profile of the same name is replaced, and a profile the document does not carry is left alone. A profile its kind refuses is named with the reason, and the others are still written.
One policy, or a few
A policy is named by its kind and its name: password and default,
passkey and a named policy, authn and one of the named authentication
policies. The same pair names it on this page and to each kind’s Save.
Exporting a selection. Each policy this realm stores has an Export
button on the All profiles tab, and each named authentication policy has
one beside its Delete. It downloads a signed document that holds that one
policy. On the Export and import tab, tick the policies to carry and press
Export this realm’s policies. With none ticked, the export carries every
policy, as before. A selection is the same document with fewer profiles in
it, signed the same way, so any importer reads it. Its payload says which
policies it was asked to hold, in selection. Only what the realm stores can
be selected, so a profile it inherits cannot. A name the realm does not store
is refused with STS-ADMIN-0937, and nothing is exported.
Importing a selection. Check the signer lists every policy in the
document, each ticked, with replaces an existing policy beside a name this
realm already stores. Untick the ones to leave out, then import. With none
ticked, the whole document is imported. The trust question is asked about the
document’s signer before anything is written, whatever is ticked. A selected
name the document does not carry is refused with STS-ADMIN-0938 before the
question, and nothing is trusted or written.
Through the API: POST /admin-api/policies/transfer/export, inspect and
import. Another realm’s import answers 400 with needsTrust until it is
posted again with trustSigner: true and issuerFingerprint, the Issuing
CA’s SHA-256 fingerprint from the inspection. Export and import each take an
optional policies, a list of { "kind": …, "name": … }; left out, they act
on everything. The inspection’s profiles lists what the document carries,
each with replaces. GET /admin-api/policies/transfer lists what this realm
can export in policies. Export, the yes and the import each write an audit
row: admin.policies.export, admin.policies.trust-signer and
admin.policies.import. A selection’s export and import rows record the
policies it named.
What this realm signs with, and whom it trusts. The tab, and
GET /admin-api/policies/transfer, show the algorithm the next export is
signed with, whether pki.paranoidPolicySigner is on, this realm’s Policy
Export Signing CA, and the signer truststore’s entries for policy imports.
The CA is shown with its subject, its validity and its SHA-256 fingerprint,
the value another realm’s administrator names to trust this realm’s exports.
The answer also carries the CA’s x5t#S256 and its chain up to the service
Root, without the Root itself. The entries are the other realms this realm
has said yes to. The CA is missing until the realm’s first export creates it,
and reading the tab or the API does not create it. The answer holds
certificates only, never a private key.
In the running service
- Console: Directory → Policies,
/admin/policies. A tab per kind, then Export and import and All profiles. - API:
GET /admin-api/policies.POST /admin-api/policies/save-<id>-policyandreset-<id>-policy, with<id>from the table above.save-named-authn-policyanddelete-named-authn-policyfor a named authentication policy.POST /admin-api/groups/set-policyto point a group at one.POST /admin-api/applications/setto point an application at one.POST /admin-api/users/set-attributeto point a person at one. - Who names a profile is
namedByon each named row ofGET /admin-api/policies.