User Field Settings

Configure what information users provide during registration and how it's stored.

Benefits

• Flexible User Identification: Email, mobile_number, and username can be used to identify users. Custom fields with USERNAME data type can also be used as alternative login identifiers.
• Customizable Field Structure: Configure field types, validation rules, and permissions to match your business requirements.
• Token Integration: Map fields to OAuth scopes to control which user data is included in tokens.
• Important Considerations:
  • Field Key cannot be changed after creation - choose carefully
  • Data Type can only be changed if the new type is compatible with the current one

Fields Explained

Fields define what information users provide during registration and how it's stored. The cidaas Admin Dashboard provides a visual interface for configuring field settings.

Registration Page Fields are the fields that appear on the registration form for end users. These fields can be configured based on your business requirements, including:

• Field Key: Unique identifier for the field (cannot be changed after creation)
• Field Type: Determines the input format and validation (see field types below)
• Status: Whether the field is enabled or disabled
• Permissions: Whether the field is required, read-only, internal, or unique
• Scopes: Which OAuth scopes the field belongs to (controls token inclusion)

Registration Page Fields can be accessed on the cidaas Admin dashboard under Settings > Registration field settings.

The following table view displays all configured fields:

Field Structure

A field setting consists of:

• a dataType to be able to express semantics on a field and give hints for visual presentation
• options to set editability and visibility of a field: required, internal, readonly
• options to use in resp. tokens using scopes
• grouping and ordering fields applying a virtual grouping by setting the parent_group_id for those fields you would like to add to the GROUPING field. ordering of fields to give fields an order in UI
• setting field ranges with a fieldDefinition
• localize the fieldKey and editing hints in various localeTexts

Field Setting can contain groups with the data type GROUPING which is used to group the Field Setting parameters that cannot be used directly for custom fields.

In addition to the default fields, cidaas lets you create and define custom registration page fields based on your business requirements.

To create or configure a custom field, navigate to Settings > Registration field settings in the cidaas Admin Dashboard and click Create Field.

Field Types

Field Type	Description	Use Case
TEXT	Text input	Names, descriptions
EMAIL	Email address	User email (validated)
MOBILE	Phone number	Mobile number (validated)
PASSWORD	Password field	User password (masked)
NUMBER	Numeric value	Age, quantity
DATE	Date and time	Birth date, event date
URL	Web link	Website, profile link
TEXTAREA	Multi-line text	Description, notes
SELECT	Dropdown selection	Single choice from options
MULTISELECT	Multiple selections	Multiple choices from options
RADIO	Radio buttons	Single choice (mutually exclusive)
CHECKBOX	Checkbox	Yes/No, true/false
CONSENT	Consent acceptance	GDPR consent tracking
USERNAME	Custom identifier	Alternative login identifier
ARRAY	Array of strings	List of values
JSON_STRING	JSON data	Structured data

For SELECT, MULTISELECT, RADIO: Define the options (key-value pairs) users can choose from.

For DATE: Set date range (min/max dates).

For GROUPING: A special datatype used to create groupings of fields. Cannot store values, only used for UI organization to group related fields together. Can be used with Remote Fields to fetch data from external APIs.

Base Data Types

Since dataTypes reflect either a user interface type (like RADIO, TEXTAREA) and/or add semantics to the data (like PASSWORD, URL, EMAIL, CONSENT), the baseDataType is used to map the data to programming language data types and how data gets stored in databases (e.g., MongoDB, Elasticsearch).

Data Type	Base Data Type	Description
TEXT	string	Text field with optional min/max length constraints
NUMBER	double/integer	Numeric field
RADIO	string	Predefined values, selected value saved as string
CHECKBOX	boolean	Binary value stored as boolean
PASSWORD	string	Text field with min/max length constraints
DATE	datetime	Date with optional min/max date constraints
URL	string	Text field that must match URL format
EMAIL	string	Text field that must match email format
TEXTAREA	string	Multi-line text field
MOBILE	string	Text field that must match mobile number format
CONSENT	boolean	Binary value used to store consent
JSON_STRING	string	Text field for JSON data with optional min/max length
USERNAME	string	Text field for unique user identifiers
ARRAY	array[string]	Array of strings without predefined values
SELECT	string	Predefined values, selected value saved as string
MULTISELECT	array[string]	Predefined values, multiple selections saved as array of strings
DAYDATE	datetime	Date without time component (day/month/year only)
GROUPING	(none)	Note: GROUPING has no baseDataType. Special datatype for grouping fields. Cannot store values, only used for UI organization

