Configuring Scalar Authentication with Microsoft Entra ID

Learn how to configure Scalar API documentation to authenticate with Microsoft Entra ID (formerly Azure AD) for testing protected endpoints in ASP.NET Core applications.

Problem Statement

When using Scalar as an alternative to Swagger/SwaggerUI for API documentation, you may encounter authentication issues when testing endpoints that require Microsoft Entra ID authentication. While your frontend application successfully authenticates users and obtains bearer tokens, Scalar doesn't automatically handle this authentication flow, resulting in 401 Unauthorized responses when testing protected APIs.

This guide explains how to configure Scalar to integrate with Microsoft Entra ID's OAuth 2.0 authorization code flow with PKCE, enabling you to test authenticated endpoints directly from your API documentation.

Environment Requirements

• ASP.NET Core 9 Web API
• Microsoft OpenAPI package
• Scalar's ASP.NET integration package
• Microsoft Entra ID app registrations

Configuration Steps

1. OpenAPI Security Scheme Configuration

Configure the OpenAPI security scheme in your Program.cs to define the OAuth 2.0 flow for Microsoft Entra ID:

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((document, context, cancellationToken) =>
    {
        document.Components ??= new OpenApiComponents();

        document.Components.SecuritySchemes.Add(JwtBearerDefaults.AuthenticationScheme, new OpenApiSecurityScheme
        {
            Type = SecuritySchemeType.OAuth2,
            Flows = new OpenApiOAuthFlows
            {
                AuthorizationCode = new OpenApiOAuthFlow
                {
                    AuthorizationUrl = new Uri($"https://login.microsoftonline.com/{builder.Configuration["AzureAD:TenantId"]}/oauth2/v2.0/authorize"),
                    TokenUrl = new Uri($"https://login.microsoftonline.com/{builder.Configuration["AzureAD:TenantId"]}/oauth2/v2.0/token"),
                    Scopes = new Dictionary<string, string>
                    {
                        {builder.Configuration["AzureAd:Scopes"], "Data Access"}
                    },
                    // To allow Scalar to select PKCE by Default
                    // valid options are 'SHA-256' | 'plain' | 'no'
                    Extensions = new Dictionary<string, IOpenApiExtension>()
                    {
                        ["x-usePkce"] = new OpenApiString("SHA-256")
                    }
                }
            }
        });

        // Provide a security requirement for all operations
        document.SecurityRequirements.Add(new OpenApiSecurityRequirement
        {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference
                    {
                        Type = ReferenceType.SecurityScheme,
                        Id = JwtBearerDefaults.AuthenticationScheme
                    }
                },
                // scopes
                [builder.Configuration["AzureAd:Scopes"]]
            }
        });

        return Task.CompletedTask;
    });
});

2. Scalar Configuration

Configure Scalar with authentication options in your Program.cs:

app.MapScalarApiReference(options =>
{
    options.Authentication = new ScalarAuthenticationOptions
    {
        PreferredSecurityScheme = JwtBearerDefaults.AuthenticationScheme,
        OAuth2 = new OAuth2Options
        {
            ClientId = builder.Configuration["AzureAd:ClientId"],
            Scopes = [builder.Configuration["AzureAd:Scopes"]]
        }
    };
});

3. Microsoft Entra ID App Registration Configuration

IMPORTANT

You must configure your Entra ID app registration with the proper redirect URIs and scopes for Scalar to work correctly.

Frontend App Registration:

1. Add a redirect URI for Scalar (typically https://localhost:<port>/scalar/v1)
2. Ensure the client ID matches what you configured in your Scalar options

Backend App Registration:

1. Expose an API with the appropriate scopes
2. The scope format should be: api://<client-id>/<scope-name>

Authentication Endpoints:

Use tenant-specific endpoints instead of the common endpoints:

• Authorization: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
• Token: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token

Configuration Values

Store these values in your configuration (e.g., appsettings.json or user secrets):

{
  "AzureAd": {
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "Scopes": "api://your-client-id/data.read"
  }
}

Common Issues and Solutions

Redirect URI Mismatch

DANGER

Ensure the redirect URI in your Entra ID app registration matches exactly with what Scalar uses (typically https://localhost:<port>/scalar/v1).

Endpoint Configuration

Use tenant-specific endpoints instead of the common endpoints:

• ❌ https://login.microsoftonline.com/common/oauth2/v2.0/authorize
• ✅ https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize

Scope Configuration

Ensure your scopes follow the correct format and are properly exposed in your backend app registration:

// Incorrect scope format (may not work)
Scopes = ["User.Read"]

// Correct scope format
Scopes = ["api://your-client-id/data.read"]

PKCE Configuration

Scalar supports PKCE (Proof Key for Code Exchange) for enhanced security. The configuration includes:

Extensions = new Dictionary<string, IOpenApiExtension>()
{
    ["x-usePkce"] = new OpenApiString("SHA-256")
}

Testing the Configuration

Once configured:

1. Start your application
2. Navigate to the Scalar endpoint (typically /scalar)
3. You should see an Authentication section at the top
4. Select the OAuth 2.0 authentication type
5. Click "Authorize" to initiate the Entra ID authentication flow
6. After successful authentication, you can test protected endpoints

Advanced Configuration

Multiple Security Schemes

If your API supports multiple authentication methods, you can configure multiple security schemes:

document.Components.SecuritySchemes.Add("oauth2", new OpenApiSecurityScheme
{
    Type = SecuritySchemeType.OAuth2,
    // OAuth2 configuration
});

document.Components.SecuritySchemes.Add("bearer", new OpenApiSecurityScheme
{
    Type = SecuritySchemeType.Http,
    Scheme = "bearer",
    BearerFormat = "JWT"
});

Custom Scopes

For APIs with multiple permission levels, define multiple scopes:

Scopes = new Dictionary<string, string>
{
    {"api://client-id/data.read", "Read data"},
    {"api://client-id/data.write", "Write data"},
    {"api://client-id/data.admin", "Admin access"}
}

Troubleshooting

Common Error: IDX10511

If you encounter IDX10511: Signature validation failed errors:

1. Ensure your token validation parameters are correctly configured
2. Verify the issuer and audience claims match your app registration settings
3. Check that the signing keys are being properly resolved

Authentication Not Preselected

If the authentication type isn't preselected in Scalar:

1. Verify that PreferredSecurityScheme matches the security scheme name in your OpenAPI configuration
2. Ensure the security requirement is properly added to the document

Conclusion

Configuring Scalar to authenticate with Microsoft Entra ID enables seamless testing of protected APIs directly from your documentation. By properly setting up the OAuth 2.0 authorization code flow with PKCE, configuring the correct endpoints and scopes, and ensuring proper app registration settings, you can create a secure and user-friendly testing environment for your authenticated APIs.

For the most up-to-date information, always refer to the official Scalar documentation and Microsoft Entra ID documentation.