This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.
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.
In the running service
- Console: Directory → Policies,
/admin/policies. A tab per kind, then 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.