# Example Web Application using Modern Authentication and Tridion Docs OpenAPI

The preferred way of creating an extension is to use the Organize Space Extensibility mechanism, you don't have to do anything for Modern Authentication as it is handled by Organize Space.
If you want to create your own Web Application that consumes Tridion Docs content, you have to cater for Modern Authentication and this Web Application is an example of how this can be achieved.

The left column in the table below shows the Modern Authentication options used in Organize Space and Collective Spaces. The right column highlights what you get when using the extension points in Organize Space, (The extensions inherent the Modern Authentication options from Organize Space.)  The example Web Application we will walk through uses all these options except for the token refresh and session cookies are stored in memory which is not ideal for using it behind a load balancer.

|                                                | Tridion Docs 15 Standard Product (/ISHCS)                                                                            | Tridion Docs 15 Secure Extensions (/ISHEXT)                                                                          | 
|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| Modern Authentication                          | Yes                                                                                                                  | Yes                                                                                                                  |
| Sign in                                        | Yes                                                                                                                  | Yes                                                                                                                  |
| Refresh access token before it expires         | Yes                                                                                                                  | Yes                                                                                                                  |
| Sign Out                                       | Yes                                                                                                                  | Yes                                                                                                                  |
| Token Management                               | Session cookies using Backend-for-Frontend paradigm supported. Supporting Load-Balancing over shared session storage | Session cookies using Backend-for-Frontend paradigm supported. Supporting Load-Balancing over shared session storage |
| "No tokens in the browser" policy              | No, Access Token remains on the server                                                                               | No, Access Token remains on the server                                                                               |
| Sliding Expiration                             | Yes                                                                                                                  | Yes                                                                                                                  |
| React to changes in the browser security model | Yes                                                                                                                  | Yes                                                                                                                  |

This example Web Application uses Modern Authentication, generates a TypeScript client from the Tridion Docs OpenAPI and communicates to it. 
It is based on React and ASP.NET Core but can also be done in other technologies.
- It uses React to create the user interface, which is what you see and interact with on the web page.
- It uses NSwag to generate a TypeScript client from the Tridion Docs OpenAPI specification (https://example.ish.com/ISHWS/api/api-docs/v3/openapi.json).
- It uses YARP as a reverse proxy for proxying request to Tridion Docs OpenAPI.
- It uses ASP.NET Core to handle the authentication, which is the process of verifying who you are and what you can access. It acts as a backend for the frontend.
- It uses ASP.NET Core to communicate with Tridion Docs Web Services (OpenAPI) that stores and manages documents.
- The web application needs to know who you are before it can show you the documents. 
- To do this, it asks another software program, called an identity provider, to verify your identity. 
- The identity provider is a trusted third-party that can confirm your username and password. 
- The web application does not know or store your username and password.

## Overview
![Overview](./Images/Overview.png)

The process of authentication works like this:
- When you open the Web Application and press the sign in button, it sends a request to the ASP.NET Core part of the program. It will initiate the login process by returning a redirect URL to Access Management (ISHAM) which act as a federation gateway to the identity provider.
- If you enter the correct username and password, the identity provider sends you back to the Access Management (ISHAM) with a special code, your identity token and optional claims.
- Based on your identity prover and/or claims Access Manager grant you access to this Web Application.- The ASP.Net Core part of the program receives the access token and stores it in a secure place. It also sends you a small piece of data, called a cookie, that has a unique number, called a session id, that links to the access token.
- The cookie is stored in your web browser and sent to the ASP.NET Core part of the program every time you make a request to the web application.
- The ASP.NET Core part of the program checks the cookie and the session id, and finds the access token that matches it. It then adds the access token to a security message, called a claim, that it sends to the Tridion Docs Web Services part of the program.
- The Tridion Docs Web Services part of the program checks the claim and the access token, and decides what documents you can see and edit.
- The advantage of using a session store and a cookie with a session id is that the access token is not exposed to the web browser or the user, which makes it more secure and less likely to be stolen or misused.
  
The advantage of loading the Web Application from the same server as where the requests are sent to is that there is no need to configure CORS, which is a set of rules that allow different web applications to talk to each other. 
This makes it easier to set up and maintain the web application. The Tridion Docs Web Services do not need to be accessible from the internet, as long as the Web Application can connect to it. This makes it more secure and less vulnerable to attacks.

## Remarks on the Demo Web Application:
* The session store is memory based and not suited for running multiple web applications behind a load balancer, session should be stored centralized.
* There is no support for refreshing the access token. 
* The example shows the basics of building a secure web application. There are packages available for better token management, for example [Duende BFF Security Framework](https://docs.duendesoftware.com/identityserver/v6/bff/overview/)

## Building the demo web application
1. Install the [.NET 8 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)
2. Have [Visual Studio Code](https://code.visualstudio.com/) or an other IDE.
3. Make sure you have a running Tridion Docs environment
4. Make sure you have registered an application in Access Management
   1. Login into Access Management
   2. Select 'Applications'
   3. Click 'Register application'
   4. This demo application is using react-and-openapi as the client id and is configurable
   5. Use Authorization Code flow with PKCE for the most secure authentication flow type
   6. For allowed redirects URLs, add https://localhost:44482/signin-oidc ![](./Images/Register%20Application.png)
   7. Make sure the users have access to this demo web application, preferably configured in the identity provider, it also requires 'Tridion Docs Content Manager API' Services with role 'user' ![](./Images/Application%20Access.png)
5. The appsettings.json contains authentication and reverse proxy configuration settings, make sure the authority and address are pointing to your Tridion Docs instance
``` json
"Tridion": {
 "Authentication": {
   "Authority": "https://demo.tridion-docs.com/ISHAM",
   "ClientId": "react-and-openapi",
   "CookieExpireTimeSpan": "00:55:00"
 }
},
"ReverseProxy": {
 "Routes": {
   "openapi-route": {
     "ClusterId": "openapi-cluster",
     "Match": {
       "Path": "openapi/{**catch-all}"
     },
     "Transforms": [
       {
         "PathPattern": "api/{**catch-all}"
       },
       {
         "X-Forwarded": "Set"
       },
       {
         "RequestHeader": "X-Forwarded-Prefix",
         "Set": "/openapi"
       }          
     ]
   }
 },
 "Clusters": {
   "openapi-cluster": {
     "Destinations": {
       "destination1": {
         "Address": "https://demo.tridion-docs.com/ISHWS"
       }
     }
   }
 }
}  
```

## Running the Demo Web Application
Run the application from your IDE or command line (in the folder where the project is located (ReactAndOpenApi.csproj) run command 'dotnet run')
![](./Images/ReactAndOpenApi.gif)

## Troubleshooting
When you are having issues with SSL certificate for localhost follow the [link](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-dev-certs) for generating a HTTPS certificate.
