Add support for Inclusion of OpenApiOAuthFlows as a Configurable Option in the Intent.AspNetCore.Swashbuckle Module

[stephanjohnson]

The Swagger module in Intent Architect currently provides a robust default OpenApiSecurityScheme, which uses JWT for authorization. While this setup serves a wide range of applications, we can further extend its utility by incorporating OAuth 2.0 flows (OpenApiOAuthFlows) as a configurable feature in the module. This enhancement could offer a broader array of use-cases and afford developers greater flexibility in selecting their authorization mechanisms.

A key advantage of integrating OAuth 2.0 flows includes:

Granular Access Control and Enhanced Testing Capabilities: OAuth 2.0 provides granular control over access rights via scopes and permissions, aligning with industry best practices for securing APIs. More importantly, if configured correctly, Swagger presents the option for developers to choose the scopes they want authenticated during their testing. This means developers can specifically test security and access code within their controllers and actions. This level of granularity can significantly improve the debugging and validation process, reducing potential issues in production environments.

The following code snippet exemplifies the proposed integration of OAuth 2.0 flows:

// ConfigureSwagger

options.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
{
    Type = SecuritySchemeType.OAuth2,
    Flows = new OpenApiOAuthFlows
    {
        Implicit = new OpenApiOAuthFlow
        {
            Scopes = scopes.ToDictionary(x => $"api://{x.Key}", x => x.Value),
            AuthorizationUrl = new Uri(swagger.Auth?.AuthorizationUrl),
            TokenUrl = new Uri(swagger.Auth?.TokenUrl)
        }
    }
});

options.AddSecurityRequirement(new OpenApiSecurityRequirement
{
    {
        new OpenApiSecurityScheme
        {
            Reference = new OpenApiReference
            {
                Type = ReferenceType.SecurityScheme,
                Id = "oauth2"
            }
        },
        scopes.Select(m => $"api://{m.Key}").ToArray()
    }
});

// UseSwashbuckle

options.OAuthClientId(swagger.Auth?.ClientId);

The proposed OAuth 2.0 extension necessitates some supplemental settings in the application's configuration. These primarily pertain to your OAuth 2.0 server's details and the scopes your API supports.

Within the Swagger section, the Auth subsection encapsulates the ClientId, AuthorizationUrl, and TokenUrl. The ClientId corresponds to your OAuth 2.0 server registered application. The AuthorizationUrl and TokenUrl are your OAuth 2.0 server endpoints that facilitate the authorization code flow.

"Swagger": {
  "Auth": {
    "ClientId": "xxx",
    "AuthorizationUrl": "https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize",
    "TokenUrl": "https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize"
  }
}

Noteworthy is that the above configuration is necessary for Azure Active Directory integration. The ClientId is also mandatory for Azure AD integration through the Intent.Security.MSAL module.

"AzureAd": {
  "Instance": "https://login.microsoftonline.com/",
  "Domain": "example.com",
  "TenantId": "aaa",
  "ClientId": "xxx",
  "Audience": "api://example.com",
  "Scopes": "access_as_user access_as_application",
  "CallbackPath": "/signin-oidc",
  "SignedOutCallbackPath": "/signout-callback-oidc",
  "ClientSecret": ""
},

The Scopes section defines the scopes your API supports - these are the permissions that your API can solicit from the OAuth 2.0 server. Each scope is represented as a key-value pair where the key is the scope identifier, and the value is its corresponding user-friendly name.

"Scopes": {
  "example.com/access_as_user": "Access as user"
}

These supplemental settings are crucial for appropriately configuring Swagger UI with OAuth 2.0 support, facilitating the precise generation of the required authorization parameters.

[joelsteventurner]

Hi @stephanjohnson

Thanks for all the detailed info in this suggestion. I have logged this on our backlog.

[joelsteventurner]

Hi @stephanjohnson

Happy to inform you that this feature is now available in Intent.AspNetCore.Swashbuckle.Security v 4.0.4