Well-Known Endpoints and Protecting Custom APIs with Microsoft Entra: A Developer's Guide

Introduction

In my journey as a developer working with Microsoft Entra (formerly Azure AD), I've encountered numerous scenarios where understanding well-known endpoints and API protection mechanisms became crucial for building secure applications. Today, I want to share my personal experience and knowledge about these fundamental concepts that every developer should understand when working with Microsoft's identity platform.

This guide will explore two critical aspects:

1. Well-Known Endpoints in Microsoft Entra and their role in OpenID Connect discovery

2. Protecting Custom APIs using Microsoft Entra authentication and authorization

What are Well-Known Endpoints?

Well-known endpoints are standardized URLs that provide discovery information for OpenID Connect providers. In the context of Microsoft Entra, these endpoints serve metadata about the identity provider's capabilities, supported flows, and configuration details.

The OpenID Connect Discovery Document

Microsoft Entra exposes a well-known configuration document at a predictable URL pattern:

https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration

Where {tenant} can be:

• common - For multi-tenant applications

• organizations - For work/school accounts only

• consumers - For personal Microsoft accounts only

• {tenant-id} - For single-tenant applications

What Information Does the Well-Known Endpoint Provide?

When you make a GET request to the well-known endpoint, you receive a JSON document containing:

{
  "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
  "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
  "token_endpoint_auth_methods_supported": ["client_secret_post", "private_key_jwt"],
  "jwks_uri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
  "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
  "subject_types_supported": ["pairwise"],
  "response_types_supported": ["code", "id_token", "token", "code id_token"],
  "scopes_supported": ["openid", "profile", "email", "offline_access"],
  "issuer": "https://login.microsoftonline.com/{tenant}/v2.0",
  "claims_supported": ["sub", "iss", "aud", "exp", "iat", "auth_time", "name", "email"]
}

Why Well-Known Endpoints Matter

From my experience, well-known endpoints are essential because they:

1. Enable Dynamic Discovery: Applications can programmatically discover endpoint URLs instead of hardcoding them

2. Support Multi-Tenant Scenarios: Different tenants may have slightly different configurations

3. Facilitate Library Integration: Most authentication libraries automatically consume these endpoints

4. Ensure Future Compatibility: Microsoft can update endpoint URLs without breaking applications

Protecting Custom APIs with Microsoft Entra

Now, let's dive into the practical aspect of protecting custom APIs using Microsoft Entra. I'll use a Python Flask API as an example to demonstrate the concepts.

Architecture Overview

Here's how the authentication flow works when protecting a custom API:

Step 1: Register Your API in Microsoft Entra

First, you need to register your custom API as an application in Microsoft Entra:

1. Navigate to the Microsoft Entra admin center

2. Go to App registrations → New registration

3. Configure your API application:

   • Name: my-custom-api

   • Account types: Choose based on your requirements

   • Redirect URI: Not needed for API-only applications

Step 2: Expose API Scopes

After registration, expose your API by defining scopes:

1. Go to Expose an API

