fix: accept api://botid-{app_id} audience format in token validation (#314)

## Summary
- Add `api://botid-{app_id}` to the valid audiences list in
`TokenValidator.for_service()` and `TokenValidator.for_entra()`,
matching the TypeScript SDK behavior (teams.ts#469)
- Bot Framework tokens issued for bots registered with Entra ID use this
audience format and were being rejected with a 401
- Add `application_id_uri` option to `AppOptions` — matches
`webApplicationInfo.resource` in the Teams app manifest — for custom
audience values in Entra token validation
- Add parametrized test covering all three default audience formats and
tests for `application_id_uri`

## Test plan
- [x] All 24 token validator tests pass
- [x] Verify with a bot registered via Entra ID that tokens with
`aud=api://botid-{app_id}` are accepted
- [x] Verify custom `application_id_uri` audiences are accepted

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: heyitsaamir

packages/apps/src/microsoft_teams/apps/app.py

@@ -151,7 +151,9 @@ def __init__(self, **options: Unpack[AppOptions]):
         self.entra_token_validator: Optional[TokenValidator] = None
         if self.credentials and hasattr(self.credentials, "client_id"):
             self.entra_token_validator = TokenValidator.for_entra(
-                self.credentials.client_id, self.credentials.tenant_id
+                self.credentials.client_id,
+                self.credentials.tenant_id,
+                application_id_uri=self.options.application_id_uri,
             )
 
     @property

packages/apps/src/microsoft_teams/apps/auth/token_validator.py

@@ -47,6 +47,10 @@ def __init__(self, jwt_validation_options: JwtValidationOptions):
         self.options = jwt_validation_options
         self._jwks_client = jwt.PyJWKClient(jwt_validation_options.jwks_uri)
 
+    @staticmethod
+    def _default_audiences(app_id: str) -> List[str]:
+        return [app_id, f"api://{app_id}", f"api://botid-{app_id}"]
+
     # ----- Factory constructors -----
     @classmethod
     def for_service(cls, app_id: str, service_url: Optional[str] = None) -> "TokenValidator":
@@ -60,30 +64,41 @@ def for_service(cls, app_id: str, service_url: Optional[str] = None) -> "TokenVa
 
         options = JwtValidationOptions(
             valid_issuers=["https://api.botframework.com"],
-            valid_audiences=[app_id, f"api://{app_id}"],
+            valid_audiences=cls._default_audiences(app_id),
             jwks_uri="https://login.botframework.com/v1/.well-known/keys",
             service_url=service_url,
         )
         return cls(options)
 
     @classmethod
-    def for_entra(cls, app_id: str, tenant_id: Optional[str], scope: Optional[str] = None) -> "TokenValidator":
+    def for_entra(
+        cls,
+        app_id: str,
+        tenant_id: Optional[str],
+        scope: Optional[str] = None,
+        application_id_uri: Optional[str] = None,
+    ) -> "TokenValidator":
         """Create a validator for Entra ID tokens.
 
         Args:
             app_id: The app's Microsoft App ID (used for audience validation)
             tenant_id: The Azure AD tenant ID
             scope: Optional scope that must be present in the token
+            application_id_uri: Optional Application ID URI from Azure portal.
+                Matches webApplicationInfo.resource in the app manifest.
 
         """
 
         valid_issuers: List[str] = []
         if tenant_id:
             valid_issuers.append(f"https://login.microsoftonline.com/{tenant_id}/v2.0")
         tenant_id = tenant_id or "common"
+        valid_audiences = cls._default_audiences(app_id)
+        if application_id_uri:
+            valid_audiences.append(application_id_uri)
         options = JwtValidationOptions(
             valid_issuers=valid_issuers,
-            valid_audiences=[app_id, f"api://{app_id}"],
+            valid_audiences=valid_audiences,
             jwks_uri=f"https://login.microsoftonline.com/{tenant_id}/discovery/v2.0/keys",
             scope=scope,
         )

packages/apps/src/microsoft_teams/apps/options.py

@@ -25,6 +25,9 @@ class AppOptions(TypedDict, total=False):
     """The client secret. If provided with client_id, uses ClientCredentials auth."""
     tenant_id: Optional[str]
     """The tenant ID. Required for single-tenant apps."""
+    application_id_uri: Optional[str]
+    """Application ID URI from the Azure portal. Used for user authentication.
+    Matches webApplicationInfo.resource in the app manifest."""
     # Custom token provider function
     token: Optional[Callable[[Union[str, list[str]], Optional[str]], Union[str, Awaitable[str]]]]
     """Custom token provider function. If provided with client_id (no client_secret), uses TokenCredentials."""
@@ -86,6 +89,9 @@ class InternalAppOptions:
     """The client secret. If provided with client_id, uses ClientCredentials auth."""
     tenant_id: Optional[str] = None
     """The tenant ID. Required for single-tenant apps."""
+    application_id_uri: Optional[str] = None
+    """Application ID URI from the Azure portal. Used for user authentication.
+    Matches webApplicationInfo.resource in the app manifest."""
     token: Optional[Callable[[Union[str, list[str]], Optional[str]], Union[str, Awaitable[str]]]] = None
     """Custom token provider function. If provided with client_id (no client_secret), uses TokenCredentials."""
     managed_identity_client_id: Optional[str] = None

packages/apps/tests/test_token_validator.py

@@ -66,7 +66,11 @@ def test_init(self):
         validator = TokenValidator.for_service("test-app-id")
 
         assert validator.options.valid_issuers == ["https://api.botframework.com"]
-        assert validator.options.valid_audiences == ["test-app-id", "api://test-app-id"]
+        assert validator.options.valid_audiences == [
+            "test-app-id",
+            "api://test-app-id",
+            "api://botid-test-app-id",
+        ]
         assert validator.options.jwks_uri == "https://login.botframework.com/v1/.well-known/keys"
 
     @pytest.mark.asyncio
@@ -129,6 +133,33 @@ async def test_validate_token_decode_error(self, validator, mock_jwks_client):
             with pytest.raises(jwt.InvalidTokenError):
                 await validator.validate_token(token)
 
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "audience",
+        [
+            "test-app-id",
+            "api://test-app-id",
+            "api://botid-test-app-id",
+        ],
+        ids=["app_id", "api://app_id", "api://botid-app_id"],
+    )
+    async def test_validate_token_accepts_all_audience_formats(self, mock_jwks_client, audience):
+        """Test that all three audience formats are accepted."""
+        validator = TokenValidator.for_service("test-app-id")
+        validator._jwks_client = mock_jwks_client
+        token = "valid.jwt.token"
+        payload = {
+            "iss": "https://api.botframework.com",
+            "aud": audience,
+            "serviceurl": "https://smba.trafficmanager.net/teams",
+            "exp": 9999999999,
+            "iat": 1000000000,
+        }
+
+        with patch("jwt.decode", return_value=payload):
+            result = await validator.validate_token(token)
+            assert result["aud"] == audience
+
     @pytest.mark.asyncio
     async def test_validate_token_invalid_audience(self, validator, mock_jwks_client):
         """Test validation with invalid audience."""
@@ -220,7 +251,7 @@ def test_for_entra_initialization(self, validator_entra):
         """Check Entra-specific initialization."""
         options = validator_entra.options
         assert options.valid_issuers == ["https://login.microsoftonline.com/test-tenant-id/v2.0"]
-        assert options.valid_audiences == ["test-app-id", "api://test-app-id"]
+        assert options.valid_audiences == ["test-app-id", "api://test-app-id", "api://botid-test-app-id"]
         assert options.jwks_uri == "https://login.microsoftonline.com/test-tenant-id/discovery/v2.0/keys"
         assert options.scope == "user.read"
 
@@ -271,6 +302,22 @@ async def test_validate_entra_token_invalid_issuer(self, validator_entra, mock_j
             with pytest.raises(jwt.InvalidTokenError):
                 await validator_entra.validate_token(token)
 
+    def test_for_entra_with_application_id_uri(self):
+        """Check that applicationIdUri is included in valid audiences."""
+        validator = TokenValidator.for_entra(
+            app_id="test-app-id",
+            tenant_id="test-tenant-id",
+            application_id_uri="api://my-app.contoso.com/test-app-id",
+        )
+        options = validator.options
+        assert "api://my-app.contoso.com/test-app-id" in options.valid_audiences
+
+    def test_for_entra_without_application_id_uri(self):
+        """Check that audiences are default when applicationIdUri is not provided."""
+        validator = TokenValidator.for_entra(app_id="test-app-id", tenant_id="test-tenant-id")
+        options = validator.options
+        assert options.valid_audiences == ["test-app-id", "api://test-app-id", "api://botid-test-app-id"]
+
     @pytest.mark.asyncio
     async def test_validate_entra_token_invalid_audience(self, validator_entra, mock_jwks_client):
         """Fail validation for invalid audience."""