Remote Fields Configuration

Remote Fields is an advanced feature in cidaas that allows field values to be dynamically fetched from an external API during token generation or user profile retrieval.

This configuration is applied strictly to custom fields with dataType: GROUPING.

info

The GROUPING field itself does not hold values. Instead, its child fields (any fields with their parent_group_id set to this grouping's fieldKey) are populated from the remote API response. The remote API response must return a JSON object whose keys map directly to these child field keys.

How it Works

Trigger: When a user logs in, is queried, or a token is generated, the system checks if the requested payload (configured in Additional Access Token Payload) includes the custom GROUPING field or its child fields.
Execution: If configured, cidaas executes an HTTP call to the configured external endpoint (communicationEP) using the specified authentication mechanism (apiAccessType).
Mapping: The response from the external API (expected to be a flat JSON object) is parsed. The values are mapped to the child fields where the key matches the child's fieldKey.
Caching (callOnce):
- If callOnce is true, the fetched data is persisted in the user's customFields object. Subsequent token requests reuse this persisted data until the system cache expires.
- If callOnce is false, the remote API is called dynamically on every token request.

Configuration Properties

The configuration is defined inside the remoteFieldSettings object on a GROUPING field setup:

Property	Type	Required	Description
`callOnce`	boolean	Yes	When `true`, the API response is stored in the user's profile and cached. When `false`, the API is called on every token request.
`apiClientSetup`	object	Yes	Detailed HTTP client setup defining the endpoint, HTTP method, and credentials.

API Client Setup (`apiClientSetup`)

Property	Type	Required	Description
`communicationEP`	string	Yes	The absolute URL of the external API. Supports dynamic runtime placeholder replacement (e.g. `{{sub}}`, `{{customFields.insuranceNumber}}`).
`httpMethod`	string	Yes	HTTP method to call the endpoint. Typically `GET`.
`apiAccess`	object	Yes	Authentication details for calling the external API.

API Access (`apiAccess`)

The apiAccess object defines the authentication type and credentials for the external API. It consists of two main fields:

apiAccessType: The chosen authentication type (one of APIKEY, TOTP, BASIC_AUTH, CIDAAS_OAUTH2, GEN_OAUTH2).
A matching details object containing credentials (e.g. apikeyDetails, totpDetails, basicAuthDetails, oAuthDetails).

Authentication Type (`apiAccessType`)	Description	Required Configuration Object
`APIKEY`	API Key authentication (sent via header or query parameter).	`apikeyDetails`
`TOTP`	Time-based One-Time Password authentication.	`totpDetails`
`BASIC_AUTH`	Standard HTTP Basic Authentication (Username/Password).	`basicAuthDetails`
`CIDAAS_OAUTH2`	OAuth2 Client Credentials grant flow using a client registered on the same cidaas instance.	`oAuthDetails`
`GEN_OAUTH2`	Generic OAuth2 Client Credentials grant flow utilizing an external Identity Provider.	`oAuthDetails`

Configuration Details & Schemas

1. API Key Authentication (`APIKEY`)

Use this when your external service validates requests using a static API key.

"apiAccess": {
  "apiAccessType": "APIKEY",
  "apikeyDetails": {
    "apikey": "your-secret-api-key-value",
    "apikey_placeholder": "X-API-Key",
    "apikey_placement": "header"
  }
}

apikey: The actual API Key value.
apikey_placeholder: The HTTP header name (e.g., X-API-Key, Authorization) or query parameter name.
apikey_placement: Set to "header" or "query".

2. Time-Based One-Time Password (`TOTP`)

Generates and sends a dynamic TOTP code with every request.

"apiAccess": {
  "apiAccessType": "TOTP",
  "totpDetails": {
    "totpkey": "base32-encoded-totp-secret",
    "totp_placeholder": "X-Totp-Key",
    "totp_placement": "header"
  }
}

totpkey: The Base32-encoded secret key used to generate TOTP codes.
totp_placeholder: The HTTP header or query parameter name where the TOTP token will be placed.
totp_placement: Set to "header" or "query".

3. Basic Authentication (`BASIC_AUTH`)

Standard username/password credentials.

"apiAccess": {
  "apiAccessType": "BASIC_AUTH",
  "basicAuthDetails": {
    "user": "api-username",
    "password": "api-password"
  }
}

4. cidaas OAuth2 (`CIDAAS_OAUTH2`)

Performs a client credentials grant flow against the same cidaas tenant.

"apiAccess": {
  "apiAccessType": "CIDAAS_OAUTH2",
  "oAuthDetails": {
    "client_id": "your-cidaas-client-id",
    "req_scopes": "ext:read_data"
  }
}

client_id: The Client ID of the application in cidaas authorized to access the external resource.
req_scopes: Scopes requested during the token generation.

5. Generic OAuth2 (`GEN_OAUTH2`)

Performs a client credentials grant flow against an external token endpoint or openid-configuration.

"apiAccess": {
  "apiAccessType": "GEN_OAUTH2",
  "oAuthDetails": {
    "client_id": "external-client-id",
    "client_secret": "external-client-secret",
    "wellknownUrl": "https://auth.external-provider.com/.well-known/openid-configuration",
    "req_scopes": "read"
  }
}

wellknownUrl: The well-known configuration endpoint URL of the external Identity Provider.
client_id: The Client ID registered on the external Provider.
client_secret: The Client Secret registered on the external Provider.
req_scopes: Space-separated list of scopes to request.

Integration Examples

Example: Creating a Remote Grouping Field

This payload registers a custom grouping field external_customer_data that retrieves data from a remote endpoint using Generic OAuth2 authentication.

{
  "fieldKey": "external_customer_data",
  "dataType": "GROUPING",
  "fieldType": "CUSTOM",
  "enabled": true,
  "remoteFieldSettings": {
    "callOnce": true,
    "apiClientSetup": {
      "communicationEP": "https://api.external-service.com/customers?id={{customFields.insuranceNumber}}",
      "httpMethod": "GET",
      "apiAccess": {
        "apiAccessType": "GEN_OAUTH2",
        "oAuthDetails": {
          "client_id": "my-client-id",
          "client_secret": "my-client-secret",
          "req_scopes": "ext:read",
          "wellknownUrl": "https://auth.external-provider.com/.well-known/openid-configuration"
        }
      }
    }
  }
}

tip

Dynamic parameters such as {{customFields.insuranceNumber}} are replaced at runtime with the actual values stored in the user's profile before making the external API request. You can also use {{sub}}, {{email}}, {{mobile_number}}, or {{username}}.

programmatic Setup using cURL

Ensure you replace ${BASE_URL} with your cidaas domain (e.g. https://your-tenant.cidaas.de) and Bearer <token> with a valid access token containing admin rights to configure field setups.

1. APIKEY Setup

curl --location "${BASE_URL}/fieldsetup-srv/fields" \
  --header "Authorization: Bearer <access_token>" \
  --header 'Content-Type: application/json' \
  --data '{
    "parent_group_id": "DEFAULT",
    "dataType": "GROUPING",
    "fieldKey": "remote_apikey_field",
    "fieldType": "CUSTOM",
    "scopes": ["profile"],
    "localeTexts": [{ "locale": "en-US", "name": "Remote API Key Field" }],
    "remoteFieldSettings": {
      "apiClientSetup": {
        "communicationEP": "https://api.example.com/users?identifier={{sub}}",
        "httpMethod": "GET",
        "apiAccess": {
          "apiAccessType": "APIKEY",
          "apikeyDetails": {
            "apikey": "your-api-key",
            "apikey_placeholder": "X-Api-Key",
            "apikey_placement": "header"
          }
        }
      },
      "callOnce": false
    }
  }'

2. TOTP Setup

curl --location "${BASE_URL}/fieldsetup-srv/fields" \
  --header "Authorization: Bearer <access_token>" \
  --header 'Content-Type: application/json' \
  --data '{
    "parent_group_id": "DEFAULT",
    "dataType": "GROUPING",
    "fieldKey": "remote_totp_field",
    "fieldType": "CUSTOM",
    "scopes": ["profile"],
    "localeTexts": [{ "locale": "en-US", "name": "Remote TOTP Field" }],
    "remoteFieldSettings": {
      "apiClientSetup": {
        "communicationEP": "https://api.example.com/users?identifier={{sub}}",
        "httpMethod": "GET",
        "apiAccess": {
          "apiAccessType": "TOTP",
          "totpDetails": {
            "totpkey": "base32-secret",
            "totp_placeholder": "X-Totp-Key",
            "totp_placement": "header"
          }
        }
      },
      "callOnce": true
    }
  }'

