Changes for doc/architecture/register/register.md: 100 added lines, 4 removed lines.
Original line number
Diff line number
Diff line
@@ -2,12 +2,108 @@
## Overview
The Register Service is responsible for user management within the CAPIF ecosystem.
It provides a structured way to register, authenticate, and manage users that interact with CAPIF, ensuring a secure and efficient process.
The Register Service is responsible for user management within the OpenCAPIF ecosystem. It runs as an independent component with its own MongoDB database, separate from the CAPIF Core.
It provides a REST API to register, authenticate, and manage the users that will later interact with CAPIF as Invokers or Providers. It also exposes dynamic configuration management for the Register itself.
All communication with the Register Service is encrypted via TLS, and all administrative endpoints require a valid JWT access token obtained through the `/login` endpoint.
## Architecture
The Register Service is deployed in its own namespace, isolated from the OpenCAPIF Core (Vault NS and OpenCAPIF NS). Communication between the Register and the CCF happens only through HTTPS REST APIs. The CCF's Helper Service exposes a `/deleteEntities/{uuid}` endpoint that the Register calls to clean up all CAPIF entities belonging to a user when that user is deleted.
## API Overview
The Register Service exposes the following groups of endpoints:
Authenticates an administrator using HTTP Basic Auth credentials. On success, returns a JWT access token and a refresh token. The access token must be included as a `Bearer` token in subsequent admin requests and expires after the configured duration (default: 10 minutes).
The admin credentials (`admin_user` and `admin_pass`) are configured in the Register's `config.yaml`.
### `POST /refresh`
Exchanges a valid refresh token (passed as a `Bearer` token) for a new access token. This avoids repeated Basic Auth login by the administrator.
## User Management Endpoints
### `POST /createUser`
Creates a new user in the Register database. Requires a valid admin Bearer token.
On success, returns the generated `uuid` for the new user. The user can then use `/getauth` to obtain their CAPIF access token and the CCF endpoint URLs needed to interact with OpenCAPIF.
### `GET /getauth`
Retrieves the user's authorization information. Uses HTTP Basic Auth with the user's own credentials (not the admin's).
The response includes:
-**`access_token`**: A JWT token the user presents to the CCF to authenticate API calls.
-**`ca_root`**: The CA certificate to verify the CCF's TLS connection.
-**`ccf_api_onboarding_url`**: Endpoint for registering an API Provider.
-**`ccf_publish_url`**: Endpoint for publishing APIs (the `<apfId>` placeholder must be replaced with a real APF ID).
-**`ccf_onboarding_url`**: Endpoint for onboarding an API Invoker.
-**`ccf_discover_url`**: Endpoint for discovering APIs (append the Invoker ID to the query parameter).
-**`ccf_open_discover_url`**: Endpoint for open API discovery (requires only the access token, no invoker onboarding).
-**`ccf_security_url`**: Endpoint for creating security contexts (the `<apiInvokerId>` placeholder must be replaced).
### `GET /getUsers`
Returns a list of all registered users with their profile information. Requires a valid admin Bearer token.
### `DELETE /deleteUser/{uuid}`
Removes a user from the Register by their UUID. Before deleting the user, the Register calls the CCF Helper's `/deleteEntities/{uuid}` endpoint to remove all CAPIF entities (invokers, providers, services, security contexts, event subscriptions) associated with that user. Requires a valid admin Bearer token.
## Configuration Endpoints
The Register Service stores its configuration in a MongoDB collection (`capif_configuration`). These endpoints allow the administrator to retrieve and modify the configuration without restarting the service.
### `GET /configuration`
Retrieves the current Register configuration, including the `config_name`, `description`, `version`, and `settings` (currently `certificates_expiry.ttl_superadmin_cert`).
This endpoint does not require authentication.
### `PATCH /configuration`
Updates a specific configuration parameter by its JSON path. The request body takes a `param_path` (e.g., `settings.certificates_expiry.ttl_superadmin_cert`) and a `new_value`. Requires a valid admin Bearer token.
### `PUT /configuration`
Replaces the entire Register configuration with a new one. The request body must contain the full configuration object (`config_name`, `description`, `version`, `settings`). Requires a valid admin Bearer token.
### `POST /configuration/addNewCategory`
Adds a new category to the configuration settings. The request body takes a `category_name` and `category_values`. This endpoint does not require authentication.
Adds a new parameter inside an existing configuration category. The request body takes a `param_path` (e.g., `certificates_expiry.new_config_ttl`) and a `new_value`. This endpoint does not require authentication.
### `DELETE /configuration/removeConfigParam`
Removes a specific parameter from the configuration by its JSON path. Requires a valid admin Bearer token.
### `DELETE /configuration/removeConfigCategory`
Removes an entire category from the configuration settings. Requires a valid admin Bearer token.
## API Documentation
For more details, refer to the **API documentation**:
For full request and response schemas, refer to the Swagger documentation:
-[Register Service API Documentation](./register-swagger.md)
➡️[Register Service API Swagger](./register-swagger.md)
