docs: add setup docs

Aam-Digital · Dec 11, 2024 · 8626807 · 8626807
1 parent 6173e87
commit 8626807
Show file tree

Hide file tree

Showing 2 changed files with 58 additions and 7 deletions.
diff --git a/...src/main/kotlin/com/aamdigital/aambackendservice/skill/controller/SkillAdminController.kt b/...src/main/kotlin/com/aamdigital/aambackendservice/skill/controller/SkillAdminController.kt
@@ -43,7 +43,7 @@ class SkillAdminController(
     private val logger = LoggerFactory.getLogger(javaClass)
 
     @GetMapping("/sync")
-    @PreAuthorize("hasAuthority('ROLE_aam_skill_admin')")
+    @PreAuthorize("hasAuthority('ROLE_skill_admin')")
     fun fetchSyncStatus(): ResponseEntity<List<SkillDto>> {
         val result = skillLabUserProfileSyncRepository.findAll().mapNotNull {
             SkillDto(
@@ -60,7 +60,7 @@ class SkillAdminController(
      * For details of parameters like syncMode, see docs/api-specs/skill-api-v1.yaml
      */
     @PostMapping("/sync/{projectId}")
-    @PreAuthorize("hasAuthority('ROLE_aam_skill_admin')")
+    @PreAuthorize("hasAuthority('ROLE_skill_admin')")
     fun triggerSync(
         @PathVariable projectId: String,
         syncMode: SyncModeDto = SyncModeDto.DELTA,

diff --git a/docs/modules/skill.md b/docs/modules/skill.md
@@ -9,13 +9,64 @@ and import certain properties from matched external records into our entities vi
 
 TODO: diagram of use cases and services
 
-
 ## Setup
-- TODO configure in environmnent
 
-- TODO define Keycloak role
-- assign role to the user(s) who should be able to access the external profiles data
+### Provide environment configuration for skill module
+
+You can find the latest version of the needed configuration in the package `aambackendservice.skill.di`.
+The classes with the `@ConfigurationProperties` defines the needed properties.
+
+An example configuration would be:
+
+#### Disable the Skill feature: (default behaviour)
+
+```yaml
+features:
+  skill-api: disabled
+```
+
+#### Enable Skill feature with connection to SkillLab
+
+Here an example configuration for the SkillLab project `42`
+
+```yaml
+features:
+  skill-api: skilllab
+
+skilllab-api-client-configuration:
+  base-path: https://skilllab.app/<some-api-path>/project/42
+  api-key: this-is-a-secret
+  project-id: 42
+  response-timeout-in-seconds: 30 # (default value)
 
+```
+
+### Configure permissions in the authentication system (Keycloak)
+
+Example for the realm: `dummy-realm`
+
+#### Setup Realm roles
+
+- Open the Keycloak user interface and navigate to the `dummy-realm`
+- Go to `Realm roles`
+- Create two new roles by clicking on `Create role`:
+  - `skill_admin`
+  - `skill_reader`
+- assign role to the `User(s)` or `Group(s)` who should be able to access the external profiles data
+
+#### Add roles mapper for clients
+
+It's necessary to add the roles to the JWT token to verify the roles in the backend.
+
+For that, add an `roles mapper` for each client that sends requests to the skill api.
+This should usually be the `app` client
+
+- Open the Keycloak user interface and navigate to the `dummy-realm`
+- Go to `Clients`
+- Open the `app` client
+- Switch to tab `Client scopes`
+- Add the pre-defined client scope `roles` with Assigned Type `default`
 
 ## Using the API
-_see [api-specs/skill-api](../api-specs/skill-api-v1.yaml)_
+
+_see [api-specs/skill-api](../api-specs/skill-api-v1.yaml)_