Skip to content

Commit dd61216

Browse files
akila-iLakshanSS
akila-i
authored and
LakshanSS
committed
docs: add Observer external IDP configuration steps
Signed-off-by: Akila-I <akila.99g@gmail.com>
1 parent 0c287e4 commit dd61216

6 files changed

Lines changed: 210 additions & 0 deletions

File tree

‎docs/platform-engineer-guide/identity-configuration.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,10 @@ The following components require OAuth client configuration:
179179

180180
- For configuration steps, see the [Workload Publishing Credentials](./workflows/workflow-workload-configuration.mdx) guide
181181

182+
**Observer (uid-resolver):**
183+
184+
- For configuration steps, refer to the [Observer External IDP Configuration](./observability-alerting.mdx#observer-external-idp-configuration) guide
185+
182186
:::tip
183187
Store sensitive values like client secrets using Kubernetes secrets rather than directly in helm values. Refer to the [Secret Management](./secret-management.mdx) guide for best practices.
184188
:::

‎docs/platform-engineer-guide/observability-alerting.mdx‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -500,6 +500,101 @@ Apply the updated values with `helm upgrade`.
500500

501501
For all available alert storage configuration options, see the [Observability Plane Helm Reference](../reference/helm/observability-plane.mdx#observer).
502502

503+
## Observer External IDP Configuration
504+
505+
By default, OpenChoreo configures Thunder as the identity provider for the Observer with a pre-configured OAuth client.
506+
If you are using an external identity provider, configure the uid-resolver as described below.
507+
508+
The uid-resolver is a sub-component of the Observer service that resolves component/project/environment identities
509+
by calling the OpenChoreo control plane API. It uses the OAuth2 `client_credentials` grant to authenticate as a service account when making those calls.
510+
511+
### Step 1: Create an OAuth Client in Your Identity Provider
512+
513+
Create an OAuth 2.0 client with the following settings in your identity provider:
514+
515+
- **Grant type**: `client_credentials`
516+
- **Client ID**: Choose a name (e.g., `openchoreo-observer-resource-reader-client`)
517+
- **Scopes**: No specific scopes are required by default. Set this only if your identity provider requires
518+
a non-empty scope for the `client_credentials` grant (e.g., `"api://<client-id>/.default"` for Azure AD).
519+
520+
### Step 2: Store the OAuth Client Secret
521+
522+
Store the client secret so the Observer can access it. For example, if you are using OpenBao:
523+
524+
```bash
525+
kubectl exec -n openbao openbao-0 -- \
526+
env BAO_ADDR=http://127.0.0.1:8200 BAO_TOKEN=root \
527+
bao kv put secret/observer-oauth-client-secret value="<YOUR_OAUTH_CLIENT_SECRET>"
528+
```
529+
530+
Add `UID_RESOLVER_OAUTH_CLIENT_SECRET` to the existing `observer-secret` ExternalSecret in the `openchoreo-observability-plane` namespace:
531+
532+
```bash
533+
kubectl patch externalsecret observer-secret -n openchoreo-observability-plane --type=json \
534+
-p '[{"op":"add","path":"/spec/data/-","value":{"secretKey":"UID_RESOLVER_OAUTH_CLIENT_SECRET","remoteRef":{"key":"observer-oauth-client-secret","property":"value"}}}]'
535+
```
536+
537+
### Step 3: Configure the Observability Plane
538+
539+
Update your Helm values with the OAuth client ID and the token endpoint of your identity provider:
540+
541+
```yaml
542+
security:
543+
oidc:
544+
tokenUrl: "<your-idp-token-url>"
545+
546+
observer:
547+
oauthClientId: "<your-client-id>"
548+
secretName: "observer-secret"
549+
```
550+
551+
For environments that use self-signed certificates on the identity provider's token endpoint, also set:
552+
553+
```yaml
554+
security:
555+
oidc:
556+
uidResolverTlsInsecureSkipVerify: "true"
557+
```
558+
559+
:::warning
560+
Only set `uidResolverTlsInsecureSkipVerify: "true"` in development or testing environments.
561+
For production deployments, ensure your identity provider uses valid TLS certificates.
562+
:::
563+
564+
Apply the changes using `helm upgrade` with your updated values.
565+
566+
### Step 4: Grant Control Plane Access
567+
568+
The Observer uses the `observer-resource-reader` role to read resource metadata (projects, components, environments, namespaces) from the control plane API.
569+
The API matches the `sub` claim in the issued JWT to identify the caller, so the new client must be granted the `observer-resource-reader` role via a bootstrap authorization mapping.
570+
571+
Add the following to your Control Plane values override, replacing `<your-client-id>` with the same client ID used in Step 1:
572+
573+
```yaml
574+
openchoreoApi:
575+
config:
576+
security:
577+
authorization:
578+
bootstrap:
579+
mappings:
580+
- name: observer-resource-reader-binding
581+
kind: ClusterAuthzRoleBinding
582+
system: true
583+
roleMappings:
584+
- roleRef:
585+
name: observer-resource-reader
586+
kind: ClusterAuthzRole
587+
entitlement:
588+
claim: sub
589+
value: "<your-client-id>"
590+
effect: allow
591+
```
592+
593+
:::warning
594+
When overriding the `bootstrap.mappings` array, the entire array is replaced. Make sure to include all other default bindings you want to keep.
595+
See the [Authorization Configuration](./authorization.md#customizing-bootstrap-roles-and-bindings) guide for details.
596+
:::
597+
503598
---
504599

505600
## Configuration Reference

‎docs/reference/helm/observability-plane.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,12 @@ OpenChoreo Observer service configuration - REST API that abstracts OpenSearch f
173173
| `observer.tracingAdapter.timeout` | Timeout for tracing adapter requests | `string` | `30s` |
174174
| `observer.tracingAdapter.url` | URL of the tracing adapter service | `string` | `http://tracing-adapter:9100` |
175175

176+
:::note
177+
The Observer includes a **uid-resolver** component that uses the OAuth2 `client_credentials` grant to call the control plane API for component/project/environment identity resolution.
178+
The relevant values are `observer.oauthClientId`, the `UID_RESOLVER_OAUTH_CLIENT_SECRET` key in `observer.secretName` secret, and `security.oidc.tokenUrl`.
179+
When using an external identity provider, refer to [Observer External IDP Configuration](../../platform-engineer-guide/observability-alerting.mdx#observer-external-idp-configuration) for setup steps.
180+
:::
181+
176182
## Rca
177183

178184
AI-powered Root Cause Analysis agent configuration

‎versioned_docs/version-v1.0.x/platform-engineer-guide/identity-configuration.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,10 @@ The following components require OAuth client configuration:
179179

180180
- For configuration steps, see the [Workload Publishing Credentials](./workflows/workflow-workload-configuration.mdx) guide
181181

182+
**Observer (uid-resolver):**
183+
184+
- For configuration steps, refer to the [Observer External IDP Configuration](./observability-alerting.mdx#observer-external-idp-configuration) guide
185+
182186
:::tip
183187
Store sensitive values like client secrets using Kubernetes secrets rather than directly in helm values. Refer to the [Secret Management](./secret-management.mdx) guide for best practices.
184188
:::

‎versioned_docs/version-v1.0.x/platform-engineer-guide/observability-alerting.mdx‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -500,6 +500,101 @@ Apply the updated values with `helm upgrade`.
500500

501501
For all available alert storage configuration options, see the [Observability Plane Helm Reference](../reference/helm/observability-plane.mdx#observer).
502502

503+
## Observer External IDP Configuration
504+
505+
By default, OpenChoreo configures Thunder as the identity provider for the Observer with a pre-configured OAuth client.
506+
If you are using an external identity provider, configure the uid-resolver as described below.
507+
508+
The uid-resolver is a sub-component of the Observer service that resolves component/project/environment identities
509+
by calling the OpenChoreo control plane API. It uses the OAuth2 `client_credentials` grant to authenticate as a service account when making those calls.
510+
511+
### Step 1: Create an OAuth Client in Your Identity Provider
512+
513+
Create an OAuth 2.0 client with the following settings in your identity provider:
514+
515+
- **Grant type**: `client_credentials`
516+
- **Client ID**: Choose a name (e.g., `openchoreo-observer-resource-reader-client`)
517+
- **Scopes**: No specific scopes are required by default. Set this only if your identity provider requires
518+
a non-empty scope for the `client_credentials` grant (e.g., `"api://<client-id>/.default"` for Azure AD).
519+
520+
### Step 2: Store the OAuth Client Secret
521+
522+
Store the client secret so the Observer can access it. For example, if you are using OpenBao:
523+
524+
```bash
525+
kubectl exec -n openbao openbao-0 -- \
526+
env BAO_ADDR=http://127.0.0.1:8200 BAO_TOKEN=root \
527+
bao kv put secret/observer-oauth-client-secret value="<YOUR_OAUTH_CLIENT_SECRET>"
528+
```
529+
530+
Add `UID_RESOLVER_OAUTH_CLIENT_SECRET` to the existing `observer-secret` ExternalSecret in the `openchoreo-observability-plane` namespace:
531+
532+
```bash
533+
kubectl patch externalsecret observer-secret -n openchoreo-observability-plane --type=json \
534+
-p '[{"op":"add","path":"/spec/data/-","value":{"secretKey":"UID_RESOLVER_OAUTH_CLIENT_SECRET","remoteRef":{"key":"observer-oauth-client-secret","property":"value"}}}]'
535+
```
536+
537+
### Step 3: Configure the Observability Plane
538+
539+
Update your Helm values with the OAuth client ID and the token endpoint of your identity provider:
540+
541+
```yaml
542+
security:
543+
oidc:
544+
tokenUrl: "<your-idp-token-url>"
545+
546+
observer:
547+
oauthClientId: "<your-client-id>"
548+
secretName: "observer-secret"
549+
```
550+
551+
For environments that use self-signed certificates on the identity provider's token endpoint, also set:
552+
553+
```yaml
554+
security:
555+
oidc:
556+
uidResolverTlsInsecureSkipVerify: "true"
557+
```
558+
559+
:::warning
560+
Only set `uidResolverTlsInsecureSkipVerify: "true"` in development or testing environments.
561+
For production deployments, ensure your identity provider uses valid TLS certificates.
562+
:::
563+
564+
Apply the changes using `helm upgrade` with your updated values.
565+
566+
### Step 4: Grant Control Plane Access
567+
568+
The Observer uses the `observer-resource-reader` role to read resource metadata (projects, components, environments, namespaces) from the control plane API.
569+
The API matches the `sub` claim in the issued JWT to identify the caller, so the new client must be granted the `observer-resource-reader` role via a bootstrap authorization mapping.
570+
571+
Add the following to your Control Plane values override, replacing `<your-client-id>` with the same client ID used in Step 1:
572+
573+
```yaml
574+
openchoreoApi:
575+
config:
576+
security:
577+
authorization:
578+
bootstrap:
579+
mappings:
580+
- name: observer-resource-reader-binding
581+
kind: ClusterAuthzRoleBinding
582+
system: true
583+
roleMappings:
584+
- roleRef:
585+
name: observer-resource-reader
586+
kind: ClusterAuthzRole
587+
entitlement:
588+
claim: sub
589+
value: "<your-client-id>"
590+
effect: allow
591+
```
592+
593+
:::warning
594+
When overriding the `bootstrap.mappings` array, the entire array is replaced. Make sure to include all other default bindings you want to keep.
595+
See the [Authorization Configuration](./authorization.md#customizing-bootstrap-roles-and-bindings) guide for details.
596+
:::
597+
503598
---
504599

505600
## Configuration Reference

‎versioned_docs/version-v1.0.x/reference/helm/observability-plane.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,12 @@ OpenChoreo Observer service configuration - REST API that abstracts OpenSearch f
173173
| `observer.tracingAdapter.timeout` | Timeout for tracing adapter requests | `string` | `30s` |
174174
| `observer.tracingAdapter.url` | URL of the tracing adapter service | `string` | `http://tracing-adapter:9100` |
175175

176+
:::note
177+
The Observer includes a **uid-resolver** component that uses the OAuth2 `client_credentials` grant to call the control plane API for component/project/environment identity resolution.
178+
The relevant values are `observer.oauthClientId`, the `UID_RESOLVER_OAUTH_CLIENT_SECRET` key in `observer.secretName` secret, and `security.oidc.tokenUrl`.
179+
When using an external identity provider, refer to [Observer External IDP Configuration](../../platform-engineer-guide/observability-alerting.mdx#observer-external-idp-configuration) for setup steps.
180+
:::
181+
176182
## Rca
177183

178184
AI-powered Root Cause Analysis agent configuration

0 commit comments

Comments
 (0)