diff --git a/docs/auth/introduction.md b/docs/pages/auth-concept/authentication.md similarity index 82% rename from docs/auth/introduction.md rename to docs/pages/auth-concept/authentication.md index 7431e4bcc..2cd7a0101 100644 --- a/docs/auth/introduction.md +++ b/docs/pages/auth-concept/authentication.md @@ -1,4 +1,9 @@ -# Authentication +--- +title: 'Authentication functions' +weight: 3 +--- + +# Getting started with Authentication functions Authentication in Glee can be done using authentication functions. Authentication functions are files that export either one or both of the `clientAuth` and `serverAuth` Node.js functions: @@ -19,28 +24,28 @@ The name of the authentication file should be the name of the targeted server th ## Supported Authentication Values in asyncapi.yaml file -AsyncAPI currently supports a variety of authentication formats as specified in the [documentation](https://www.asyncapi.com/docs/reference/specification/v2.6.0#securitySchemeObject), however Glee supports the following authentication schemas. +AsyncAPI currently supports a variety of authentication formats as specified in the [documentation](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.15#securitySchemeObject), however Glee supports the following authentication schemas. - userPassword -- Bearer token -- HttpPApiKey -- ApiKey +- http ("bearer") +- httpApiKey +- Oauth2 A sample `asyncapi.yaml` for a server with security requirements and a `userPassword` security schemes is shown below: ```yaml ##server asyncAPI schema -asyncapi: 2.6.0 +asyncapi: 3.0.0 info: title: AsyncAPI IMDB server version: 1.0.0 description: This app is a dummy server that would stream the trending/upcoming anime. servers: trendingAnimeServer: - url: 'http://localhost:8081' + host: 'localhost:8081' protocol: http security: - - userPass: [] + - $ref: '#/components/securitySchemes/userPass' ... @@ -57,12 +62,12 @@ A sample `asyncapi.yaml` for a client that implements some of the requirements o ##client asyncAPI schema servers: trendingAnime: - url: http://localhost:8081 + host: localhost:8081 protocol: http security: - - userPass: [] + - $ref: '#/components/securitySchemes/userPass' testwebhook: - url: ws://localhost:9000 + host: localhost:9000 protocol: ws x-remoteServers: - trendingAnime @@ -76,12 +81,12 @@ components: ``` -**The Client asyncapi.yaml file does not need to implement all the security requirements in the server, it only needs to implement the ones that it uses.** +**The Client asyncapi.yaml file does not need to implement all the security requirements in the server, it only needs to implement the ones that it uses like *userPassword* here.** -Glee can act as both a server and a client at the same time. Hence the need for `serverAuth` and `clientAuth`. Glee acts as a client when the `x-remoteServers` property is present in the `asyncapi.yaml` file. +Glee can act as both a server and a client. Hence the need for `serverAuth` and `clientAuth`. Glee acts as a client when the server name is included in the `x-remoteServers` property in the `asyncapi.yaml` file. -When Glee acts as a client, it can connect to a Glee server, and when Glee acts as a server it accepts connection from other Glee clients. Hence a Glee application can both accept connections from clients while also sending requests to other Glee applications (servers) ath the same time. +When Glee acts as a client, it can connect to a Glee server, and when Glee acts as a server it accepts connections from other Glee clients. Hence a Glee application can both accept connections from clients while also sending requests to other Glee applications (servers) at the same time. When a security requirement is specified in the `asyncapi.yaml` file and Glee acts as a server, the `serverAuth` function should be implemented, if Glee acts as a client then the `clientAuth` function should be implemented. If Glee is being used as both client and server, then it should have both the `clientAuth` and `serverAuth` functions. @@ -104,11 +109,18 @@ The `done` parameter in the `serverAuth` function allows the broker/server to kn /* websocket.js */ export async function serverAuth({ authProps, done }) { - // done(true) - //done(false, 401, "Unauthorized") - // done(false) + if (isValidUser(authProps)) { + done(true); + } else { + done(false, 401, "Unauthorized"); + } } ``` +**Parameters for done():** + +- Authentication Result (Boolean): true for success, false for failure. +- HTTP Status Code (Integer): Code for authentication failure (e.g., 401 for Unauthorized). +- Status Message (String): Description of the authentication result (e.g., "Unauthorized"). When `true` is passed to the done parameter, the server/broker knows to go ahead and allow the client to connect, which means authentication has succeeded. However if the `done` parameter is called with `false` then the server knows to throw an error message and reject the client, which means authenticatio has failed. diff --git a/docs/auth/bearerToken.md b/docs/pages/auth-concept/bearerToken.md similarity index 77% rename from docs/auth/bearerToken.md rename to docs/pages/auth-concept/bearerToken.md index 094614875..9f1d2244b 100644 --- a/docs/auth/bearerToken.md +++ b/docs/pages/auth-concept/bearerToken.md @@ -1,3 +1,8 @@ +--- +title: 'Http (Bearer Token)' +weight: 5 +--- + ## Getting started with Bearer Token authentication Bearer Token authentication is one of the most popular forms of authentication and is widely used because of its percieved security. This guide will walk through how to implement bearer token authentication in Glee. @@ -6,17 +11,17 @@ A sample `asyncapi.yaml` for a server with security requirements and user passwo ```yaml ##server asyncAPI schema -asyncapi: 2.6.0 +asyncapi: 3.0.0 info: title: AsyncAPI IMDB server version: 1.0.0 description: This app is a dummy server that would stream the trending/upcoming anime. servers: trendingAnimeServer: - url: 'http://localhost:8081' + host: 'localhost:8081' protocol: http security: - - token: [] + - $ref: '#/components/securitySchemes/token' ... @@ -35,12 +40,12 @@ A sample `asyncapi.yaml` for a client that implements some of the requirements o ##client asyncAPI schema servers: trendingAnime: - url: http://localhost:8081 + host: localhost:8081 protocol: http security: - - token: [] + - $ref: '#/components/securitySchemes/token' testwebhook: - url: ws://localhost:9000 + host: localhost:9000 protocol: ws x-remoteServers: - trendingAnime @@ -56,7 +61,7 @@ components: ``` -**The Client asyncapi.yaml file does't need to implement all the security requirements in the server, it only needs to implement the ones that it uses.** +**The Client asyncapi.yaml file does't need to implement all the security requirements in the server, it only needs to implement the ones that it uses like &*http (bearer token)* here.** ### Client Side @@ -66,7 +71,7 @@ Following the client `asyncapi.yaml` file above, create a file named `trendingAn touch auth/trendingAnime.ts ``` -When using the `token` security scheme, it is important that you pass the parameters as follows: +When using the `bearer` security scheme, it is important that you pass the parameters as follows: ```js export async clientAuth({ parsedAsyncAPI, serverName }) { @@ -76,7 +81,7 @@ export async clientAuth({ parsedAsyncAPI, serverName }) { } ``` -`token` should be the name of the security requirement as specified in your `asyncapi.yaml` file, and it's value should be a string. +Glee will utilize the `token` for server authentication, employing it in the header with the format: Authorization: Bearer {token}. ### Server side @@ -92,8 +97,8 @@ On the server side, you can retrieve the values as follows export async serverAuth({ authProps, done }) { authProps.getToken() - - done(true) + // your authentication logic here... + done(true|false) } ``` diff --git a/docs/auth/httpApiKey.md b/docs/pages/auth-concept/httpApiKey.md similarity index 89% rename from docs/auth/httpApiKey.md rename to docs/pages/auth-concept/httpApiKey.md index a2d7d3951..e95131edb 100644 --- a/docs/auth/httpApiKey.md +++ b/docs/pages/auth-concept/httpApiKey.md @@ -1,3 +1,8 @@ +--- +title: 'httpAPIKey' +weight: 5 +--- + ## Getting started with httpAPIKey authentication This guide will walk through how to implement authentication using the `httpAPiKey` security scheme in Glee. @@ -6,17 +11,17 @@ A sample `asyncapi.yaml` for a server with security requirements and user `HttpA ```yaml ##server asyncAPI schema -asyncapi: 2.6.0 +asyncapi: 3.0.0 info: title: AsyncAPI IMDB server version: 1.0.0 description: This app is a dummy server that would stream the trending/upcoming anime. servers: trendingAnimeServer: - url: 'http://localhost:8081' + host: 'localhost:8081' protocol: http security: - - apiKey: [] + - $ref: '#/components/securitySchemes/apiKey' ... @@ -35,12 +40,12 @@ A sample `asyncapi.yaml` for a client that implements some of the requirements o ##client asyncAPI schema servers: trendingAnime: - url: http://localhost:8081 + host: localhost:8081 protocol: http security: - - apiKey: [] + - $ref: '#/components/securitySchemes/apiKey' testwebhook: - url: ws://localhost:9000 + host: localhost:9000 protocol: ws x-remoteServers: - trendingAnime @@ -59,7 +64,7 @@ components: The `httpApiKey` could be in either the header or query parameter. -**The Client asyncapi.yaml file does not need to implement all the security requirements in the server, it only needs to implement the ones that it uses.** +**The Client asyncapi.yaml file does not need to implement all the security requirements in the server, it only needs to implement the ones that it uses like *httpApiKey* here.** ### Client Side @@ -104,5 +109,3 @@ export async serverAuth({ authProps, done }) { `getHttpAPIKeys(name)` takes a name parameter to specify the name of the httpApiKey that is desired. Then it returns an object containing the httpApiKey value that was sent from the client. - - diff --git a/docs/pages/auth-concept/index.md b/docs/pages/auth-concept/index.md new file mode 100644 index 000000000..0df20b6f1 --- /dev/null +++ b/docs/pages/auth-concept/index.md @@ -0,0 +1,21 @@ +--- +title: 'Introduction' +weight: 30 +--- + +Glee comes with Authentication features which help you erifying the identity of users or entities attempting to access a system or application. It ensures that only authorised individuals or systems are granted access, protecting against unauthorised intrusions and data breaches. Glee simplifies this vital process by offering multiple authentication methods, each tailored to different use cases: + +# Authentication Using Authentication Functions: +Glee allows you to implement custom authentication logic by utilising authentication functions. This flexible approach enables developers to craft tailored authentication mechanisms, ensuring that access to resources is controlled precisely as required. + + +# HTTP Bearer Token Authentication: +In today's API-driven world, bearer token authentication is a widely adopted method. Glee supports this approach, allowing clients to present a token as proof of their identity, thus ensuring secure and efficient access to resources. + +# HttpApiKey Authentication: +Glee's authentication suite includes support for API key authentication, which is vital for protecting web APIs. By using API keys, you can regulate access to your services, making it an essential component of your application's security strategy. + +# Username and Password Authentication: +Traditional yet still crucial, username and password authentication remains a reliable option within Glee's toolkit. This method allows users to access systems or applications by providing their unique credentials, ensuring a familiar and straightforward login experience. + +Glee's authentication features not only provide layers of security but also offer the flexibility needed to meet your unique requirements. Whether you're developing a web application, a mobile app, or any other application, Glee's authentication methods empower you to tailor your security measures to suit the demands of your project. With Glee, you can build and maintain a secure digital environment, ensuring that only authorised users and systems gain access, protecting your valuable data and resources. \ No newline at end of file diff --git a/docs/auth/userPassword.md b/docs/pages/auth-concept/userPassword.md similarity index 88% rename from docs/auth/userPassword.md rename to docs/pages/auth-concept/userPassword.md index f74b62a5d..fc761310e 100644 --- a/docs/auth/userPassword.md +++ b/docs/pages/auth-concept/userPassword.md @@ -1,3 +1,8 @@ +--- +title: 'userPassword' +weight: 5 +--- + ## Getting started with username and password authentication User and password authentication is one of the most basic forms of authentication. This guide will walk through how to implement username and password authentication in Glee. @@ -6,17 +11,17 @@ A sample `asyncapi.yaml` for a server with security requirements and user passwo ```yaml ##server asyncAPI schema -asyncapi: 2.6.0 +asyncapi: 3.0.0 info: title: AsyncAPI IMDB server version: 1.0.0 description: This app is a dummy server that would stream the trending/upcoming anime. servers: trendingAnimeServer: - url: 'http://localhost:8081' + host: 'localhost:8081' protocol: http security: - - userPass: [] + - $ref: '#/components/securitySchemes/userPass ... @@ -33,12 +38,12 @@ A sample `asyncapi.yaml` for a client that implements some of the requirements o ##client asyncAPI schema servers: trendingAnime: - url: http://localhost:8081 + host: localhost:8081 protocol: http security: - - userPass: [] + - $ref: '#/components/securitySchemes/userPass testwebhook: - url: ws://localhost:9000 + host: localhost:9000 protocol: ws x-remoteServers: - trendingAnime @@ -52,7 +57,7 @@ components: ``` -**The Client asyncapi.yaml file does not need to implement all the security requirements in the server, it only needs to implement the ones that it uses.** +**The Client asyncapi.yaml file does not need to implement all the security requirements in the server, it only needs to implement the ones that it uses like &*userPassword* here.** ### Client Side @@ -99,6 +104,3 @@ export async serverAuth({ authProps, done }) { ``` `getUserPass()` return an object containing the username and password that was sent from the client. - - -