[esignet-2667] Allow Keycloak init YAML to configure audience mappers

AGENTS.md

@@ -41,6 +41,12 @@ own `README.md`/`AGENTS.md` over guessing conventions from a sibling.
   is the sqlc-facing source of truth for the `client_detail` table
   specifically; keep it in sync if you change that table elsewhere.
 
+## Keycloak init mappers
+
+Protocol mappers are created by `mosip/keycloak` `keycloak-init/keycloak_init.py`. `deploy/keycloak/keycloak-init.sh` installs that chart. `deploy/keycloak/keycloak-init-values.yaml` is the eSignet realm input. Do not copy `keycloak_init.py` into this repo.
+
+A client `mappers` entry without `protocol_mapper` stays `oidc-usermodel-attribute-mapper` (`mapper_name`, `mapper_user_attribute`, `token_claim_name`). Set `protocol_mapper: oidc-audience-mapper` and `included_client_audience` or `included_custom_audience` to add that value to the access token `aud`. Add that entry only on the client that needs it. A re-run skips a mapper name that already exists.
+
 ## Conventions
 
 - Only commit generated/build artifacts if a subproject's own docs say to;

deploy/keycloak/keycloak-init-values.yaml

@@ -120,7 +120,14 @@ keycloak:
             display.on.consent.screen: "false",
             include.in.token.scope: "true"
           }
-      clients:   
+      clients:
+        # A mapper without protocol_mapper stays oidc-usermodel-attribute-mapper
+        # (mapper_name, mapper_user_attribute, token_claim_name).
+        # Add an audience on the client that needs it:
+        # - mapper_name: esignet-audience
+        #   protocol_mapper: oidc-audience-mapper
+        #   included_client_audience: target-client-id
+        #   # or included_custom_audience: https://api.example.org
         - name: mosip-pms-client
           mappers: []
           saroles:

deploy/keycloak/keycloak-init/README.md

@@ -0,0 +1,27 @@
+# Keycloak init audience mappers
+
+`keycloak_init.py` is the eSignet Keycloak init script with support for audience protocol mappers. Issue [#2667](https://github.com/mosip/esignet/issues/2667). This change stays in eSignet. `keycloak-init-values.yaml` is unchanged.
+
+## Mapper YAML
+
+A client `mappers` entry creates a protocol mapper. `protocol_mapper` selects the type. When it is omitted, the mapper stays `oidc-usermodel-attribute-mapper` and uses `mapper_user_attribute` plus `token_claim_name`.
+
+An `oidc-audience-mapper` entry adds an audience to the access token `aud` claim. Set `included_client_audience` (another client's client id in the same realm), `included_custom_audience` (a literal audience), or both. The script sets `access.token.claim=true`.
+
+```yaml
+clients:
+  - name: mosip-pms-client
+    mappers:
+      - mapper_name: partnerType
+        mapper_user_attribute: partnerType
+        token_claim_name: partnerType
+      - mapper_name: esignet-audience
+        protocol_mapper: oidc-audience-mapper
+        included_client_audience: mosip-esignet-client
+      - mapper_name: custom-audience
+        protocol_mapper: oidc-audience-mapper
+        included_custom_audience: https://api.example.org
+    saroles: []
+```
+
+A re-run does not change a mapper whose name already exists. Keycloak returns 409 and the script skips it. To change `included_client_audience` or `included_custom_audience` on a mapper that is already in the realm, delete that mapper in Keycloak and run init again.