Loading...
const entity = context.entity
return (
Name: {entity?.name}
Kind: {entity?.kind}
Owner: {entity?.owner}
Reference: {entity?.entity_ref}
)
}
```
The `entity` object is the standard Harness Entity Object. You can read entity annotations to drive plugin behavior. For example, reading `github.com/project-slug` tells your plugin which GitHub repository to fetch data from.
### Make proxy fetch calls
Plugins cannot make direct network requests because the production environment blocks them via CSP. Use `PluginAPI.proxyFetch()` to route third-party API calls through the IDP host instead. To call Harness APIs, use [`PluginAPI.harnessFetch()`](#call-harness-apis).
{% hint style="info" %}
You must configure the [Backend Proxy Plugin](/internal-developer-portal/use-idp/plugins/delegate-proxy.md) before making proxy fetch calls. The endpoint paths you pass to `proxyFetch` must match the endpoints you defined there.
{% endhint %}
```tsx
import { PluginAPI } from '@harnessio/idp-plugins-sdk';
// GET request. The path is the endpoint you configured in Backend Proxy Plugin.
const res = await PluginAPI.proxyFetch('/your-configured-endpoint/some-path')
const data = await res.json()
// POST request with body
const res = await PluginAPI.proxyFetch('/your-configured-endpoint/create', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name: 'example' }),
})
```
The endpoint path (for example, `/github`) corresponds to the endpoint name you configured in the Backend Proxy Plugin. All paths under that endpoint follow the same prefix.
```tsx
// Example: reading the GitHub project slug from entity annotations
// and fetching pull requests through the "/github" proxy endpoint
const context = usePluginContext()
const slug = context.entity?.metadata?.annotations?.['github.com/project-slug']
const res = await PluginAPI.proxyFetch(`/github/repos/${slug}/pulls`)
const pulls = await res.json()
```
**How it works:**
1. Your plugin calls `PluginAPI.proxyFetch(url, init)`.
2. The IDP host makes the actual HTTP request through the Backend Proxy Plugin, which handles authentication and routing.
3. The host returns the response to your plugin.
Your plugin never touches secrets. Authentication is handled entirely by the Backend Proxy Plugin configuration.
### Send the user identity to your external system
By default, your external system cannot identify which IDP user sent a proxy fetch request. IDP does not forward the user's Harness session to external systems, as that session grants access to Harness. Your external system can authenticate the proxy with a static key in the endpoint headers, but it cannot make per-user decisions.
When you enable signed user tokens on a Backend Proxy Plugin endpoint, IDP adds a short-lived, signed token to every request that your plugin sends to that endpoint with `PluginAPI.proxyFetch()`. The token identifies the Harness user who triggered the request. Your external system verifies the token and then decides how to handle the request. For example, it can restrict an action to specific users, audit access per user, or apply per-user rate limits. IDP does not make the authorization decision; your external system does.
**How it works:**
1. Your plugin calls `PluginAPI.proxyFetch()` with a path under a signing-enabled endpoint.
2. IDP identifies the signed-in user from the session.
3. Harness generates a signed token for that user.
4. IDP forwards the request to the endpoint target and adds the token in the `X-Harness-IDP-User-Token` header.
5. Your external system validates the token, and then makes its authorization decision.
**Enable signed user tokens on an endpoint**
By default, IDP does not send signed user tokens. You turn them on per endpoint, so endpoints without the setting keep their current behavior.
To enable signed user tokens, complete the following steps:
1. In IDP, go to **Configure** and click **Plugins**.
2. Select the **Configure Backend Proxies** plugin.
3. In the configuration YAML, add `enableSignedUser: true` to the endpoint that your plugin calls.
```yaml
proxy:
endpoints:
/my-external-api:
target: https://api.example.com
enableSignedUser: true
headers:
X-API-Key: ${MY_API_KEY}
```
