This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.

Abstract data model

The abstract model describes this service’s data once, in TypeSpec, under models/, in namespaces that stay apart: a directory entry is not an API body, and neither is a PostgreSQL row.

The model is the source. Every directory object with a published table is written in it: applications, roles, devices, service accounts, SPIFFE registrations, XACML policies and enforcement points, federation relationships, and the seven kinds of policy. The service reads what the image build generates from it. A policy’s settings are there too: their types, defaults, limits, and labels. So are people, groups, the registers that keep one JSON value, and the directory’s lists of attribute spellings and of the attributes it withholds. The PostgreSQL and MariaDB tables and indexes are too, and they generate both the statements the service runs and the scripts an owner runs. So are all five OpenAPI documents. Each object switched only after what the model generated was shown to be the same as what was there. One thing is still to come: this service’s own OIDs, below, are placeholders.

The current state: code and SQL are read into TypeSpec, the compiler checks it, and what it generates is compared with the code and SQL it came from

Select the diagram for full size.

What is generated from the compiled model

Output From compiled TypeSpec How it is checked Used by the service
The 15 switched tables, and policy settings Yes, and TypeSpec is the source Byte-identical to the tables they replaced Yes
RFC 4512 definitions, for names with an OID Yes Against the RFC text No
Directory and table classes, with validators Yes Compiled and run No
Domain concept classes, and types for every API request and response Yes Compiled, and each concept held to real entries and records Yes
Request validators for the Account API and Authentication API Yes, from the documents the service serves The refusal and the document are one declaration Yes
PostgreSQL tables and indexes, and postgres/schema.sql Yes, and TypeSpec is the source The same statements as those they replaced Yes
MariaDB tables and indexes, and mariadb/schema.sql Yes, and TypeSpec is the source The same statements as those they replaced Yes
All five OpenAPI documents Yes, and TypeSpec is the source Equal to the documents they replaced Yes

Changing what a directory object holds

The attributes of an application entry are defined in models/directory/application.tsp, and those of every other object with a published table in that object’s file beside it, such as role.tsp or policy_password.tsp. To add an attribute, or to change one, edit the file: each attribute is a property with an @attr decorator that says how many values it holds, where it comes from, and what it means. The decorator’s keys are fixed, so a misspelled key stops the build.

The image build compiles the model and generates one file per object under models/generated/, and the service reads those files when it starts. They exist only inside an image. A tree without them does not start and says why (STS-CORE-0093), and a model that does not compile fails the build.

The compiler runs in the build and in the tests. It is not in the image that ships, and neither are the .tsp files.

How an object switches

Each directory object moved to the model the same way:

  1. The object’s table is written out once as TypeSpec, with its comments.
  2. The build generates the table from that TypeSpec.
  3. The generated table is compared with the original. It has to be the same.
  4. Only then is the original removed, and the TypeSpec becomes the source.

The models, written out

Directory models is every directory model in reading form: the container, the object classes, and each attribute, with how many values it holds and where the name comes from. Persistence models is every PostgreSQL table in the model, column by column. The API models are under models/api/, and the OpenAPI reference is their reading form.

The directory and persistence pages are rewritten whenever their TypeSpec is written. On a checkout that command is tests/tools/regenerate-model-docs.sh. Do not edit the generated pages by hand.

Directory

The directory namespace is the domain. An entry in the embedded directory is where a person, an application, or a policy is stored. The model is the object: its container, its object classes, and its attributes. The directory still enforces nothing. No object class is required, and no attribute syntax is checked when an entry is written. LDAP schema is the explanation of the names. This page does not copy those tables.

An attribute is single-valued, multi-valued, or unspecified when neither its module nor its RFC says. Provenance is one of rfc, oasis-or-other, iya-sts, derived, or unspecified.

An OID, an LDAP syntax, and matching rules are recorded where a published standard defines the name, read from that standard’s text. An object class also records its kind, its superiors, and its MUST and MAY lists.

This service’s own names are numbered in models/directory/oid_register.json. Those OIDs currently begin 1.3.6.1.4.1.32473, the enterprise number RFC 5612 reserves for documentation. They are placeholders and will change when this service’s own Private Enterprise Number is assigned.

Each object’s container, classes, and attributes are listed on Directory models.

A service account is a person-shaped entry under ou=users. The service-account policy is a different object, policy.serviceAccount. Password-policy attributes that live on the person, such as pwdHistory, stay a second list on policy.password. They are not copied onto the policy entry.

People, groups, attribute sources, and the operational attributes have no SCHEMA module. Their shapes are the catalogue behind People, LDAP schema, and the group page. memberOf is operational and derived from member. An attribute source is one JSON value, stsAttributeSourceData.

The directory does not load a schema when it answers.

The service reads an entry through the concept that names it (see Domain concepts), and a stored value that is not in its type’s canonical form reads as absent rather than guessed: a boolean is TRUE or FALSE in any case, an integer is digits with an optional leading minus, and a time is LDAP Generalized Time in UTC (ending Z). A value written over LDAP as 12abc where a counter belongs is therefore treated as not set.

What the application’s entry states as structure

The @entry in models/directory/application.tsp names what the attribute rows do not call out as structure:

  • the key, appIdentifier
  • the derived subject, urn:sts:application:<appIdentifier>, which is not an attribute
  • registration, the declared protocol, and the protocol that was seen
  • the relationships to roles, policies, federation, and fine-grained authorization
  • the application secrets the SCHEMA withholds

A name it uses is a name common/applications.js already publishes, except a derived name, which must not be an attribute. Applications is the page for what those fields mean.

Domain concepts

models/domain/ says what each thing MEANS, separately from how it is stored. A concept such as User, Credential, Application, OAuthClient or Session names each field and where it is held, and the build refuses a directory attribute that no concept reads. A credential is its own concept, so passing a User around cannot carry one. Classes for the concepts and types for every API request and response are generated from the model.

API

The API namespace is the service’s five OpenAPI documents, written as TypeSpec under models/api/. Compiling those files gives each document back, and a test requires it to equal the one the service serves.

All five have switched: their files under models/api/ are the source, and the service serves and validates against what the image build generates. To change an operation or a schema, edit its file. The OpenAPI reference is their reading form.

Document What it is
Management API OpenAPI document /admin-api, the console’s operations for a machine
Admin Console API OpenAPI document the console’s own operations
Account API OpenAPI document /account-api, the portal
Authentication API OpenAPI document /authn-api, the sign-in screens
Reports API OpenAPI document /report-api

Persistence

The persistence namespace holds the PostgreSQL and MariaDB schemas, one file per engine under models/persistence/, because the two differ in types, keys, and indexes. Each table is a model and each column carries its SQL type and clauses. The build generates the statements the service runs and the script an owner runs from them.

To change a table, edit its model and run tests/tools/regenerate-model-docs.sh, which writes postgres/schema.sql and mariadb/schema.sql. Everything else in those scripts is in the templates beside the models. A column added after a table first shipped is marked in the model, and the statement giving an existing database that column is generated. Other upgrades, such as a change of key, are steps between two versions and stay in the driver.

Directory attributes do not become columns. One directory entry is one row of sts_ldap_entries, with the attributes sealed in attrs. Four lookup columns name attributes the SQL already states: name_keys is uid, mail_keys is mail, uuid_keys is entryUUID and stsEntryUuidAlias, and class_keys is objectClass.

PostgreSQL schema describes the tables. Persistence describes what survives a restart.