This example is a simple Spring Boot application that connects to an Azure AI Foundry model using keyless authentication (Microsoft Entra ID) and tests your setup. It keeps Spring AI's ChatClient, backed by the official OpenAI Java SDK and the Azure OpenAI v1 endpoint.
The versions in pom.xml are Spring Boot 4.1.1, Spring AI 2.0.1, OpenAI Java 4.63.1, Azure Identity 1.18.6, and dotenv-java 3.2.0. The sample uses spring-ai-starter-model-openai and explicitly declares openai-java and azure-identity; Spring AI 2 removed the old Azure OpenAI starter.
- Prerequisites
- Quick Start
- How Authentication Works
- Running the Application
- Configuration Reference
- Troubleshooting
- Next Steps
- Resources
Before running this example, ensure you have:
- An Azure AI Foundry resource with a
gpt-5.6-lunadeployment - provision it withazd upor manually via the Azure AI Foundry setup guide - The Cognitive Services OpenAI User role on that resource (the Bicep templates assign this for you)
- The Azure CLI (
az), signed in withaz login - Java 21+ and Maven 3.9+
No API key required — authentication is keyless via Microsoft Entra ID.
# 1. Navigate to project
cd 02-SetupDevEnvironment/examples/basic-chat-azure
# 2. Sign in so keyless auth can get a token
az login
# 3. Configure the endpoint
# - If you ran `azd up`, .env was written for you (skip this).
# - Otherwise copy the template and set AZURE_OPENAI_ENDPOINT:
cp .env.example .env
# 4. Run the application
mvn spring-boot:runThis example authenticates with Microsoft Entra ID — there is no API key.
The application configures authentication explicitly in BasicChatApplication.java:
azureCredential()creates aBearerTokenCredentialusingAuthenticationUtil.getBearerTokenSupplierwithDefaultAzureCredentialand thehttps://ai.azure.com/.defaultscope.azureOpenAiClient()builds anOpenAIClientwithOpenAIOkHttpClient.builder(), resolves the resource endpoint to/openai/v1, and supplies the bearer credential with.credential(...).azureChatModel()supplies that client to Spring AI'sOpenAiChatModel, which backs the lesson'sChatClient.
These explicit beans keep a global OPENAI_API_KEY from overriding Azure authentication. Omitting an API key from YAML alone is not the authentication setup. DefaultAzureCredential can use your az login session locally or a managed identity in Azure; whichever identity is selected must have the resource role listed above.
mvn spring-boot:run- Open the project in VS Code
- Press
F5or use the "Run and Debug" panel - Select "Spring Boot-BasicChatApplication" configuration
Note: The application loads
.envfrom its working directory, including when launched from VS Code.
Illustrative output after a successful run (startup logs omitted; response wording varies):
Starting Basic Chat with Azure OpenAI...
Environment variables loaded from .env file
Endpoint: https://your-resource.openai.azure.com/
Deployment: gpt-5.6-luna
Auth: keyless (Microsoft Entra ID via DefaultAzureCredential)
Connecting to Azure OpenAI...
Sending prompt: What is AI in a short sentence? Max 100 words.
AI Response:
================
AI, or Artificial Intelligence, is the simulation of human intelligence in machines programmed to think and learn like humans.
================
Success! Azure OpenAI connection is working correctly.
| Variable | Description | Required | Example |
|---|---|---|---|
AZURE_OPENAI_ENDPOINT |
Foundry (Azure OpenAI) endpoint URL | Yes | https://my-resource.openai.azure.com/ |
AZURE_OPENAI_DEPLOYMENT |
Chat model deployment name | No | gpt-5.6-luna (default) |
There is no API key variable — authentication is keyless (Microsoft Entra ID via
az login).
The application.yml settings use the spring.ai.openai prefix and flattened chat properties (no options block):
spring:
ai:
openai:
base-url: ${AZURE_OPENAI_ENDPOINT}
microsoft-foundry: true
chat:
model: ${AZURE_OPENAI_DEPLOYMENT:gpt-5.6-luna}
reasoning-effort: none
max-completion-tokens: 500model is the Azure deployment name. Authentication comes from the explicit beans described above, not an api-key setting. The lesson disables reasoning and caps completion tokens at 500; it leaves temperature and the legacy max-tokens unset.
Microsoft recommends the official OpenAI SDK with Azure OpenAI v1 and the Responses API for new applications. Chat Completions remains supported for this existing message-based lesson. For GPT-5.6, requests that include tools on Chat Completions must set reasoning_effort to none; use Responses when combining reasoning with tools. See tool calling with reasoning models.
Error: 401 / "PermissionDenied" / token errors
- Run
az login— keyless auth needs an active sign-in to get a token - Verify your account has the Cognitive Services OpenAI User role on the resource
- If you just assigned the role, wait a minute for it to propagate
- Confirm you're in the right tenant/subscription (
az account show)
Error: "The endpoint is not valid" / connection errors
- Ensure
AZURE_OPENAI_ENDPOINTis the full base URL (e.g.,https://your-resource.openai.azure.com/) - Check for trailing slash consistency
- Verify the endpoint matches your provisioned resource (
azd env get-values)
Error: "The deployment was not found"
- Verify
AZURE_OPENAI_DEPLOYMENTmatches a deployment name in Azure - Check that the model is successfully deployed and active
- The default deployment name is
gpt-5.6-luna
Error: 429 / rate limit exceeded
- The default GPT-5.6 Luna deployment has Global Standard capacity 10: 10 requests/minute and 10,000 tokens/minute
- Run examples sequentially and wait for the service's retry interval before retrying
- This basic example disables automatic SDK retries, so a failed request is reported directly
VS Code: Environment variables not loading
- Ensure your
.envfile is in the project root directory (same level aspom.xml) - Try running
mvn spring-boot:runin VS Code's integrated terminal - Check that the VS Code Java extension is properly installed
To enable detailed logging, uncomment these lines in application.yml:
logging:
level:
"[org.springframework.ai]": DEBUG
"[com.azure]": DEBUGSetup Complete! Continue your learning journey: