graphql-dotnet-server

The server can be integrated into the ASP.NET Core pipeline using several different patterns:

1. Middleware: Configure via IApplicationBuilder or IEndpointRouteBuilder to serve requests as middleware.
2. Route Handlers: Use .NET 6+ route handlers (e.g., MapGet, MapPost) by returning specific result types:
   • GraphQLExecutionHttpResult: For direct GraphQL execution.
   • ExecutionResultHttpResult: For returning pre-executed GraphQL responses.
3. MVC Controllers: Return GraphQL responses from controller actions using:
   • GraphQLExecutionActionResult
   • ExecutionResultActionResult

Authorization Support

Includes AuthorizationValidationRule which validates that the schema, output graph types, fields, and query arguments meet the policies or roles defined in the ASP.NET Core authorization framework.

Note: It does not validate policies/roles for input graph types, input fields, or directives. It skips validation for fields/fragments marked with @skip or @include.

The ASP.NET Core GraphQL server supports multiple request types and protocols:

HTTP Transport

Compatible with the GraphQL over HTTP draft specification.

• GET: Processes requests from the query string.
• POST: Supports JSON requests, form submissions, and raw GraphQL strings.
• Multipart Requests: Supports the GraphQL multipart request spec for file uploads via operations and map parameters.

WebSocket Transport

Supports GraphQL subscriptions via the following protocols:

• graphql-ws (enisdenjo/graphql-ws)
• subscriptions-transport-ws (apollographql/subscriptions-transport-ws)

All message formats are JSON-based.

Authorization can be configured at the endpoint level or for individual graph types, fields, and arguments.

Endpoint Authorization

Checks authorization requirements for the entire endpoint (including introspection) before parsing or executing the document. Configure this via the UseGraphQL options delegate.

Field and Type Authorization

To enable ASP.NET Core authorization validation for individual fields/types, call .AddAuthorizationRule() during GraphQL service configuration. You can then use .Authorize() or the [Authorize] attribute on schema elements.

Note: Authorization rules do not apply to input types or fields of input types.

// Endpoint authorization
app.UseGraphQL("/graphql", config =>
{
    config.AuthorizationRequired = true;
    config.AuthorizedRoles.Add("MyRole");
    config.AuthorizedPolicy = "MyPolicy";
});

// Field/Type authorization
builder.Services.AddGraphQL(b => b
    .AddAutoSchema<Query>()
    .AddSystemTextJson()
    .AddAuthorizationRule());

v7 introduces a new, simplified authorization system integrated into Transports.AspNetCore.

Warning: Authorization rules on input types are ignored in v7.

Migration Steps:

1. Remove the GraphQL.Server.Authorization.AspNetCore NuGet package.
2. Replace .AddGraphQLAuthorization(...) with .AddAuthorizationRule() in your service configuration.
3. Use standard ASP.NET Core services.AddAuthorization(...) for your policy configuration.

New Authorization Features:

• Authorize()
• AuthorizeWithRole(string role)
• AllowAnonymous()
• Security fix: Authorization failure messages no longer reveal specific requirements to the caller.

// v6
services.AddGraphQL(b => b
    .AddGraphQLAuthorization(options => {
        // ASP.NET authorization configuration
    })
    // other code
);

// v7
services.AddGraphQL(b => b
    .AddAuthorizationRule()
    // other code
);
services.AddAuthorization(options => {
    // ASP.NET authorization configuration
});

You can register the same endpoint multiple times to apply different authorization rules to different HTTP methods (e.g., allowing GET for queries but requiring authentication for POST/WebSockets).

Note: It is recommended to instead use the AddAuthorizationRule() and apply authorization metadata directly to your schema's Mutation and Subscription parts to avoid complexity.

Example of transport-specific configuration:

var app = builder.Build();
app.UseDeveloperExceptionPage();
// Allow unauthenticated GET requests
app.UseGraphQL("/graphql", options =>
{
    options.HandleGet = true;
    options.HandlePost = false;
    options.HandleWebSockets = false;
    options.AuthorizationRequired = false;
});
// Require authentication for POST and WebSockets
app.UseGraphQL("/graphql", options =>
{
    options.HandleGet = false;
    options.HandlePost = true;
    options.HandleWebSockets = true;
    options.AuthorizationRequired = true;
});
await app.RunAsync();

By default, the middleware does not send keep-alive packets. To prevent clients from being disconnected by the OS or network due to inactivity, configure KeepAliveTimeout and KeepAliveMode in GraphQLWebSocketOptions.

For the graphql-transport-ws sub-protocol, you can choose from several KeepAliveMode values:

• Default: Same as Timeout.
• Timeout: Sends a unidirectional keep-alive message when no message has been received within the specified timeout period.
• Interval: Sends a unidirectional keep-alive message at a fixed interval.
• TimeoutWithPayload: Sends a bidirectional keep-alive message with a payload on a fixed interval. This is useful for high-traffic servers to ensure the client is still processing messages.

Example configuration:

app.UseGraphQL("/graphql", options =>
{
    // configure keep-alive packets
    options.WebSockets.KeepAliveTimeout = TimeSpan.FromSeconds(10);
    options.WebSockets.KeepAliveMode = KeepAliveMode.TimeoutWithPayload;
    // enforce the graphql-transport-ws sub-protocol
    options.WebSockets.SupportedWebSocketSubProtocols = [GraphQLWs.SubscriptionServer.SubProtocol];
});