add keycloak client for external API token issuance (#32)

* add keycloak client for external API token issuance

Configure a second Keycloak client (runway-api) for the client
credentials flow so the external API can be tested locally without
an external IdP. Adds create:jobs and partner:ea client scopes,
an audience mapper, and updates .env.copyme with working defaults.

Update docs with local development curl examples and fix the
generic token request example to use form-encoded parameters.

Made-with: Cursor

* fix link in external api readme

Author: edandylytics

app/README.md

@@ -93,7 +93,11 @@ There are two methods to log in as a given user:
    1. Within the user record, select `Impersonate` from the Action menu in the upper right
    1. Go to http://localhost:4200 and click the login button. When you get redirected to Keycloak, Keycloak will authenticate you as the user you just impersonated.
 
-#### 4. Configure an ODS
+#### 4. Testing the External API
+
+The local Keycloak comes with a pre-configured client for the external API (client credentials flow). See the [External API README](api/src/external-api/README.md#local-development) for curl examples.
+
+#### 5. Configure an ODS
 
 You'll need a valid (even if non-prod) place to send data in order to run local jobs.
 

app/api/.env.copyme

@@ -27,5 +27,5 @@ LOCAL_EVENT_EMITTER=log # log | noop (omit for EventBridge)
 AWS_REGION=us-east-2
 BUNDLE_BRANCH=development
 
-# OAUTH2_AUDIENCE=runway-local
-# OAUTH2_ISSUER=<url of token issuer, if using>
+OAUTH2_ISSUER=http://localhost:8080/realms/example
+OAUTH2_AUDIENCE=runway-local

app/api/keycloak/config.yaml

@@ -4,7 +4,19 @@ realm: example
 displayName: Example
 ssoSessionMaxLifespan: 7776000
 enabled: true
+
+clientScopes:
+  - name: "create:jobs"
+    protocol: openid-connect
+    attributes:
+      "include.in.token.scope": "true"
+  - name: "partner:ea"
+    protocol: openid-connect
+    attributes:
+      "include.in.token.scope": "true"
+
 clients:
+  # UI login (authorization code flow)
   - clientId: runway-local
     name: 'Runway Local Dev'
     enabled: true
@@ -50,6 +62,31 @@ clients:
           jsonType.label: String
     attributes:
       post.logout.redirect.uris: http://localhost:4200* 
+
+  # External API (client credentials flow)
+  - clientId: runway-api
+    name: 'Runway External API'
+    enabled: true
+    clientAuthenticatorType: client-secret
+    secret: api-secret-123
+    serviceAccountsEnabled: true
+    standardFlowEnabled: false
+    directAccessGrantsEnabled: false
+    defaultClientScopes:
+      - "create:jobs"
+      - "partner:ea"
+    protocolMappers:
+      # The app validates the aud claim, so we need to inject it.
+      # Value must match OAUTH2_AUDIENCE.
+      - name: API Audience
+        protocol: openid-connect
+        protocolMapper: oidc-audience-mapper
+        consentRequired: false
+        config:
+          included.custom.audience: "runway-local"
+          id.token.claim: "false"
+          access.token.claim: "true"
+
 users:
   - username: dev
     credentials:

app/api/src/external-api/README.md

@@ -25,14 +25,34 @@ Configure an OAuth2/OIDC client in your identity provider with:
 
 The access token must include the following claims:
 
-| Claim         | Required | Description                                                                                         |
-| ------------- | -------- | --------------------------------------------------------------------------------------------------- |
-| `client_id`   | Yes\*    | The OAuth2 client ID. Used to attribute jobs to the API client.                                     |
-| `azp`         | Yes\*    | Authorized party. Used as fallback if `client_id` is not present.                                   |
-| `client_name` | No       | Display name for the API client. If provided, shown in the Runway UI for jobs created via the API.  |
+| Claim         | Required | Description                                                                                        |
+| ------------- | -------- | -------------------------------------------------------------------------------------------------- |
+| `client_id`   | Yes\*    | The OAuth2 client ID. Used to attribute jobs to the API client.                                    |
+| `azp`         | Yes\*    | Authorized party. Used as fallback if `client_id` is not present.                                  |
+| `client_name` | No       | Display name for the API client. If provided, shown in the Runway UI for jobs created via the API. |
 
 \* At least one of `client_id` or `azp` must be present. Most OAuth2 providers include `client_id` by default in client credentials tokens.
 
+### Local Development
+
+The local Keycloak instance (started by `docker compose`) comes pre-configured with a `runway-api` client for the external API. No additional IdP setup is needed.
+
+The client is configured in [`api/keycloak/config.yaml`](../../../api/keycloak/config.yaml) with the `create:jobs` and `partner:ea` scopes and an audience of `runway-local`.
+
+Get a token and verify it:
+
+```bash
+# Obtain a token from local Keycloak
+TOKEN=$(curl -s -X POST http://localhost:8080/realms/example/protocol/openid-connect/token \
+  -d "grant_type=client_credentials" \
+  -d "client_id=runway-api" \
+  -d "client_secret=api-secret-123" | jq -r '.access_token')
+
+# Verify it against the local API
+curl -X POST http://localhost:3333/api/v1/token/verify \
+  -H "Authorization: Bearer $TOKEN"
+```
+
 ## API Usage
 
 All requests must include: