{"_id":"@astaykov/n8n-nodes-entraagentid","name":"@astaykov/n8n-nodes-entraagentid","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.1":{"name":"@astaykov/n8n-nodes-entraagentid","version":"0.1.1","description":"Microsoft Entra Agent ID credentials for n8n","license":"MIT","homepage":"https://github.com/astaykov/n8n-nodes-entraagentid","keywords":["n8n-community-node-package","EntraAgentID"],"author":{"name":"Anton Staykov","email":"astaykov@gmail.com"},"repository":{"type":"git","url":"git+https://github.com/astaykov/n8n-nodes-entraagentid.git"},"publishConfig":{"access":"public"},"scripts":{"build":"n8n-node build","build:watch":"tsc --watch","dev":"n8n-node dev","lint":"n8n-node lint","lint:fix":"n8n-node lint --fix","release":"n8n-node release","prepublishOnly":"n8n-node prerelease"},"n8n":{"n8nNodesApiVersion":1,"strict":false,"credentials":["dist/credentials/EntraAgentIDApi.credentials.js"],"nodes":["dist/nodes/EntraAgentIDAuthManager/EntraAgentIdAuthManager.node.js"]},"devDependencies":{"@n8n/node-cli":"*","eslint":"9.32.0","prettier":"3.6.2","release-it":"^19.0.4","typescript":"5.9.2"},"peerDependencies":{"n8n-workflow":"*"},"gitHead":"6268e3f75729ac276340b24c0b8ae4d823505316","_id":"@astaykov/n8n-nodes-entraagentid@0.1.1","bugs":{"url":"https://github.com/astaykov/n8n-nodes-entraagentid/issues"},"_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-GD97potS7tcNVIGyohsTisUOh3yd/16rQ/QOwGZ1yEqrdpObifGhlpo41690ykEym9Pbr0AJMRK1k8jItiEzCA==","shasum":"672bca0e04caad15a1dc6d12b243311e55be98df","tarball":"https://registry.npmjs.org/@astaykov/n8n-nodes-entraagentid/-/n8n-nodes-entraagentid-0.1.1.tgz","fileCount":19,"unpackedSize":153950,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDbIZtQSMf+6GKxHsdBDFMTjEvBlu4HPl4g8vf61jr//AiEAzZPE22iUEUXu22g8+nUvATAdHyoBgSitqcVsUnahJyU="}]},"_npmUser":{"name":"astaykov","email":"astaykov@gmail.com"},"directories":{},"maintainers":[{"name":"astaykov","email":"astaykov@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/n8n-nodes-entraagentid_0.1.1_1773075753261_0.4351941857060957"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-09T17:02:33.145Z","0.1.1":"2026-03-09T17:02:33.400Z","modified":"2026-03-09T17:02:33.573Z"},"maintainers":[{"name":"astaykov","email":"astaykov@gmail.com"}],"description":"Microsoft Entra Agent ID credentials for n8n","homepage":"https://github.com/astaykov/n8n-nodes-entraagentid","keywords":["n8n-community-node-package","EntraAgentID"],"repository":{"type":"git","url":"git+https://github.com/astaykov/n8n-nodes-entraagentid.git"},"author":{"name":"Anton Staykov","email":"astaykov@gmail.com"},"bugs":{"url":"https://github.com/astaykov/n8n-nodes-entraagentid/issues"},"license":"MIT","readme":"# n8n-nodes-EntraAgentID\r\n\r\nA custom [n8n](https://n8n.io/) credential that implements the [Microsoft Entra Agent ID](https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/what-is-agent-id-platform) token exchange flows.\r\n\r\nThis credential implements Entra Agent ID token token acquisition and injects the resulting `access_token` as a Bearer header into any n8n HTTP node.\r\n\r\n## Microsoft Entra Agent ID platform\r\n\r\nMicrosoft Entra Agent ID supports all three types of AI Agents: assistive agent acting on user's behalf (calssical on-behalf-of flow), autonomous agent acting with its own authorizations and agent user (digital employee). \r\n\r\nThere are three main concepts in Microsoft Entra Agent ID: \r\n - [Agent Identity Blueprint](https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-blueprint): An agent identity blueprint is an object in Microsoft Entra ID that serves as a template for creating agent identities. It establishes the foundation for how agents are created, authenticated, and managed within an organization.\r\n - [Agent Identities](https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-identities): An agent identity is a special service principal in Microsoft Entra ID. It represents an identity that the agent identity blueprint created and is authorized to impersonate. It doesn't have credentials on its own. The agent identity blueprint can acquire tokens on behalf of the agent identity provided the user or tenant admin consented for the agent identity to the corresponding scopes. Autonomous agents acquire app tokens on behalf of the agent identity. Interactive agents called with a user token acquire user tokens on behalf of the agent identity.\r\n - [Agent User](https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-users): Agent users are a specialized identity type designed to bridge the gap between agents and human user capabilities. Agent users enable AI-powered applications to interact with systems and services that require user identities, while maintaining appropriate security boundaries and management controls. It allows organizations to manage those agent's access using similar capabilities as they do for human users. \r\n\r\n> **Note** You must create all the neccessary artefacts and grant consents (authorizations) in Microsoft Entra ID first. You can follow\r\n> the instructions to create [agent identity blueprint](https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/create-blueprint?tabs=powershell) and [agent identities](https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/create-delete-agent-identities?tabs=microsoft-graph-api)\r\n\r\n## Package Components\r\n\r\nThis package ships two complementary components that together cover the full range of Entra Agent ID token acquisition scenarios.\r\n\r\n---\r\n\r\n### EntraAgentID Credential\r\n\r\n`Microsoft Entra Agent ID (Blueprint) credentials` is an n8n credential type. It stores all configuration needed to authenticate as an Agent Identity and prepares a ready-to-use `Bearer` token for use in `Authorization` header of any n8n node.\r\n\r\nWhile this node implements the `authenticate` hook, **the credential always fetches a fresh token** and does not implement any caching. For workflows that make many downstream calls this can add perceptible latency and consume unnecessary Entra ID token-endpoint quota. That is why the [Authentication Manager node](#entra-agent-id-authentication-manager) is the recommended approach for production workflows.\r\n\r\n#### Credential Fields\r\n\r\n| Field | Description |\r\n|---|---|\r\n| **Entra ID Token Endpoint** | Your Entra ID token endpoint, e.g. `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`. The `common` and `organizations` endpoints are **not** supported with Entra Agent ID — you must supply a tenant-specific URL. |\r\n| **Blueprint ID** | The `Application (client) ID` of the Agent Identity Blueprint app registration. |\r\n| **Blueprint Secret** | The `client_secret` of the Agent Identity Blueprint. Stored encrypted by n8n. |\r\n| **Agent ID** | The **object ID** of the Agent Identity (service principal) to authenticate. |\r\n| **On Behalf Of** *(optional)* | Determines the token flow: leave empty for an **autonomous agent** token (app-only). Supply a UPN (e.g. `agent@contoso.com`) to acquire a token on behalf of an **Agent User**. Supply `Bearer <token>` to perform a standard **OBO flow** on behalf of a signed-in human user. |\r\n| **Scope** | The target resource scope, e.g. `https://graph.microsoft.com/.default`. Defaults to `https://graph.microsoft.com/.default`. |\r\n\r\n> **Note:** For instructions on how to create agent identity blueprint, agent identity, agent user and add secret to the blueprint, follow the instructions [here](./readme.entra.agentid.md).\r\n\r\n### Entra Agent ID Authentication Manager\r\n\r\n`Entra Agent ID Authentication Manager` is an n8n **node** (trigger/transform) that sits inside your workflow and explicitly manages token acquisition and caching. It outputs the acquired `access_token` (and metadata) as fields on every item passing through it, so subsequent nodes in your workflow can reference `{{ $json.agent_id_access_token }}` directly.\r\n\r\nIt implements a simple token caching using the static workflow data. Access tokens are encrypted before writing to the cache. Caching layer accounts for the variances of the flows - `agent user` vs `autonomous agent` vs `on-behalf-of` end user.\r\n\r\n#### Why use the Manager instead of the Credential?\r\n\r\n| Concern | Credential only | With Manager node |\r\n|---|---|---|\r\n| Token reuse across calls within the same workflow | No — fresh token per request | Yes — cached and reused until near-expiry |\r\n| Entra ID token-endpoint calls per workflow run | One per HTTP Request node | One per workflow run (on cache miss) |\r\n| Explicit control over caching | Not available | Enable/disable via node property |\r\n| Token visible to subsequent nodes | No | Yes — `agent_id_access_token` on the item |\r\n| Suitable for high-throughput workflows | Limited | Recommended |\r\n\r\nFor any workflow that calls the same protected resource more than once, or that runs frequently, **we recommend placing the Authentication Manager node at the start of your workflow** and using its output token in all downstream HTTP Request nodes via an expression. This minimizes round-trips to the Entra ID token endpoint and keeps your workflow fast.\r\n\r\n#### Token Caching Logic\r\n\r\nThe manager uses n8n **workflow static data** for the cache, which persists across executions within the same running workflow instance.\r\n\r\n- **Cache key isolation** — the cache is split into two tiers:\r\n  - *Global slot* — used when **On Behalf Of** is empty (autonomous agent). A single encrypted token entry is stored.\r\n  - *Per-user slot* — used when **On Behalf Of** is set. Each user identity gets its own slot, keyed by the **SHA-256 hash** of the identity value. For incoming `Bearer` tokens the key is the SHA-256 of the JWT `sub` claim (or the full token string if decoding fails), so raw PII is never written to cache.\r\n\r\n- **Encrypted at rest** — cached tokens are encrypted with **AES-256-GCM** using a key derived from the Blueprint Secret via `scrypt`. The Blueprint Secret itself is never stored in the cache. If the secret is rotated, decryption fails gracefully and a fresh token is fetched automatically.\r\n\r\n- **Expiry with clock-skew buffer** — cached tokens are considered expired **5 minutes before** their actual `expires_in` deadline. This prevents edge cases where a token is valid when read from cache but expired by the time it reaches the downstream service.\r\n\r\n- **Disabling the cache** — when **Enable Token Cache** is set to `false`, all existing cached entries (global and per-user) are wiped at the start of execution, and a fresh token is always fetched. This is useful during development or when you need guaranteed token freshness.\r\n\r\n#### Output Fields\r\n\r\nEach item emitted by the manager carries the following additional JSON fields:\r\n\r\n| Field | Type | Description |\r\n|---|---|---|\r\n| `agent_id_access_token` | `string` | The acquired (or cached) Bearer access token. |\r\n| `cached` | `boolean` | `true` if the token was served from cache, `false` if freshly fetched. |\r\n| `expires_in` | `number` | Remaining token lifetime in seconds at the time of acquisition. |\r\n\r\n#### Authentication Manager Node Properties\r\n\r\n| Property | Description |\r\n|---|---|\r\n| **Credential** | Select an **EntraAgentID** credential (required). All token endpoint, blueprint, and agent settings are read from there. |\r\n| **Operation** | Currently only `Get Token` is available. |\r\n| **Enable Token Cache** | Toggle in-memory token caching. When disabled, cached tokens are wiped and a fresh token is always fetched. Defaults to `true`. |\r\n\r\n## Installation\r\n\r\n### From npm (community nodes)\r\n\r\n1. Open your n8n instance.\r\n2. Go to **Settings → Community Nodes**.\r\n3. Enter `@astaykov/n8n-nodes-EntraAgentID` and click **Install**.\r\n\r\nSee the [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/installation/) for details.\r\n\r\n### Manual installation\r\n\r\n```bash\r\ncd ~/.n8n/nodes\r\nnpm install @astaykov/n8n-nodes-EntraAgentID\r\n```\r\n\r\nRestart n8n after installation.\r\n\r\n## Usage\r\n\r\n### Recommended: Using the Authentication Manager node\r\n\r\n1. Create a credential of type **Microsoft Entra Agent ID (Blueprint) credentials** and fill in all required fields (Token Endpoint, Blueprint ID, Blueprint Secret, Agent ID, and Scope).\r\n2. Add an **Entra Agent ID Authentication Manager** node at the beginning of your workflow and select the credential you just created.\r\n3. Enable **Token Cache** (default) to avoid redundant token fetches across executions.\r\n4. In all downstream **HTTP Request** nodes, set the `Authorization` header to `Bearer {{ $('Entra Agent ID Authentication Manager').item.json.agent_id_access_token }}`.\r\n\r\n### Simple: Using the Credential directly\r\n\r\n1. Create a credential of type **Microsoft Entra Agent ID (Blueprint) credentials**.\r\n2. Fill in the Token Endpoint, Blueprint ID, Blueprint Secret, Agent ID, and Scope.\r\n3. *(Optional)* Set **On Behalf Of** to an agent user UPN or `Bearer <user-token>` for delegated access.\r\n4. Attach this credential to any **HTTP Request** node — the Bearer token is injected automatically on every request.\r\n\r\n## Development\r\n\r\n```bash\r\n# Install dependencies\r\nnpm install\r\n\r\n# Build\r\nnpm run build\r\n\r\n# Lint\r\nnpm run lint\r\n\r\n# Watch mode (TypeScript only, no n8n validation)\r\nnpm run build:watch\r\n```\r\n\r\n## Resources\r\n\r\n- [Microsoft Entra Agent ID Platform documentation](https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/what-is-agent-id-platform)\r\n- [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)\r\n- [Creating n8n community nodes](https://docs.n8n.io/integrations/creating-nodes/)\r\n- [n8n credential documentation](https://docs.n8n.io/integrations/creating-nodes/build/reference/credentials-files/)\r\n\r\n## License\r\n\r\n[MIT](LICENSE)","readmeFilename":"README.md","_rev":"1-fd48b82491b1968a4b5d80a1ebbd1d3e"}