Configuration Steps to enable auto-generation client REST interfaces

Tue, 17 Oct 2023 08:30:50 GMT

Problem Statement:

In the process of developing a multi-layered RESTful system, which includes both backend and frontend components, there is a need to identify new endpoints and update existing ones. It is crucial that these updates are reflected in the RESTful client interface or API client proxy. However, the conventional approach involves manual implementation, resulting in numerous issues such as time wastage, inconsistencies between the API definitions and client representation, and a lack of documentation necessary for proper API utilization.

Proposition:

We propose the implementation of a user-friendly auto-generation system that can simultaneously create a well-documented API client proxy. This solution will involve integrating third-party libraries, executing shell commands, and configuring Visual Studio settings.

Prerequisites:

Strongly defined API parameters, including data returned and input model schemas.
Strict adherence to RESTful conventions, utilizing HTTP methods to define actions and ensuring that endpoint URIs describe the affected elements.
Thorough documentation of the defined API.

Methodology:

Enable XML documentation and incorporate it into the OpenAPI configuration.
Generate the OpenAPI as a physical JSON file during the project build process.
Use AutoRest to generate the API client in a specific output language (in this case, TypeScript) based on the generated OpenAPI JSON file.
Copy the commands derived from the previous steps into the post-build event.

Explanation:

In the API project properties, (1) enable the documentation file, and (2) specify the output XML filename and path.

Source: Adding Swagger to ASP.NET Core Web API Using XML Documentation

Include the on-build generated file in the Swagger configuration to make all documentation references appear in the Swagger UI.

Run the following commands to enable on-build Swagger JSON config file generation and set the path to the Web API project:

dotnet new tool-manifest
dotnet tool install --version 5.3.1 Swashbuckle.AspNetCore.Cli Source: How to Generate a Swagger JSON File on Build in .NET Core

To test JSON config file generation, run the following command:

dotnet swagger tofile --output swagger.json "bin\debug\net7.0\APIs.dll" v1

Install AutoRest using npm:

npm install -g autorest
autorest --latest

Generate the AutoRest client using the following command:

autorest --input-file=swagger.json --typescript --namespace=EarlyRegistration.APIs.Controllers --add-credentials
If you encounter certification-related errors, try the following steps:
- Find and delete the file autorest.ps1 in "C:\Users%USERPROFILE%\AppData\Roaming\npm"
- Execute the command: autorest --reset

If the above steps work as expected, you can copy the commands to the post-build section in the Web API build properties. These commands include:

dotnet swagger tofile --output swagger.json "bin\debug\net7.0\APIs.dll" v1
autorest --input-file=swagger.json --output-folder=../../autogen-api-tsclient --typescript --namespace=EarlyRegistration.APIs.Controllers --add-credentials

Build your project, and in the file explorer, you should find a folder named "autogen-api-tsclient" located in the root folder of the project.

OpenID Connect and To Practice over ASP.NET Core

Tue, 15 Aug 2023 18:34:28 GMT

Please note that this is a draft for personal use, it misses some extended explanation and details, but I think it will be useful as an initial startup

1. Useful Resources with comments

Recent trends for securing web APIs and Web Apps are dependent on the OAuth 2.0 with OpenID Connect protocols. Below are useful resources to understand the theory and the architecture. Additionally, some of them could help to implement Authentication and Authorization systems to secure ASP Core apps. The popular way is the utilization of Asp Core Identity with IdentityServer4.

1.1. The official Microsoft documentation (Continuous)

Make it your main handbook,

· For Microsoft Identity check the link https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-implicit-grant-flow

· To review the security that is specific to ASP .NET Core check https://docs.microsoft.com/en-us/aspnet/core/security/?view=aspnetcore-5.0

//TODO: put most important points related to ASP .NET Core API, such as Shared Cookies, Authorization, and Authentication...

1.2. The Official IdentityServer4 Documentation (Continues)

http://docs.identityserver.io/en/latest/index.html

1.3. Introduction to understand the OAuth 2.0 and OpenID Connect

It is important to have a clear definition of the OAuth and OpenID Connect (OIDC). Like many developers, they used them in the wrong way. To avoid such wrong definitions, check the links below:

- Remove fear by https://www.youtube.com/watch?v=t18YB3xDfXI to gain a necessary terminology and nutshell explanation. You will also find some useful resources in the video description. You can also read this small article which I find useful https://nat.sakimura.org/2011/05/15/dummys-guide-for-the-difference-between-oauth-authentication-and-openid/

- For a deep review, I highly recommend starting with a video presented by Dr. Philippe De Ryck that mainly gave a clear definition for them and explained the different recommended flows for authentication and authorization. Notice that you should focus as much as you can to understand the different proposed flows, as they are essential to rich the highest levels of the security process for your apps

- Introduction to OAuth 2.0 and OpenID Connect • Philippe De Ryck • GOTO 2018

You can download the slides from the link Slides to extract the flows diagrams.

Also, you can watch another video for the same presenter that talks about the different API Security pitfalls https://www.youtube.com/watch?v=Ss1tZjooo9I.