3. BASIC_AUTH Setup

curl --location "${BASE_URL}/fieldsetup-srv/fields" \
  --header "Authorization: Bearer <access_token>" \
  --header 'Content-Type: application/json' \
  --data '{
    "parent_group_id": "DEFAULT",
    "dataType": "GROUPING",
    "fieldKey": "remote_basicauth_field",
    "fieldType": "CUSTOM",
    "scopes": ["profile"],
    "localeTexts": [{ "locale": "en-US", "name": "Remote Basic Auth Field" }],
    "remoteFieldSettings": {
      "apiClientSetup": {
        "communicationEP": "https://api.example.com/users?identifier={{sub}}",
        "httpMethod": "GET",
        "apiAccess": {
          "apiAccessType": "BASIC_AUTH",
          "basicAuthDetails": {
            "user": "api-user",
            "password": "api-password"
          }
        }
      },
      "callOnce": false
    }
  }'

4. CIDAAS_OAUTH2 Setup

curl --location "${BASE_URL}/fieldsetup-srv/fields" \
  --header "Authorization: Bearer <access_token>" \
  --header 'Content-Type: application/json' \
  --data '{
    "parent_group_id": "DEFAULT",
    "dataType": "GROUPING",
    "fieldKey": "remote_cidaas_oauth2_field",
    "fieldType": "CUSTOM",
    "scopes": ["profile"],
    "localeTexts": [{ "locale": "en-US", "name": "Remote Cidaas OAuth2 Field" }],
    "remoteFieldSettings": {
      "apiClientSetup": {
        "communicationEP": "https://your-tenant.cidaas.de/user-srv/users?identifier={{sub}}",
        "httpMethod": "GET",
        "apiAccess": {
          "apiAccessType": "CIDAAS_OAUTH2",
          "oAuthDetails": {
            "client_id": "YOUR_CLIENT_ID",
            "req_scopes": "cidaas:users_read"
          }
        }
      },
      "callOnce": true
    }
  }'

