What this is about
Self-registration is the public way to an account: someone fills in a form without being signed in. In the variant SELF_SERVICE the person usually founds a new tenant for their company and becomes its first person.
The flow
sequenceDiagram
participant B as User
participant C as CIAS
participant K as Keycloak
participant M as Email
B->>C: POST /cias/registration/self<br/>email, first name, last name, company
C->>C: throttling, check fields
C->>K: create account disabled
C->>M: email with verification link
C-->>B: 202 accepted
B->>C: clicks the link (POST /verify)
alt approval needed
C->>M: “Your registration is being reviewed”
Note over C: waits for a platform administrator
end
C->>K: enable account
C->>K: organization for the new tenant
C->>C: create tenant
C->>K: membership and founder roles
C->>M: welcome email
The form
GET /cias/registration/flows/SELF_SERVICE/form returns which fields exist. In the shipped configuration of cias-runtime:
| Field | Required | What for |
|---|---|---|
email | yes | the address, which is also the account |
firstName, lastName | no | name on the account |
company | yes | name of the new tenant and source of its key |
application | no | which user interface the person comes from. Selects the email template and links |
The request can also send consents (consents) and a language (locale). There is no password field. Fields that the flow does not know are rejected.
POST /cias/registration/self
{
"email": "anna@nordbau.example",
"fields": { "firstName": "Anna", "lastName": "Berg", "company": "Nordbau GmbH" },
"locale": "de"
}202
{ "status": "accepted" }The variants
When: There is no account for the address yet.
CIAS creates the account in Keycloak disabled and unverified and sends the email VERIFY_EMAIL with the link.
Result: See Verify the email.
When: The address already belongs to an active, verified account.
CIAS creates no new account and changes nothing on the existing one, not even the password. Instead of the verification email, the person gets a different email. The answer to the form is the same as for a new address.
Result: See The email is the account.
When: The flow requires an approval (approval-required: true).
After the click the registration moves to PENDING_APPROVAL, and the person gets the email APPROVAL_PENDING. It continues only when a platform administrator approves. In cias-runtime approval is on by default (CIAS_SELF_SERVICE_APPROVAL), in the hub it is off by default.
Result: See Approval by an administrator.
When: approval-required: false
Provisioning starts right after the click.
Result: The welcome email arrives a few seconds after the click.
When: The shipped setting for SELF_SERVICE.
The tenant key is made from the field company: umlauts and accents become base letters, everything is lowercase, other characters become -, at most 48 characters. “Nordbau GmbH” becomes nordbau-gmbh. If the key is already taken, CIAS tries nordbau-gmbh-2 up to -20. During provisioning the organization and the tenant are then created, and the person becomes the founder with the founder roles.
Result: See Where the tenant comes from and Initial roles as a rule set.
When: An installation sets tenant-assignment: NONE.
No tenant is created. The person gets the roles of the situation TENANTLESS.
Result: The field company is then not needed.
Protecting the public form
Because the form can be reached without signing in, it always answers the same way and is throttled: at most a certain number of attempts per address in a time window (in cias-runtime 10 in 10 minutes). Details in Protecting the public endpoints.