Frequently Asked Questions about the Microsoft Entra SDK for AgentID

General Questions

What is the Microsoft Entra SDK for AgentID?

The Microsoft Entra SDK for AgentID is a containerized web service that handles token acquisition, validation, and secure downstream API calls. It runs as a companion container alongside your application, allowing you to offload identity logic to a dedicated service. By centralizing identity operations in the SDK, you eliminate the need to embed complex token management logic in each service, reducing code duplication and potential security vulnerabilities.

Why would I use the Microsoft Entra SDK for AgentID instead of Microsoft.Identity.Web?

See Comparison Guide for detailed guidance.

Is the Microsoft Entra SDK for AgentID production-ready?

Yes, the SDK is production ready. Refer to the GitHub releases for the latest release status and production readiness guidelines.

Are container images available?

Yes - Refer to the Installation Guide for available images and version tags.

Can I run the SDK outside Kubernetes?

Yes - Refer to the Installation Guide for instructions on running the SDK in Docker Compose or other container environments (Docker Compose, Azure Container Instances, AWS ECS/Fargate, Standalone Docker).

What network ports does the SDK use?

Default port: 5000 (configurable)

The SDK should only be accessible from your application container, never exposed externally.

Deployment

Learn about deployment options, resource requirements, and integration with container platforms like Docker Compose and Kubernetes.

What are the resource requirements?

Yes - see the Installation Guide for resource requirements.

Can I use the SDK with Docker Compose?

Yes - see the Installation Guide for Docker Compose examples.

How do I deploy to AKS with Managed Identity?

Yes - follow the Installation Guide in the Azure Kubernetes Service (AKS) with Managed Identity section.

Configuration

Configure the SDK settings including credentials, downstream APIs, and request overrides to match your deployment requirements.

Is a configuration reference available?

Yes - see the Configuration Reference for detailed configuration options.

Should I use client secrets or certificates?

Prefer certificates over client secrets:

• More secure
• Easier to rotate
• Recommended by Microsoft

Best: Use Managed Identity in Azure (no credentials needed)

See Security Best Practices for guidance.

Can I configure multiple downstream APIs?

Yes. Configure each with its own section:

DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
DownstreamApis__Graph__Scopes: "User.Read"

DownstreamApis__MyApi__BaseUrl: "https://api.contoso.com"
DownstreamApis__MyApi__Scopes: "api://myapi/.default"

How do I override configuration per request?

Use query parameters on endpoints:

# Override scopes
GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read

# Request app token instead of OBO
GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true

# Override relative path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

See Configuration Reference for all options.

Agent Identities

Agent identities enable scenarios where an agent application can operate autonomously or on behalf of a user, with proper context isolation and scoping.

What are agent identities?

Agent identities enable scenarios where an agent application acts either:

• Autonomously - in its own application context
• Interactive - on behalf of the user that called it

See Agent Identities for comprehensive documentation.

When should I use autonomous agent mode?

Use autonomous agent mode for:

• Batch processing without user context
• Background tasks
• System-to-system operations
• Scheduled jobs

Example:

GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>

When should I use interactive agent mode?

Use delegated agent mode for:

• Interactive agent applications
• AI assistants acting on behalf of users
• User-scoped automation
• Personalized workflows

Example:

GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUsername=user@contoso.com

Why can't I use AgentUsername without AgentIdentity?

AgentUsername is a modifier that specifies which user the agent operates on behalf of. It requires AgentIdentity to specify which agent context to use. Without AgentIdentity, the parameter has no meaning.

Why are AgentUsername and AgentUserId mutually exclusive?

They're two ways to identify the same user:

• AgentUsername - User Principal Name (UPN)
• AgentUserId - Object ID (OID)

Allowing both creates ambiguity. Choose the one that fits your scenario:

• Use AgentUsername when you have the user's UPN
• Use AgentUserId when you have the user's object ID

API Usage