4. Scopes: Select which OAuth scopes this field belongs to.

Scopes in Fieldsetup

What are Scopes?

Scopes control which fields are included in tokens. When an application requests specific scopes, only fields mapped to those scopes are returned.

How Scopes Work

• One field can be assigned to multiple scopes (e.g., Date of Birth in both "profile" and "personal" scopes)
• Multiple fields can share the same scope (e.g., First Name, Last Name, and email all in "profile" scope)
• When an application requests "profile" and "payment" scopes, only fields mapped to these scopes are included
• Fields without scopes are not included in tokens

Scope Model

The scope management system consists of three interconnected entities:

┌─────────────────────────────────────────────────────────────────┐
│                         SCOPE MODEL                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────┐    assigned to    ┌─────────────┐                │
│  │  Scope   │◄──────────────────►│   Field     │                │
│  └──────────┘   many-to-many     └─────────────┘                │
│       │                                 │                        │
│       │ requested by                    │ included in            │
│       ▼                                 ▼                        │
│  ┌──────────────┐           ┌─────────────┐                    │
│  │ Application  │───────────►│    Token    │                    │
│  │              │  requests  │  (claims)   │                    │
│  └──────────────┘            └─────────────┘                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Key Relationships:

• Scope ↔ Field: Many-to-many relationship - one scope can include multiple fields, one field can belong to multiple scopes
• Application → Scope: Applications request specific scopes during authentication
• Scope → Token: Only fields mapped to requested scopes are included as claims in the token

Example:

• Field "email" mapped to scopes: ["email", "profile"]
• Field "credit_card" mapped to scope: ["payment"]
• Application requests scope: "profile" → Only "email" is returned (not "credit_card")

For more information, refer to Scope Management

5. Permissions: Select one or more permissions:

Permission	Description
Enable	Field is visible on the registration form
Required	Field is mandatory - user must provide input
Read Only	Field can be viewed but not changed by users
Internal	Field is hidden from users (admin only)
Unique	Field values must be unique across all users (e.g., employee ID)

Permissions change depending on the field type selected.

6. Localization (optional): Configure field labels and hints in different languages.

   The LocaleText structure provides localized labels and messages for a field. Each FieldSetup must have at least one LocaleText entry. Several LocaleText attributes are directly related to FieldDefinition attributes and provide localized messages for the corresponding validation constraints.

   Attribute	Type	Required	Related FieldDefinition	Description
   locale	string	Yes	-	Locale identifier (e.g., en, de, en-US, de-DE)
   name	string	Yes	-	Localized display name of the field
   minLength	string	No	minLength	Localized validation message when value is below minimum length
   maxLength	string	No	maxLength	Localized validation message when value exceeds maximum length
   required	string	No	-	Localized message shown when required field is empty
   matchWith	string	No	matchWith	Localized error message when field values don't match the referenced field
   error	string	No	regex	Localized error message displayed when regex validation fails
   attributes	KeyValue[]	Conditional	attributesKeys	Localized display values for each key in attributesKeys. Required for SELECT, RADIO, MULTISELECT
   consentLabel	ConsentLabel	No	-	Localized label and text for CONSENT type fields

   Note: For SELECT, RADIO, and MULTISELECT datatypes, the attributes array must contain a localized value for each key defined in FieldDefinition.attributesKeys.

