La correcta definición de los esquemas de seguridad en una API es fundamental para garantizar la autenticación y autorización de los consumidores. Swagger / OpenAPI proporciona un mecanismo estandarizado mediante securitySchemes, permitiendo documentar y aplicar distintos métodos de seguridad como Bearer Tokens, OAuth2, API Keys, Basic Auth y OpenID Connect.

A continuación se presenta una guía técnica optimizada para SEO, acompañada de ejemplos prácticos implementados en C# (.NET).

---

Tabla Comparativa de Esquemas de Seguridad en OpenAPI

Esquema de Seguridad	Tipo	Nivel de Seguridad	Caso de Uso Ideal	Pros	Contras
Bearer Token (JWT)	http / bearer	Alto	APIs REST, microservicios	Rápido, stateless, estándar	Requiere gestión de expiración y revocación
OAuth2 (Authorization Code, Password, Client Credentials, Implicit)	oauth2	Muy Alto	Aplicaciones web, móviles, enterprise	Flexible, seguro, estándar industrial	Configuración compleja
API Key	apiKey	Medio	APIs públicas, servicios internos	Fácil de implementar	No identifica al usuario
Basic Authentication	http / basic	Bajo	Integraciones simples, entornos controlados	Fácil	Credenciales expuestas si no hay HTTPS
OpenID Connect (OIDC)	openIdConnect	Muy Alto	Autenticación de usuario final	Permite identidad + OAuth2	Requiere proveedor OIDC

---

1. Bearer Authentication (JWT) en Swagger + .NET

Definición en OpenAPI

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

Implementación en .NET (Program.cs)

builder.Services.AddAuthentication("Bearer")
    .AddJwtBearer("Bearer", options =>
    {
        options.Authority = "https://example.com/";
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateAudience = false
        };
    });

builder.Services.AddSwaggerGen(c =>
{
    c.AddSecurityDefinition("BearerAuth", new OpenApiSecurityScheme
    {
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT",
        In = ParameterLocation.Header
    });

    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Id = "BearerAuth",
                    Type = ReferenceType.SecurityScheme
                }
            },
            new string[] {}
        }
    });
});

---

2. OAuth2 (Authorization Code) en Swagger + .NET

Definición en OpenAPI

securitySchemes:
  OAuth2Auth:
    type: oauth2
    flows:
      authorizationCode:
        authorizationUrl: https://example.com/oauth/authorize
        tokenUrl: https://example.com/oauth/token
        scopes:
          read: Grants read access
          write: Grants write access

Implementación en Swagger (.NET)

c.AddSecurityDefinition("OAuth2Auth", new OpenApiSecurityScheme
{
    Type = SecuritySchemeType.OAuth2,
    Flows = new OpenApiOAuthFlows
    {
        AuthorizationCode = new OpenApiOAuthFlow
        {
            AuthorizationUrl = new Uri("https://example.com/oauth/authorize"),
            TokenUrl = new Uri("https://example.com/oauth/token"),
            Scopes = new Dictionary<string, string>
            {
                { "read", "Grants read access" },
                { "write", "Grants write access" }
            }
        }
    }
});

c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
    {
        new OpenApiSecurityScheme
        {
            Reference = new OpenApiReference
            {
                Id = "OAuth2Auth",
                Type = ReferenceType.SecurityScheme
            }
        },
        new[] { "read", "write" }
    }
});

---

3. API Key Authentication en Swagger + .NET

Definición en OpenAPI

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key

Ejemplo en .NET (Middleware personalizado)

app.Use(async (context, next) =>
{
    if (!context.Request.Headers.TryGetValue("X-API-Key", out var extractedKey))
    {
        context.Response.StatusCode = 401;
        await context.Response.WriteAsync("API Key missing");
        return;
    }

    if (extractedKey != "12345")
    {
        context.Response.StatusCode = 401;
        await context.Response.WriteAsync("Invalid API Key");
        return;
    }

    await next();
});

Configuración Swagger

c.AddSecurityDefinition("ApiKeyAuth", new OpenApiSecurityScheme
{
    Type = SecuritySchemeType.ApiKey,
    In = ParameterLocation.Header,
    Name = "X-API-Key"
});

---

4. Basic Authentication en Swagger + .NET

Definición en OpenAPI

securitySchemes:
  BasicAuth:
    type: http
    scheme: basic

Implementación en .NET

builder.Services.AddAuthentication("BasicAuth")
    .AddScheme<AuthenticationSchemeOptions, BasicAuthHandler>("BasicAuth", null);

Handler personalizado:

public class BasicAuthHandler : AuthenticationHandler<AuthenticationSchemeOptions>
{
    public BasicAuthHandler(IOptionsMonitor<AuthenticationSchemeOptions> options,
                            ILoggerFactory logger,
                            UrlEncoder encoder,
                            ISystemClock clock)
        : base(options, logger, encoder, clock) {}

    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        if (!Request.Headers.ContainsKey("Authorization"))
            return Task.FromResult(AuthenticateResult.Fail("Missing Authorization Header"));

        var authHeader = AuthenticationHeaderValue.Parse(Request.Headers["Authorization"]);
        var credentials = Encoding.UTF8.GetString(Convert.FromBase64String(authHeader.Parameter)).Split(':');

        if (credentials[0] != "admin" || credentials[1] != "password")
            return Task.FromResult(AuthenticateResult.Fail("Invalid Credentials"));

        var claims = new[] { new Claim(ClaimTypes.Name, credentials[0]) };
        var identity = new ClaimsIdentity(claims, Scheme.Name);
        var principal = new ClaimsPrincipal(identity);

        return Task.FromResult(AuthenticateResult.Success(new AuthenticationTicket(principal, Scheme.Name)));
    }
}

---

5. OpenID Connect (OIDC) en Swagger + .NET

Definición en OpenAPI

securitySchemes:
  OpenIDAuth:
    type: openIdConnect
    openIdConnectUrl: https://example.com/.well-known/openid-configuration

Implementación en .NET

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = "Cookies";
    options.DefaultChallengeScheme = "oidc";
})
.AddCookie("Cookies")
.AddOpenIdConnect("oidc", options =>
{
    options.Authority = "https://example.com";
    options.ClientId = "client_id";
    options.ClientSecret = "client_secret";
    options.ResponseType = "code";
});

---

Conclusión técnica

Definir esquemas de seguridad adecuados en Swagger/OpenAPI es fundamental para garantizar acceso controlado, seguro y estandarizado.
Los desarrolladores deben elegir el esquema adecuado según factores como:

• Nivel de seguridad requerido
• Tipo de cliente (web, móvil, microservicios)
• Necesidad de identidad del usuario
• Complejidad de implementación

Bearer Tokens y OAuth2 son hoy los estándares más robustos y utilizados en arquitecturas modernas, mientras que mecanismos como API Key y Basic Auth siguen siendo útiles en escenarios limitados o de baja criticidad.