The SDK exposes several HTTP endpoints for token acquisition, validation, and downstream API calls with support for both authenticated and unauthenticated flows.

What endpoints does the SDK expose?

• /Validate - Validate token and return claims
• /AuthorizationHeader/{serviceName} - Get authorization header with token
• /AuthorizationHeaderUnauthenticated/{serviceName} - Get token without inbound user token
• /DownstreamApi/{serviceName} - Call downstream API directly
• /DownstreamApiUnauthenticated/{serviceName} - Call downstream API without inbound user token
• /healthz - Health probe

See Endpoints Reference for details.

What's the difference between authenticated and unauthenticated endpoints?

Authenticated: Require bearer token in Authorization header (for OBO flows) Unauthenticated: Don't validate inbound token (for app-only or agent scenarios)

How do I validate a user token?

GET /Validate
Authorization: Bearer <user-token>

Response includes all claims from the token.

How do I get an access token for a downstream API?

GET /AuthorizationHeader/Graph
Authorization: Bearer <user-token>

Response includes authorization header ready to use with downstream API.

Can I override HTTP method or path per request?

Yes, using query parameters:

# Override method
GET /DownstreamApi/Graph?optionsOverride.HttpMethod=POST

# Override path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

Token Caching

The SDK automatically caches tokens in memory to optimize performance and reduce redundant token acquisition requests.

Does the SDK cache tokens?

Yes - the SDK caches tokens in memory by default.

How long are tokens cached?

Tokens are cached until near expiration, then automatically refreshed. Exact duration depends on token lifetime (typically 1 hour for Entra ID tokens).

Can I disable caching?

Token caching is automatic and optimized. There's currently no option to disable it.

Is token cache shared across SDK instances?

No - each SDK instance maintains its own in-memory cache. In high-availability deployments, each pod has independent caching.

Security

Secure SDK deployments follow Microsoft Entra identity and data protection best practices, including managed identity usage, network isolation, and proper credential handling.

Is it safe to run the SDK?

Yes - see the Security Best Practices for security best practices.

Should I expose the SDK externally?

Never - The SDK should only be accessible from your application container. For detailed security best practices, see Security Best Practices.

How should I secure the SDK?

See Security Best Practices for comprehensive guidance.

What credentials should I use?

Preference order:

1. Managed Identity (Azure) - Most secure, no credentials
2. Certificates - Secure, can be rotated
3. Client Secrets - Less preferred, keep in secure vault

Is the SDK compliance-certified?

Check the GitHub repository for current compliance information.

Performance

SDK performance depends on token caching effectiveness and network round-trip latency, with typical response times between 10-50ms for cached tokens.

What's the performance impact of using the SDK?

Typical HTTP round-trip: 10-50ms

Token caching minimizes repeated acquisitions. The first request is slower (token acquisition), subsequent requests use cached tokens.

How does SDK performance compare to in-process libraries?

In-process libraries are faster (no network round-trip) but the SDK provides:

• Language agnostic access
• Centralized configuration
• Shared token cache across services
• Simplified scaling

See Comparison Guide for details.

Can I scale the SDK horizontally?

Yes. Deploy multiple SDK replicas using Kubernetes Deployment. Each pod maintains independent token caching.

Migration

Moving from Microsoft.Identity.Web to the SDK offers advantages in multi-language support, centralized configuration, and simplified scaling across services.

Can I migrate from Microsoft.Identity.Web to the Microsoft Entra SDK for AgentID?

Yes - see the Comparison Guide for detailed migration steps

Support

Get help with issues, find additional documentation, and access community resources through official channels.

Where do I report bugs?

Report issues on the GitHub repository, using the Entra ID template.

Troubleshooting

When you encounter issues with the SDK, refer to the comprehensive troubleshooting guide for diagnostic steps, common problems, and solutions in Troubleshooting Guide.

Where can I get more information?

See Also

• Microsoft Learn Documentation
• Identity Platform Docs
• Agent Identity Platform