7. Validation Rules (optional):

   The Field Definition defines constraints and validation rules for a field. Different attributes apply depending on the dataType:

   Attribute	Type	Applicable DataTypes	Description
   minDate	datetime	DATE, DAYDATE	Minimum allowed date value
   maxDate	datetime	DATE, DAYDATE	Maximum allowed date value
   initialDate	datetime	DATE, DAYDATE	Default/initial date value
   initialDateView	string	DATE, DAYDATE	Calendar view hint for UI: month, year, or multi-year
   minLength	integer	NUMBER, PASSWORD, URL, EMAIL, TEXTAREA, JSON_STRING, USERNAME	Minimum length of field value (default: 0)
   maxLength	integer	NUMBER, PASSWORD, URL, EMAIL, TEXTAREA, JSON_STRING, USERNAME	Maximum length of field value (default: 200)
   matchWith	string	TEXT, NUMBER, PASSWORD, URL, EMAIL, TEXTAREA, JSON_STRING, USERNAME	fieldKey of another field whose value this field must match (e.g., password confirmation)
   attributesKeys	string[]	SELECT (required), RADIO (required), MULTISELECT (required)	Keys for predefined selection options
   regex	string	TEXT	Regular expression pattern for field validation

   Validation Rules:

   • Date constraints: If both minDate and maxDate are set, minDate must be before maxDate. If initialDate is set, it must be between minDate and maxDate.
   • Length constraints: minLength must be less than maxLength. Both must be >= 0. Default values: minLength=0, maxLength=200.
   • Regex vs Length (TEXT datatype): For TEXT datatype, minLength/maxLength are deprecated. Use regex instead. You can specify either regex or minLength/maxLength, but not both.
   • Selection types: For SELECT, RADIO, and MULTISELECT datatypes, attributesKeys is required and must contain at least one key. Each key must have a corresponding localized value in LocaleText.attributes.

8. Click Save.

Important When you try to create a Field Setting that already exists, a notification window with the message "This Registration Field already exists" appears as shown below. The Field Key of a Field Setting must be unique.

System and Custom Fields

User fields are assigned to the user account:

1. system fields "SYSTEM" - you can find in the identities of the user account
2. custom fields "CUSTOM" - you can find in user accounts customFields section

System fields are predefined fields that can be enabled or disabled in their field settings.

fieldKey	dataType	enabled	scopes
email	EMAIL	yes	email, profile
given_name	TEXT	yes	profile
family_name	TEXT	yes	profile
password	PASSWORD	yes
password_echo	PASSWORD	yes
mobile_number	MOBILE	yes	phone
phone_number	MOBILE	no	phone
birthdate	DAYDATE	no	profile
middle_name	TEXT	no	profile
nickname	TEXT	no	profile
preferred_username	TEXT	no	profile
username	USERNAME	no
profile	URL	no	profile
picture	URL	no	profile
website	URL	no	profile
gender	TEXT	no	profile
locale	TEXT	no	profile
address	GROUPING	no	profile
formatted	TEXT	no	profile
street_address	TEXT	no	profile
locality	TEXT	no	profile
region	TEXT	no	profile
postal_code	TEXT	no	profile
country	TEXT	no	profile

How System Fields and Custom Fields Differ

The differences between the Custom and Default Field Settings are shown in the following table:

Characteristic	System Field	Custom Field
Field Setting	YES ("fieldType" : "SYSTEM")	YES ("fieldType" : "CUSTOM")
Can be activated and deactivated?	YES	NO
Predefined Datatype	YES (modelled in SocialIdentity)	YES
Can be added?	NO	YES
Can be removed?	NO	YES
Can be individually grouped?	NO	YES

Remote Fields

Remote Fields is a feature that allows field values to be fetched from an external API. This is configured on fields with dataType: GROUPING, where all child fields under the grouping are populated from the remote API response.

Remote Fields Configuration (GROUPING only)

Remote fields are configured using the remoteFieldSettings object, which is only applicable to fields with dataType: GROUPING:

Attribute	Type	Required	Description
callOnce	boolean	Yes	When true, the API is called only once and the retrieved data is persisted in the user's customFields. Subsequent requests will use the cached data instead of calling the API again for a particular time period
apiClientSetup	object	Yes	Configuration for the external API client including endpoint, protocol, and authentication

System Defaults (not configurable):

• Cache time: Short-term cache duration for remote API responses (system managed)
• Timeout: Request timeout for remote API calls (system managed)

APIClientSetup and APIAccessSetup Structure

The apiClientSetup object defines how to communicate with the external API, including endpoint configuration and authentication.

