What this is about
Every tenant has a key, for example nordbau or stadtwerke-nord. The key is the name by which the whole system knows the tenant:
- It is in the token, as the attribute
tenantor as the alias of the organization. - It is the name of the tenant’s database.
- It is what the tenant gate asks CIAS about.
Besides that, a tenant has a display name (displayName), for example “Nordbau GmbH”. People read it. If it is missing, CIAS shows the key.
The rules
| Rule | Reason |
|---|---|
only lowercase letters a–z, digits 0–9 and hyphen - | These are the characters CDMS accepts as database names. CDMS checks them again right before the CREATE DATABASE |
| at least one character | an empty name names nothing |
| at most 64 characters | MySQL does not allow more for a name |
not system and not single | CDMS uses these names itself: system is the system database, single the one database in SINGLE operation. A tenant with such a name would end up there |
| unique in the whole installation | one database per tenant; the table cias_tenant enforces this with a uniqueness constraint |
| immutable | see above; there is no endpoint that changes it |
CIAS checks these rules already when a tenant is created, not only when the database is set up. Otherwise there might already be an organization in Keycloak before the name fails at the database.
| Key | Result |
|---|---|
nordbau | valid |
stadtwerke-nord-2 | valid |
system | invalid, reserved |
Nordbau | invalid, uppercase letter |
nord_bau | invalid, underscore |
müller | invalid, umlaut |
| 65 characters long | invalid, too long |
An invalid key when creating results in 400 cias.tenancy.invalid-request, and the message says which rule is broken. A key that is already taken results in 409 cias.tenancy.key-already-used.
Display name instead of renaming
Companies change their names. That is what the display name is for: It may contain anything, including umlauts and spaces, and it is not part of any database. “Nordbau GmbH” can later become “Nordbau Holding GmbH”, and the key stays nordbau.
You can set the display name through the admin API when creating. There is no separate endpoint to change it.
How the key is built during a self-registration
During a self-registration, a person fills in a form. The form does not ask for a database name. That is why CIAS builds the key itself if neither the configuration of the flow nor a hook names one.
-
CIASChoose sourceField
companyfilled in? Otherwise the domain of the email address without its ending↳ no no source → registration fails with a configuration error -
CIASTransformremove accents, lowercase, turn all other characters into
-, at most 48 characters↳ no nothing usable left → configuration error -
CIASFree?Does the key exist already, or is it reserved? Then append
-2,-3… up to-20. The company “System” thus becomessystem-2↳ no all taken → configuration error - Key for the new tenant
When: The form contains company: "Café Ruiz & Söhne".
Accents are removed, not spelled out: é becomes e, ö becomes o, not oe. & and spaces become a single hyphen.
Result: cafe-ruiz-sohne
When: No company name, address anna@muster-bau.de.
CIAS takes the domain without its last ending. The part before the @ is never used: info or d.mertins would either be the same for many customers or named after a single person.
Result: muster-bau; example.co.uk would become example-co
When: muster-bau already exists.
CIAS tries muster-bau-2, then muster-bau-3 and so on up to -20. That is why the stem is limited to 48 characters: This way the suffix still fits into the 64.
Result: muster-bau-2
When: An installation wants a different rule, for example ue instead of u for ü, or a customer number.
It provides its own bean of type TenantKeyFactory. CIAS then uses this one instead of the built-in one. The suffix -2 to -20 and the rule check still run.
Result: If the custom rule returns an invalid key, the registration fails with a configuration error.
“Free?” is checked at registration, but the tenant is only created once the person has confirmed their address, so minutes or days later. If two registrations take the same key during this time, the second one fails because of the uniqueness constraint. CIAS does not reserve a name for a registration that may never be confirmed.
Pitfalls
Next
- Create and provision a tenant
- How registration chooses the tenant: Where the tenant comes from
- What CDMS does with the key: Which database? The persistence target