5. GEN_OAUTH2 Setup

curl --location "${BASE_URL}/fieldsetup-srv/fields" \
  --header "Authorization: Bearer <access_token>" \
  --header 'Content-Type: application/json' \
  --data '{
    "parent_group_id": "DEFAULT",
    "dataType": "GROUPING",
    "fieldKey": "remote_gen_oauth2_field",
    "fieldType": "CUSTOM",
    "scopes": ["profile"],
    "localeTexts": [{ "locale": "en-US", "name": "Remote Gen OAuth2 Field" }],
    "remoteFieldSettings": {
      "apiClientSetup": {
        "communicationEP": "https://api.example.com/users?identifier={{sub}}",
        "httpMethod": "GET",
        "apiAccess": {
          "apiAccessType": "GEN_OAUTH2",
          "oAuthDetails": {
            "client_id": "external-client-id",
            "client_secret": "external-client-secret",
            "wellknownUrl": "https://auth.example.com/.well-known/openid-configuration",
            "req_scopes": "openid profile"
          }
        }
      },
      "callOnce": true
    }
  }'

Technical Integration & Schema Reference

For the exact HTTP requests and schema structure, refer to the generated OpenAPI references:

Field Configuration API: Store Field Setup API Reference
Underlying Schemas:
- remoteFieldSettings model
- apiAccess models

How it Works​

Configuration Properties​

API Client Setup (apiClientSetup)​

API Access (apiAccess)​

Configuration Details & Schemas​

1. API Key Authentication (APIKEY)​

2. Time-Based One-Time Password (TOTP)​

3. Basic Authentication (BASIC_AUTH)​

4. cidaas OAuth2 (CIDAAS_OAUTH2)​

5. Generic OAuth2 (GEN_OAUTH2)​

Integration Examples​

Example: Creating a Remote Grouping Field​

programmatic Setup using cURL​

1. APIKEY Setup​

2. TOTP Setup​

3. BASIC_AUTH Setup​

4. CIDAAS_OAUTH2 Setup​

5. GEN_OAUTH2 Setup​

Technical Integration & Schema Reference​