Important: The communicationEP is recommended to be a GET API endpoint that includes an identifier parameter placeholder. The placeholder can be:

• A user identifier: identifier={{userId}} where userId is replaced with a cidaas user identifier (sub, email, mobile, username, or custom field with dataType USERNAME)
• A custom field reference: identifier={{customFields.fieldKey}} where fieldKey is the key of a custom field (e.g., {{customFields.insuranceNumber}})

The placeholder is replaced at runtime with the actual value before making the API call.

Note: Remote Fields use the same authentication structure as webhooks:

• Authentication Type: Use apiAccessType in apiClientSetup with values APIKEY, TOTP, BASIC_AUTH, GEN_OAUTH2 CIDAAS_OAUTH2`
• Detail Objects: Use separate detail objects based on apiAccessType:
  • apikeyDetails - for APIKEY authentication
  • totpDetails - for TOTP authentication
  • oAuthDetails - for CIDAAS_OAUTH2 and GEN_OAUTH2 authentication
  • basicAuthDetails - for BASIC_AUTH authentication

Auth Type	Security Level	Description
APIKEY	low	The pre-shared API key which has to be verified by the remote API
TOTP	medium	The time-based one-time-password (TOTP) generated with the TOTP key that is provided
BASIC_AUTH	medium	Basic authentication using username and password credentials for the remote API
CIDAAS_OAUTH2	high	Security with client credentials grant flow where pre-defined scopes should be set in the remote API service. Since the clientId is not shared with anyone and scopes can be applied, it could be considered the most secure
GEN_OAUTH2	high	Security with client credentials grant flow that requires a well-known client secret and scopes that should be requested from the remote API service

For detailed specification of APIClientSetup and authentication detail structures, see the API Access Specification.

Remote API Requirements

The remote API must fulfill the following requirements:

Requirement	Description	Example
HTTP Method	Recommended to be a GET endpoint	GET https://api.example.com/data
Identifier Parameter	The URL must contain an identifier parameter with a placeholder that will be replaced at runtime	https://myexternal-service.de?identifier={{customFields.insuranceNumber}}
Placeholder Formats	User identifier: identifier={userId} Replaced with: sub, email, mobile, username, or custom field with dataType USERNAME Custom field: identifier={{customFields.fieldKey}} Replaced with: actual value from user's custom field	identifier={userId} identifier={{customFields.insuranceNumber}}
Response Format	Must return a JSON object with field keys matching the child fields of the grouping	{ "fieldKey1": "value1", "fieldKey2": "value2"}
Authentication	Must accept one of the supported apiAccessType values defined in apiClientSetup	APIKEY, TOTP, or CIDAAS_OAUTH2

Note: At runtime, placeholders like {{customFields.insuranceNumber}} will be replaced with the actual value from the user's customFields.insuranceNumber field.

Access Token Payload Configuration

To use remote fields, the grouping field must be configured in the additional access token payload. This ensures that when a token is issued, the system knows which remote field groupings need to be resolved.

Data Flow Overview

┌─────────────────┐     ┌─────────────────┐     ┌──────────────────┐
│   User Login    │────▶│    token-srv    │────▶│  Check Grouping  │
└─────────────────┘     │ (token request) │     │  remoteFieldSettings?  │
                        └─────────────────┘     └────────┬─────────┘
                                                         │
                                ┌────────────────────────┴─────────────────────────────┐
                                │                                                      │
                                ▼ YES                                                  ▼ NO
                        ┌───────────────────┐                                   ┌───────────────┐
                        │ Check callOnce?   │                                   │ No fields     │
                        └─────────┬─────────┘                                   │ returned      │
                                  │                                             └───────────────┘
                ┌─────────────────┴─────────────────┐
                │                                   │
                ▼ callOnce: true                    ▼ callOnce: false
        ┌───────────────────────┐           ┌───────────────────────┐
        │ Check user customFields│           │ Authenticate         │
        │ for persisted data    │           │ (apiAccessType)           │
        └───────────┬───────────┘           └───────────┬───────────┘
                    │                                   │
        ┌───────────┴───────────┐                       │
        │                       │                       │
        ▼ Data exists           ▼ No data               │
┌───────────────────┐   ┌───────────────┐               │
│ Use persisted     │   │ Authenticate  │               │
│ customFields for  │   │ (apiAccessType)   │               │
│ token payload     │   └───────┬───────┘               │
└───────────────────┘           │                       │
                                │                       │
                                ▼                       ▼
                        ┌───────────────────┐   ┌───────────────────┐
                        │ Call Remote API   │   │ Call Remote API   │
                        └───────────┬───────┘   └───────────┬───────┘
                                    │                       │
                                    ▼                       ▼
                        ┌───────────────────────┐   ┌───────────────────────┐
                        │ Persist data in user  │   │ Use data for          │
                        │ customFields          │   │ token payload         │
                        └───────────┬───────────┘   └───────────────────────┘
                                    │
                                    ▼
                        ┌───────────────────────┐
                        │ Use data for          │
                        │ token payload         │
                        └───────────────────────┘

Error Handling and Logging

Important: If a remote field is not returned in the API response payload, the field will not be added to the token. This is silent behavior - the token will simply not contain that field.

Proper logging must be implemented for:

• Failed requests: Log when the external API returns an error response (4xx, 5xx status codes)
• Timed out requests: Log when the external API does not respond within the configured timeout
• Missing fields: Log when expected fields are not present in the API response
• Authentication failures: Log when the API authentication fails (OAuth2 token generation, invalid API key, etc.)

Example: Remote Field Setup for GROUPING

Example with CIDAAS OAuth2 Authentication:

{
  "fieldKey": "external_customer_data",
  "dataType": "GROUPING",
  "fieldType": "CUSTOM",
  "enabled": true,
  "is_group": true,
  "remoteFieldSettings": {
    "enabled": true,
    "callOnce": true,
    "apiClientSetup": {
      "communicationEP": "https://myexternal-service.de?identifier={{customFields.insuranceNumber}}",
      "protocol": "HTTPS",
      "httpMethod": "GET",
      "apiAccessType": "GEN_OAUTH2",
      "oAuthDetails": {
        "client_id": "my-client-id",
        "client_secret": "my-client-secret",
        "req_scopes":"ext:customservice_read",
        "wellknownUrl":"https://auth.extidp.com/.well-known"
      }
    }
  }
}

Note: At runtime, {{customFields.insuranceNumber}} will be replaced with the actual value from the user's customFields.insuranceNumber field. Alternatively, you can use identifier={userId} to use a user identifier (sub, email, mobile, username).

Example with API Key Authentication:

{
  "fieldKey": "external_data",
  "dataType": "GROUPING",
  "fieldType": "CUSTOM",
  "enabled": true,
  "is_group": true,
  "remoteFieldSettings": {
    "callOnce": false,
    "apiClientSetup": {
      "communicationEP": "https://api.example.com/data?identifier={userId}",
      "protocol": "HTTPS",
      "httpMethod": "GET",
      "apiAccessType": "APIKEY",
      "apikeyDetails": {
        "apikey": "your-api-key-value",
        "apikey_placeholder": "X-API-Key",
        "apikey_placement": "header"
      }
    }
  }
}

Child fields under this grouping (with parent_group_id: "external_customer_data") will be populated from the remote API response.

Technical Integration

The field setup can also be managed using the field setup API.

API	Description	Link
Store a field setup	Create or update a field setup	API Reference
Find field setups	Search fields using graph filters	API Reference
Get field setup	Get field setup by fieldKey	API Reference
Delete field setup	Delete field setup by fieldKey	API Reference
Update field order	Update registration field order	API Reference

Capturing User Consents during Registration

Consents provide a legal basis to collect and use personal data from users. One place where companies may choose to collect consent according to the GDPR is on the registration page of an application.

In the registration flow, a business is not only collecting attributes like name and email, but also meets business requirements. Assuming that a company is using consent as a basis to collect personal data and use it for security & analytics, when an individual opts in, the form collects the given consent as an attribute from the individual to track who has consented.

It's important to note how consent flows can be designed. You can add/edit consents during registration and login. Learn more about Consent Management.