docs: container temporary credentials (#6152)

* docs: Document container temporary credentials and identity integration feature

This commit adds comprehensive documentation for the container temporary
credentials feature introduced in the Container Orchestration Provider. The
documentation covers:

- Container Identity Integration feature in container-orchestration-provider-usage.md
  - Configuration parameters (Identity Integration Enabled, Container Permissions)
  - Detailed overview of how the feature works
  - Complete usage examples in Python, JavaScript, Shell Script
  - Best practices and troubleshooting guide

- Updated container-orchestration-provider.md to list Identity Integration
  as a key feature

- New how-to-use-temporary-identity-service.md for Java developers
  - TemporaryIdentityService API reference
  - Usage examples for OSGi bundles
  - Best practices and security considerations
  - Common use cases including container authentication

- Updated authentication-and-authorization.md with new Temporary Identities section
  - Key characteristics of temporary identities
  - Differences from regular identities
  - API overview and usage example
  - Cross-references to related documentation

- Updated mkdocs.yml navigation to include the new Java development guide

The documentation provides developers and users with a complete understanding
of how to leverage temporary credentials for secure container-to-Kura communication.

* docs: update container identity integration auth details

* docs: align temporary identity docs with current implementation

* docs(container.provider): add firewall note for REST access from containers

* Refactor usage examples for container orchestration

Updated usage examples section to remove redundant examples and improve clarity.

* docs(identity): align temporary identity auth docs with certificate and password support

Author: MMaiero

docs/core-services/container-orchestration-provider-usage.md

@@ -90,6 +90,10 @@ To begin configuring the container, look under **Services** and select the item
 
 - **Restart Container On Failure** - A boolean that tells the container engine to automatically restart the container when it has failed or shut down.
 
+- **Identity Integration Enabled** - When enabled, Kura automatically creates a temporary identity with the specified permissions and provides the container with authentication credentials to access Kura's REST APIs. See [Container Identity Integration](#container-identity-integration) for more details.
+
+- **Container Permissions (optional)** - A comma-separated list of permission names to grant to the container's temporary identity (e.g., `rest.system,rest.configuration`). This field is only used when **Identity Integration Enabled** is set to true. See [Container Identity Integration](#container-identity-integration) for available permissions and usage examples.
+
 After specifying container parameters, ensure to set **Enabled** to **true** and press **Apply**. The container engine will then pull the respective image, spin up and start the container. If the gateway or the framework is power cycled, and the container and Container Orchestration Service are set to **enabled**, the framework will automatically start the container again upon startup.
 
 ![Container Orchestration Provider Container Configuration](./images/container-orchestration-provider-container-configuration.png)
@@ -141,6 +145,117 @@ The result should be a single line with all the existing options plus the new on
 !!! warning
     Modifying the bootloader options incorrectly may prevent the system from booting. Please ensure to back up any important data before making changes to these settings.
 
+## Container Identity Integration
+
+The Container Identity Integration feature allows containers to securely authenticate and interact with Kura's REST APIs using temporary credentials. When enabled, Kura automatically provisions a temporary identity and provides password-based credentials to the container, eliminating the need for manual credential configuration.
+
+### Overview
+
+When Identity Integration is enabled for a container instance, Kura performs the following operations:
+
+1. **Creates a Temporary Identity**: A temporary, non-persistent identity is created specifically for the container with a unique name based on the container name (e.g., `container_myapp` for a container named `myapp`).
+
+2. **Assigns Permissions**: The temporary identity is granted the permissions specified in the **Container Permissions** field.
+
+3. **Provides Credentials**: The container receives the following environment variables:
+   - `KURA_IDENTITY_NAME`: The temporary identity name for accessing Kura's REST APIs
+   - `KURA_IDENTITY_PASSWORD`: The temporary password for accessing Kura's REST APIs
+   - `KURA_REST_BASE_URL`: The complete base URL for Kura's REST API endpoints (e.g., `http://172.17.0.1:8080/services` or `https://172.17.0.1:443/services`)
+
+4. **Automatic Cleanup**: When the container stops or is deleted, Kura automatically removes the temporary identity and invalidates its credentials.
+
+### Features
+
+- **Zero Configuration**: Containers automatically receive the correct REST API URL based on the gateway's HTTPS configuration and network mode.
+- **Network-Aware**: The REST base URL is automatically adjusted based on the container's networking mode (bridge, host, etc.).
+- **Secure**: Credentials are temporary and automatically invalidated when containers stop.
+- **Non-Persistent**: Temporary identities exist only in memory and are never persisted to disk.
+- **Permission-Based**: Fine-grained access control using Kura's existing permission system.
+
+### Configuration
+
+To enable Identity Integration for a container:
+
+1. Set **Identity Integration Enabled** to `true`
+2. Specify the required permissions in **Container Permissions** field (comma-separated)
+3. Apply the configuration
+
+To use the temporary credentials with REST APIs, ensure **Basic Authentication Enabled** is set to `true` in the **RestService** configuration.
+
+The framework will create the temporary identity when the container starts and clean it up when the container stops.
+
+### Available Permissions
+
+For a complete list of available permissions, use the [REST Identity API](/references/rest-apis/rest-identity-api-v2/#get-defined-permissions) to query defined permissions in your system.
+
+### Usage Example
+
+#### Example: Container with Read-Only System Access
+
+A monitoring container that needs to read system information but cannot modify configuration:
+
+**Container Configuration:**
+- **Identity Integration Enabled**: `true`
+- **Container Permissions**: `rest.system`
+
+**Container Code (Python):**
+```python
+import os
+import requests
+
+# Read credentials from environment variables
+identity_name = os.environ.get('KURA_IDENTITY_NAME')
+identity_password = os.environ.get('KURA_IDENTITY_PASSWORD')
+base_url = os.environ.get('KURA_REST_BASE_URL')
+
+# Make authenticated request to get system information
+response = requests.get(
+    f'{base_url}/system/info',
+    auth=(identity_name, identity_password)
+)
+if response.status_code == 200:
+    system_info = response.json()
+    print(f"System info: {system_info}")
+else:
+    print(f"Failed to get system info: {response.status_code}")
+```
+
+### Best Practices
+
+1. **Principle of Least Privilege**: Only grant permissions that are absolutely necessary for the container's functionality.
+
+2. **Validate Environment Variables**: Always check that `KURA_IDENTITY_NAME`, `KURA_IDENTITY_PASSWORD`, and `KURA_REST_BASE_URL` are present before making API calls.
+
+3. **Handle Credential Lifecycle**: Be prepared for credentials to become invalid when the container is stopping or restarting.
+
+4. **Error Handling**: Implement proper error handling for API calls, as permissions may be denied if the container doesn't have the required permission.
+
+5. **Network Mode Considerations**: The REST base URL is automatically adjusted based on network mode:
+   - **bridge mode** (default): Uses the Docker bridge gateway IP (typically `172.17.0.1`)
+   - **host mode**: Uses `localhost`
+
+6. **HTTPS Support**: The REST base URL automatically uses HTTPS if enabled in Kura's HTTP Service configuration.
+
+### Troubleshooting
+
+**Container cannot access Kura APIs:**
+- Verify that **Identity Integration Enabled** is set to `true`
+- Check that the container has been granted the necessary permissions in **Container Permissions**
+- Ensure the container is reading the environment variables correctly
+- If Kura firewall is installed and enabled, allow traffic from container networks (for example `docker0` or user-defined Docker bridges) to the Kura REST API port
+- Check container logs for authentication errors
+
+**Basic authentication fails:**
+- Verify the request includes valid Basic credentials (`KURA_IDENTITY_NAME` / `KURA_IDENTITY_PASSWORD`)
+- Check that the temporary identity was created successfully in Kura logs
+- Ensure the container is using the correct REST base URL
+- Verify **Basic Authentication Enabled** is set to `true` in **RestService**
+
+**Permission denied errors:**
+- Verify the permission name is correct (case-sensitive)
+- Ensure the permission exists in the system (use the REST Identity API to list defined permissions)
+- Check that the permission was correctly added to the **Container Permissions** field
+
 ## Stopping the container
 
 !!! warning
@@ -152,4 +267,4 @@ To stop the container without deleting the component, set the **Enabled** field
 
 ## Container Management Dashboard
 
-The Container Orchestration service also provides the user with an intuitive container dashboard. This dashboard shows all containers running on a gateway, including containers created with the framework and those created manually through the command-line interface. To utilize this dashboard the `org.eclipse.container.orchestration.provider` (ContainerOrchestrationService) must be enabled, and the dashboard can be opened by navigating to Device > Containers.
+The Container Orchestration service also provides the user with an intuitive container dashboard. This dashboard shows all containers running on a gateway, including containers created with the framework and those created manually through the command-line interface. To utilize this dashboard the `org.eclipse.container.orchestration.provider` (ContainerOrchestrationService) must be enabled, and the dashboard can be opened by navigating to Device > Containers.

docs/core-services/container-orchestration-provider.md

@@ -2,4 +2,14 @@
 
 The Container Orchestration Provider allows Kura to manage Docker. With this tool, you can arbitrarily pull and deploy containerized software packages and run them on your gateway. This Service allows the user to create, configure, start, and stop containers all from the browser. The bundle will also restart containers if the gateway is restarted.
 
-The feature is composed of two bundles, one that exposes APIs for container management and one that implements those APIs. This API is exposed so that you can leverage it to implement containerization in your own Kura plugins.
+The feature is composed of two bundles, one that exposes APIs for container management and one that implements those APIs. This API is exposed so that you can leverage it to implement containerization in your own Kura plugins.
+
+## Key Features
+
+- **Container Lifecycle Management**: Create, start, stop, and manage Docker containers through Kura's web interface
+- **Image Management**: Pull images from Docker Hub or authenticated registries with automatic retry and timeout configuration
+- **Resource Control**: Configure CPU, memory, GPU allocation, and cgroup settings for containers
+- **Network Configuration**: Support for various Docker networking modes (bridge, host, custom networks)
+- **Security**: Container image signature verification and allowlist enforcement
+- **Identity Integration**: Automatic provisioning of temporary credentials for containers to securely access Kura's REST APIs
+- **Persistence**: Automatic container restart after gateway reboot if configured

docs/gateway-configuration/authentication-and-authorization.md

@@ -67,6 +67,102 @@ Starting from Kura 5.5 the following restrictions will be applied by the Identit
   - must be at least 3 and at most 255 characters long.
   - can only be composed by one or more sequences of alphanumeric characters (`[A-Za-z0-9]+`) separated by the dot symbol, the dot is not allowed at the beginning or at the end of the permission name (examples of valid permission names are `foo1.bAr`, `foo`, `a.b.c`).
 
+## Temporary Identities
+
+Kura 6 introduces temporary identity support in the **IdentityService**, a set of APIs for creating and managing temporary, non-persistent identities. Temporary identities are designed for short-lived authentication scenarios where identity persistence is not required.
+
+### Key Characteristics
+
+- **Non-Persistent**: Temporary identities exist only in memory and are never persisted to disk or configuration snapshots
+- **Authentication Flexibility**: Temporary identities can be used with the same authentication mechanisms supported by regular identities (for example password-based and certificate-based REST authentication, depending on RestService configuration)
+- **Automatic Lifecycle Management**: Temporary identities can be programmatically created and deleted as needed
+- **Permission-Based Authorization**: Temporary identities support the same permission model as regular identities
+
+### Primary Use Case: Container Identity Integration
+
+The main use case for temporary identities is the **Container Identity Integration** feature, which automatically provisions authentication credentials for containerized applications. When a container is configured with identity integration enabled:
+
+1. Kura creates a temporary identity with the specified permissions
+2. Generates a temporary password for the identity
+3. Provides the identity name and password to the container via environment variables
+4. Automatically cleans up the temporary identity when the container stops
+
+This allows containers to securely access Kura's REST APIs without manual credential configuration or exposing persistent credentials. Container Identity Integration provisions password credentials, so password-based REST authentication requires **Basic Authentication Enabled** in the **RestService** configuration. Temporary identities can also be used with certificate-based REST authentication when certificate authentication is enabled and the certificate CN matches the identity name.
+
+### Temporary Identity API
+
+Temporary identities are managed through the `IdentityService` APIs using an `IdentityConfiguration` and a lifetime:
+
+#### Create Temporary Identity
+```java
+void createTemporaryIdentity(IdentityConfiguration configuration, Duration lifetime)
+```
+Creates a temporary identity with the given configuration and lifetime.
+
+#### Delete Temporary Identity
+```java
+boolean deleteIdentity(String identityName)
+```
+Deletes a temporary identity by name (also works for regular identities).
+
+### Usage Example
+
+```java
+import java.time.Duration;
+import java.util.Arrays;
+import java.util.Optional;
+import org.eclipse.kura.identity.IdentityConfiguration;
+import org.eclipse.kura.identity.IdentityService;
+import org.eclipse.kura.identity.Permission;
+import org.eclipse.kura.identity.PasswordConfiguration;
+import org.eclipse.kura.identity.AssignedPermissions;
+
+// Create temporary identity with specific permissions
+Set<Permission> permissions = new HashSet<>();
+permissions.add(new Permission("rest.system"));
+permissions.add(new Permission("rest.configuration"));
+
+final String identityName = "container_myapp";
+final char[] password = "temporary-password".toCharArray();
+
+PasswordConfiguration passwordConfiguration = new PasswordConfiguration(false, true, Optional.of(password), Optional.empty());
+AssignedPermissions assignedPermissions = new AssignedPermissions(permissions);
+IdentityConfiguration configuration = new IdentityConfiguration(
+    identityName,
+    Arrays.asList(passwordConfiguration, assignedPermissions)
+);
+
+identityService.createTemporaryIdentity(configuration, Duration.ofHours(1));
+
+// Identity name and password can now be used for REST API authentication
+
+// Clean up when no longer needed
+identityService.deleteIdentity(identityName);
+```
+
+### Differences from Regular Identities
+
+| Aspect | Regular Identity | Temporary Identity |
+|--------|-----------------|-------------------|
+| Persistence | Stored in configuration snapshots | Memory only, never persisted |
+| Authentication | Password-based and certificate-based | Password-based and certificate-based |
+| Lifecycle | Manual creation/deletion via UI or API | Programmatic creation/deletion |
+| Use Case | Long-term user accounts | Short-lived service authentication |
+| Management | Web UI, REST API, MQTT | Java API only |
+
+### Security Considerations
+
+- Temporary identities follow the same permission model as regular identities
+- Passwords and client certificates should be treated as sensitive credentials and not logged or persisted
+- Temporary identities are automatically removed from memory when deleted
+- Best practice: delete temporary identities as soon as they are no longer needed
+
+### Further Reading
+
+- [Container Identity Integration](../core-services/container-orchestration-provider-usage.md#container-identity-integration) - Detailed guide on using temporary identities with containers
+- [How to Use Temporary Identities](../java-application-development/how-to-use-temporary-identity-service.md) - Developer guide for using IdentityService temporary identity APIs
+- [REST Identity API](../references/rest-apis/rest-identity-api-v2.md) - REST APIs for identity management (regular identities only)
+
 ## UserAdmin persistence
 
 The `org.eclipse.kura.internal.useradmin.store.RoleRepositoryStoreImpl` Kura service allows to persist the UserAdmin state in Kura configuration snapshot, this includes the defined identities and permissions.
@@ -216,4 +312,4 @@ Example:
   "name": "kura.permission.kura.wires.admin",
   "basicMembers": ["kura.user.appadmin"]
 }
-```
+```

docs/java-application-development/how-to-use-temporary-identity-service.md

@@ -0,0 +1,96 @@
+# How to Use Temporary Identities
+
+Temporary identities are short-lived, non-persistent identities created in memory. They are intended for scenarios such as containerized applications that need limited access to Kura REST APIs without storing long-term credentials.
+
+## Overview
+
+Temporary identities are managed through the `IdentityService` using an `IdentityConfiguration` and a lifetime:
+
+- A temporary identity is created with an `IdentityConfiguration` and assigned permissions.
+- The identity exists only in memory and is removed explicitly or when the lifetime expires.
+- REST access can use password-based or certificate-based authentication, depending on RestService configuration.
+
+## API Reference
+
+### Create Temporary Identity
+
+```java
+void createTemporaryIdentity(IdentityConfiguration configuration, Duration lifetime)
+```
+
+Creates a temporary identity with the given configuration and lifetime.
+
+### Delete Identity
+
+```java
+boolean deleteIdentity(String identityName)
+```
+
+Deletes a temporary identity by name (also works for regular identities).
+
+## Usage Example
+
+```java
+import java.time.Duration;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Optional;
+import java.util.Set;
+
+import org.eclipse.kura.identity.AssignedPermissions;
+import org.eclipse.kura.identity.IdentityConfiguration;
+import org.eclipse.kura.identity.IdentityService;
+import org.eclipse.kura.identity.Permission;
+import org.eclipse.kura.identity.PasswordConfiguration;
+
+public class TemporaryIdentityExample {
+
+    private IdentityService identityService;
+
+    public void createTemporaryIdentity() throws Exception {
+        Set<Permission> permissions = new HashSet<>();
+        permissions.add(new Permission("rest.system"));
+        permissions.add(new Permission("rest.configuration"));
+
+        String identityName = "container_myapp";
+        char[] password = "temporary-password".toCharArray();
+
+        PasswordConfiguration passwordConfiguration = new PasswordConfiguration(
+            false,
+            true,
+            Optional.of(password),
+            Optional.empty()
+        );
+
+        AssignedPermissions assignedPermissions = new AssignedPermissions(permissions);
+        IdentityConfiguration configuration = new IdentityConfiguration(
+            identityName,
+            Arrays.asList(passwordConfiguration, assignedPermissions)
+        );
+
+        identityService.createTemporaryIdentity(configuration, Duration.ofHours(1));
+
+        // Use identityName and password to access REST APIs via Basic auth
+    }
+
+    public void cleanupTemporaryIdentity() throws Exception {
+        identityService.deleteIdentity("container_myapp");
+    }
+}
+```
+
+## REST Authentication Example
+
+```bash
+curl -k -u "${KURA_IDENTITY_NAME}:${KURA_IDENTITY_PASSWORD}" \
+  "${KURA_REST_BASE_URL}/system/info"
+```
+
+Basic authentication must be enabled in the **RestService** configuration for password-based access. Certificate-based access requires certificate authentication to be enabled and a client certificate whose CN matches the temporary identity name.
+
+## Best Practices
+
+1. **Least Privilege**: Grant only the permissions required by the application.
+2. **Short Lifetimes**: Use the minimum lifetime needed for the use case.
+3. **Cleanup**: Delete temporary identities when they are no longer needed.
+4. **Secrets Handling**: Do not log or persist temporary passwords.