2. Set the Application ID URI (e.g., api://my-custom-api)

3. Add scopes such as:

   • api://my-custom-api/Data.Read

   • api://my-custom-api/Data.Write

Step 3: Create a Sample Python API

Here's a simple Flask API that demonstrates token validation:

from flask import Flask, request, jsonify
import jwt
import requests
from functools import wraps
import json

app = Flask(__name__)

# Configuration
TENANT_ID = "your-tenant-id"
CLIENT_ID = "your-api-client-id"  # The API's client ID
WELL_KNOWN_URL = f"https://login.microsoftonline.com/{TENANT_ID}/v2.0/.well-known/openid-configuration"

def get_signing_keys():
    """Fetch public keys from Microsoft Entra"""
    try:
        # Get well-known configuration
        config_response = requests.get(WELL_KNOWN_URL)
        config_response.raise_for_status()
        config = config_response.json()
        
        # Get JWKS (JSON Web Key Set)
        jwks_response = requests.get(config['jwks_uri'])
        jwks_response.raise_for_status()
        return jwks_response.json()
    except Exception as e:
        print(f"Error fetching signing keys: {e}")
        return None

def validate_token(token):
    """Validate the JWT token"""
    try:
        # Decode header to get key ID
        header = jwt.get_unverified_header(token)
        kid = header.get('kid')
        
        if not kid:
            return None, "No key ID found in token header"
        
        # Get public keys
        jwks = get_signing_keys()
        if not jwks:
            return None, "Unable to fetch signing keys"
        
        # Find the matching key
        public_key = None
        for key in jwks.get('keys', []):
            if key.get('kid') == kid:
                public_key = jwt.algorithms.RSAAlgorithm.from_jwk(json.dumps(key))
                break
        
        if not public_key:
            return None, "No matching public key found"
        
        # Validate the token
        payload = jwt.decode(
            token,
            public_key,
            algorithms=['RS256'],
            audience=f"api://{CLIENT_ID}",
            issuer=f"https://login.microsoftonline.com/{TENANT_ID}/v2.0"
        )
        
        return payload, None
    except jwt.ExpiredSignatureError:
        return None, "Token has expired"
    except jwt.InvalidAudienceError:
        return None, "Invalid audience"
    except jwt.InvalidIssuerError:
        return None, "Invalid issuer"
    except Exception as e:
        return None, f"Token validation failed: {str(e)}"

def require_auth(required_scope=None):
    """Decorator to require authentication"""
    def decorator(f):
        @wraps(f)
        def decorated_function(*args, **kwargs):
            # Get token from Authorization header
            auth_header = request.headers.get('Authorization')
            if not auth_header or not auth_header.startswith('Bearer '):
                return jsonify({'error': 'Missing or invalid Authorization header'}), 401
            
            token = auth_header.split(' ')[1]
            
            # Validate token
            payload, error = validate_token(token)
            if error:
                return jsonify({'error': error}), 401
            
            # Check scope if required
            if required_scope:
                scopes = payload.get('scp', '').split(' ')
                if required_scope not in scopes:
                    return jsonify({'error': f'Insufficient scope. Required: {required_scope}'}), 403
            
            # Add user info to request context
            request.current_user = payload
            return f(*args, **kwargs)
        
        return decorated_function
    return decorator

# API Endpoints
@app.route('/api/data', methods=['GET'])
@require_auth('Data.Read')
def get_data():
    """Protected endpoint requiring Data.Read scope"""
    return jsonify({
        'message': 'Successfully accessed protected data',
        'user': request.current_user.get('name', 'Unknown'),
        'scopes': request.current_user.get('scp', '').split(' ')
    })

@app.route('/api/data', methods=['POST'])
@require_auth('Data.Write')
def create_data():
    """Protected endpoint requiring Data.Write scope"""
    data = request.get_json()
    return jsonify({
        'message': 'Data created successfully',
        'data': data,
        'created_by': request.current_user.get('name', 'Unknown')
    })

@app.route('/health', methods=['GET'])
def health_check():
    """Public health check endpoint"""
    return jsonify({'status': 'healthy'})

if __name__ == '__main__':
    app.run(debug=True, port=5000)

Step 4: Configure API Management Protection

If you're using Azure API Management, you can configure JWT validation policies:

<policies>
    <inbound>
        <validate-jwt header-name="Authorization" failed-validation-httpcode="401" 
                     failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
            <openid-config url="https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration" />
            <audiences>
                <audience>api://my-custom-api</audience>
            </audiences>
            <issuers>
                <issuer>https://login.microsoftonline.com/{tenant-id}/v2.0</issuer>
            </issuers>
            <required-claims>
                <claim name="scp" match="any">
                    <value>Data.Read</value>
                    <value>Data.Write</value>
                </claim>
            </required-claims>
        </validate-jwt>
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Step 5: Client Application Configuration

Here's how a client application would obtain and use tokens:

import requests
import json

# Client credentials (for daemon/service applications)
TENANT_ID = "your-tenant-id"
CLIENT_ID = "your-client-app-id"
CLIENT_SECRET = "your-client-secret"
SCOPE = "api://my-custom-api/.default"  # Or specific scopes

def get_access_token():
    """Get access token using client credentials flow"""
    token_url = f"https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token"
    
    data = {
        'grant_type': 'client_credentials',
        'client_id': CLIENT_ID,
        'client_secret': CLIENT_SECRET,
        'scope': SCOPE
    }
    
    response = requests.post(token_url, data=data)
    response.raise_for_status()
    
    return response.json()['access_token']

def call_protected_api():
    """Call the protected API"""
    token = get_access_token()
    
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    
    # Call the API
    response = requests.get('https://your-api.com/api/data', headers=headers)
    
    if response.status_code == 200:
        print("API call successful:", response.json())
    else:
        print("API call failed:", response.status_code, response.text)

# Example usage
if __name__ == "__main__":
    call_protected_api()

Best Practices from My Experience

Throughout my journey with Microsoft Entra and API protection, I've learned several important best practices:

1. Token Validation

• Always validate the token signature using public keys from the JWKS endpoint

• Verify the aud (audience) claim matches your API's identifier

• Check the iss (issuer) claim to ensure it's from Microsoft Entra

• Validate token expiration (exp) and not-before (nbf) claims

2. Scope-Based Authorization

• Design granular scopes that represent specific permissions

• Use descriptive scope names (e.g., Data.Read, Users.Write)

• Implement scope checking in your API endpoints

3. Error Handling

• Return appropriate HTTP status codes (401 for authentication, 403 for authorization)

• Provide meaningful error messages without exposing sensitive information

• Log security events for monitoring and auditing

4. Performance Considerations

• Cache public keys with appropriate TTL

• Use connection pooling for HTTP requests

• Consider implementing token validation at the gateway level

5. Security Considerations

• Use HTTPS for all communications

• Implement rate limiting to prevent abuse

• Regular security audits and token rotation

• Monitor for suspicious activity

Troubleshooting Common Issues

Based on my experience, here are common issues and their solutions:

Issue 1: "Invalid Audience" Error

Problem: Token validation fails with audience mismatch Solution: Ensure the audience claim in the token matches your API's Application ID URI

Issue 2: "Invalid Signature" Error

Problem: JWT signature validation fails Solution: Verify you're using the correct public keys from the JWKS endpoint and handling key rotation

Issue 3: "Insufficient Scope" Error

Problem: User lacks required permissions Solution: Check that the client application has been granted the necessary scopes and admin consent if required

Conclusion

Understanding well-known endpoints and API protection with Microsoft Entra is crucial for building secure, modern applications. The well-known discovery document provides a standardized way to obtain configuration information, while proper API protection ensures that only authorized clients can access your resources.

Key takeaways from my journey:

1. Leverage Well-Known Endpoints: Use the discovery document for dynamic configuration

2. Implement Proper Token Validation: Always validate signatures, claims, and expiration

3. Design Granular Scopes: Create meaningful permissions that align with your business logic

4. Follow Security Best Practices: Use HTTPS, implement rate limiting, and monitor for threats

5. Plan for Scale: Consider performance implications and caching strategies

By following these patterns and practices, you'll be well-equipped to implement secure API protection using Microsoft Entra in your applications. Remember, security is not a one-time implementation but an ongoing process that requires regular review and updates.

Additional Resources

• Microsoft Entra Documentation

• OpenID Connect Protocol

• JWT.io - JWT Debugger

• Microsoft Graph API Documentation

---

This blog post reflects my personal experience and learnings while working with Microsoft Entra and API security. I hope this guide helps you in your own journey with identity and access management!