🔍 Code Extractor

A data class representing configuration settings for an application that implements a web API, specifically for Azure AD application registration.

Purpose

This class encapsulates the API-specific settings for an Azure AD application registration. It manages three key aspects: claim mapping acceptance, known client applications for consent bundling, and OAuth2 permission scopes. It inherits from ClientValue, making it suitable for serialization and transmission in API requests to Microsoft Graph or Azure AD endpoints. The class is primarily used when configuring or updating web API applications in Azure Active Directory.

Source Code

class ApiApplication(ClientValue):
    """Specifies settings for an application that implements a web API."""

    def __init__(
        self,
        accept_mapped_claims=None,
        known_client_applications=None,
        oauth2_permission_scopes=None,
    ):
        """
        :param str accept_mapped_claims: When true, allows an application to use claims mapping without specifying
            a custom signing key.
        :param list[str] known_client_applications: Used for bundling consent if you have a solution that contains
            two parts: a client app and a custom web API app. If you set the appID of the client app to this value,
            the user only consents once to the client app. Azure AD knows that consenting to the client means
            implicitly consenting to the web API and automatically provisions service principals for both APIs
            at the same time. Both the client and the web API app must be registered in the same tenant.
        :param list[PermissionScope] oauth2_permission_scopes: The definition of the delegated permissions exposed
            by the web API represented by this application registration. These delegated permissions may be requested
            by a client application, and may be granted by users or administrators during consent.
            Delegated permissions are sometimes referred to as OAuth 2.0 scopes.
        """
        self.acceptMappedClaims = accept_mapped_claims
        self.knownClientApplications = StringCollection(known_client_applications)
        self.oauth2PermissionScopes = ClientValueCollection(
            PermissionScope, oauth2_permission_scopes
        )

Parameters

Parameter Details

accept_mapped_claims: A boolean flag (str type) that when set to true, allows the application to use claims mapping without requiring a custom signing key. This simplifies authentication scenarios where claim transformation is needed. Can be None if not specified.

known_client_applications: A list of application IDs (strings) representing client applications that are bundled with this web API for consent purposes. When a user consents to a client app in this list, they implicitly consent to this web API as well, streamlining the consent process. Both applications must be registered in the same Azure AD tenant. Can be None or an empty list.

oauth2_permission_scopes: A list of PermissionScope objects defining the delegated permissions (OAuth 2.0 scopes) that this web API exposes. These permissions can be requested by client applications and granted by users or administrators during the consent flow. Can be None or an empty list.

Return Value

Instantiation returns an ApiApplication object with three attributes: acceptMappedClaims (boolean/str), knownClientApplications (StringCollection), and oauth2PermissionScopes (ClientValueCollection of PermissionScope objects). The class does not define any methods that return values beyond the constructor.

Class Interface

Methods

Attributes

Dependencies

• office365

Required Imports

from office365.directory.permissions.scope import PermissionScope
from office365.runtime.client_value import ClientValue
from office365.runtime.client_value_collection import ClientValueCollection
from office365.runtime.types.collections import StringCollection

Usage Example

from office365.directory.permissions.scope import PermissionScope
from office365.directory.applications.api_application import ApiApplication

# Create permission scopes for the API
read_scope = PermissionScope()
read_scope.id = 'scope-id-1'
read_scope.value = 'API.Read'
read_scope.adminConsentDisplayName = 'Read API data'
read_scope.adminConsentDescription = 'Allows the app to read API data'

write_scope = PermissionScope()
write_scope.id = 'scope-id-2'
write_scope.value = 'API.Write'
write_scope.adminConsentDisplayName = 'Write API data'
write_scope.adminConsentDescription = 'Allows the app to write API data'

# Create ApiApplication instance
api_app = ApiApplication(
    accept_mapped_claims=True,
    known_client_applications=['client-app-id-1', 'client-app-id-2'],
    oauth2_permission_scopes=[read_scope, write_scope]
)

# Access attributes
print(api_app.acceptMappedClaims)  # True
print(api_app.knownClientApplications)  # StringCollection with client app IDs
print(api_app.oauth2PermissionScopes)  # ClientValueCollection with PermissionScope objects

Best Practices

• Always ensure that client application IDs in known_client_applications are registered in the same Azure AD tenant as the web API
• When defining oauth2_permission_scopes, ensure each PermissionScope has a unique ID and value
• Set accept_mapped_claims to true only when you understand the security implications and don't need custom signing keys
• This class is typically used as part of a larger Application object when creating or updating Azure AD application registrations
• The class inherits from ClientValue, which means it's designed for serialization - ensure all nested objects (PermissionScope) are also properly serializable
• When passing None for any parameter, the corresponding attribute will still be initialized with an appropriate collection type (StringCollection or ClientValueCollection)
• This is an immutable-style data class - attributes are set during initialization and typically not modified afterward
• Use this class in conjunction with Microsoft Graph API calls to configure web API applications programmatically

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class WebApplication 76.6% similar

  A data class that encapsulates configuration settings for a web application, including home page URL, logout URL, and redirect URIs for OAuth 2.0 authentication flows.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/applications/web.py

• class PublicClientApplication 69.4% similar

  A configuration class that specifies settings for public client applications such as mobile apps, desktop applications, or other non-web clients that cannot securely store client secrets.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/applications/public_client.py

• class Application 67.0% similar

  Represents an Azure Active Directory (Azure AD) application registration, providing methods to manage application credentials, certificates, passwords, and publisher verification.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/applications/application.py

• class SpaApplication 64.0% similar

  A class representing configuration settings for a single-page application (SPA), specifically managing redirect URIs used in OAuth/authentication flows.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/applications/spa.py

• class ApiAuthenticationConfigurationBase 61.0% similar

  Base class for holding authentication configuration information when calling APIs, serving as a parent class for various authentication types.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/authentication/configuration_base.py