Single IA Node Reference
This Single AI Node Reference section describes the components, configuration, runtime interfaces, and operational characteristics of a single Integration Architecture (IA) node.
It is intended to be used alongside:
This document does not provide step-by-step instructions or architectural rationale.
It is a reference surface for configuration, inspection, and troubleshooting.
Components
| Component |
Purpose |
| Cognito Local |
Local identity provider emulator that issues JWTs |
| ianode-access |
Access service that exposes user attributes and group membership |
| MongoDB |
Persistence store for access service data |
| Secure Agent Graph |
Secure RDF graph runtime |
| rdf-abac |
Attribute-based access control policy evaluation engine |
| jwt-servlet-auth |
JWT validation and decoding library |
| graphql-jena |
GraphQL interface for RDF data |
| jena-fuseki-kafka |
Kafka-based RDF ingestion |
| fuseki-yaml-config |
Externalised configuration support for Fuseki |
Runtime Services and Default Ports
| Service |
Default Port |
Notes |
| Cognito Local |
9229 |
Identity provider emulator |
| ianode-access API |
8091 |
Attribute resolution and /whoami |
| Secure Agent Graph |
3030 |
Upload, SPARQL, and GraphQL |
| MongoDB |
27017 |
Used by ianode-access |
| Kafka |
9092 |
Optional event ingestion |
Ports may be overridden by configuration or container settings.
Node Runtime Modes
Secure Agent Graph supports multiple runtime modes, selected via configuration files.
| Mode |
Description |
| Minimal |
Graph runtime only, no authentication or access control |
| Secure |
JWT validation and ABAC enforcement enabled |
| Secure + GraphQL |
Secure mode with GraphQL API enabled |
| Secure + Kafka |
Secure mode with Kafka ingestion enabled |
Environment Variables
Identity and Security
| Variable |
Required |
Description |
| USER_ATTRIBUTES_URL |
Yes |
Base URL of the access service |
| JWKS_URL |
Yes (secure modes) |
JWKS endpoint used to verify JWT signatures |
| OPENID_PROVIDER_URL |
Yes (access service) |
Identity provider URL |
| CLIENT_ID |
Yes |
App client identifier used for token validation |
| GROUPS_KEY |
No |
JWT claim used to read group membership |
Access Service Behaviour
| Variable |
Required |
Description |
| SCIM_ENABLED |
No |
Enables Cognito Local integration |
| DEPLOYED_DOMAIN |
No |
Domain used for token validation |
Kafka Integration (optional)
| Variable |
Required |
Description |
| KAFKA_BOOTSTRAP_SERVERS |
Yes |
Kafka broker address |
| KAFKA_TOPIC |
Yes |
Topic used for RDF ingestion |
| KAFKA_GROUP_ID |
No |
Consumer group identifier |
Configuration Files
Configuration files are written in RDF/Turtle format.
| File |
Purpose |
| dev-server-vanilla.ttl |
Minimal graph runtime (no security) |
| dev-server-graphql.ttl |
Secure runtime with JWT, ABAC, and GraphQL |
| dev-server-kafka.ttl |
Secure runtime with Kafka ingestion |
| policy.ttl |
ABAC policy definitions |
| dataset.ttl |
Dataset and named graph configuration |
HTTP APIs and Endpoints
Access Service
| Endpoint |
Method |
Description |
| /whoami |
GET |
Returns identity and group information for the authenticated user |
Secure Agent Graph
| Endpoint |
Method |
Description |
| /ds/upload |
POST |
Upload RDF data |
| /ds |
GET / POST |
Dataset information and SPARQL queries |
| /ds/sparql |
POST |
SPARQL query endpoint |
| /ds/graphql |
POST |
GraphQL query endpoint |
All secure endpoints require:
Authorisation: bearer(JWT)
Security Model (Reference View)
- Authentication is performed using JWT validation
- JWT signatures are verified using the configured JWKS endpoint
- User attributes are resolved dynamically via the access service
- ABAC policies are evaluated during query execution
- Data is filtered dynamically; datasets are not duplicated
- Security enforcement is independent of API type (SPARQL or GraphQL)
Kafka Integration (Optional)
| Item |
Description |
| Ingestion model |
Event-driven RDF ingestion |
| Client tooling |
jena-kafka-client, fk script |
| Metadata directory |
Required for ingestion state persistence |
| Restart required |
Yes, after enabling Kafka configuration |
Common Failure Modes
| Symptom |
Likely Cause |
| 401 Unauthorised |
Missing or invalid JWT |
| 403 Forbidden |
ABAC policy denies access |
| Empty query results |
Attribute-based filtering applied |
| Token decode failure |
Incorrect JWKS_URL or provider URL |
| /whoami crashes |
Missing Authorization header |
| Kafka ingestion stalls |
Missing metadata directory or topic mismatch |
| ClassNotFoundException |
Incomplete build or missing dependencies |
Operational Characteristics
- User pool IDs and app client IDs are generated at runtime and may change when services are reset
- Environment variables are read at service startup
- Secure Agent Graph datasets are in-memory unless configured otherwise
- Restarting the graph clears in-memory data unless persistence is configured
Understanding a single IA node