diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/404.html b/404.html new file mode 100644 index 0000000..4754095 --- /dev/null +++ b/404.html @@ -0,0 +1,675 @@ + + + +
+ + + + + + + + + + + + + + + + +If the provided placeholders are not enough, and you need more logic behind your Templating, you can use our preprocessing
feature.
+This feature allows you to run a custom function on the E-Mail Template before it is sent out. This function will be able to add / modify / remove placeholders from the template. You can also use this function to add custom logic to the template.
+Examples of what you can do with this feature:
Usage Examples of Preprocessing E-Mail Templates
+In this example, we will add a timestamp
placeholder to the E-Mail Template. This placeholder will contain the current date and time when the E-Mail is sent out.
Preprocessing Function
+config/email
folder. The function should be named preprocess
and should accept a single parameter kwargs
which is a dictionary containing all the placeholders available in the E-Mail Template.kwargs
object..py
extension. (e.g. WelcomeMail.py
for the WelcomeMail.html
template)In this example, we will add a timestamp
placeholder to the ConfirmEmail.html
template.
+
Since the Goal of EZAuth is to be as extensive as possible, it is possible to create your own extensions to add functionality to EZAuth.
+To allow Extensions, you need to create a new folder called extensions/
in the directory specified in the docker-compose file (default ./
root of Repository), if it doesn't already exist. This folder is not tracked by git, so you can safely add your own extensions without the risk of losing them when updating the repository.
EZAuth Developer Mode
+To also enjoy a greater developement experience, you can start EZAuth in Development Mode. This will allow you to see changes in your extensions without restarting the server. +It will also show you more detailed error messages, which can be helpful when developing extensions.
+Extensions can break EVERYTHING (including all your userdata)
+Since Extensions are a really advanced feature, they are not recommended to be developed by beginners. However, if you are an experienced developer, you can create your own extensions.
+New Folder for the Extension
+Inside the extensions/
directory, create a new folder for your extension. The name of the folder should be the name of your extension. We force a folder, to make it easier for you to structure your extension and keep an overview of all the installed extensions. We use the name my_extension
for this example.
Make the Extension Loadable
+To make EZAuth recognize your extension as a valid one, add a __init__.py
file to your newly created extension folder. This file must be there and export a router
which is a FastAPI Router.
Depending on the structure of your Extension, you can either write the whole extension into the __init__.py
file or import only the router from another file.
Imports in Extension Files
+Be careful when doing imports in extensions, as by just importing other files using .myextension
won't work (importlib can't find the module). You have to use the full import path to the file starting with extensions.my_extension.
-> E.g. extensions.my_extension.myextension
Provide some information about the Extension
+To make it easier for users to understand what your extension does, you can provide a README.md
file in your extension folder. This file can contain information about the extension, how to use it, and what it does.
This is especially useful if you want to share your extension with others.
+If you want to use an extension that someone else has created, you can download it from a repository and place it in the extensions/
directory. The extension should be structured as described above.
Extension Repository
+If you want to share your extension with others, you can create a repository on GitHub or any other platform and share the link with others. This way, others can easily download your extension and use it in their EZAuth instance. If you want to share your extension with the community, you can also create a Pull Request to add your extension to the official EZAuth Extension Repository.
+If you want to further customize the service you can take a look at the docker-compose.yml
file in the root directory of the repository. This file contains all the configuration options for the service. You can change the port on which the service is running, the volume mounts, and the environment variables.
The Prefix for all Parameters here is services.api
.
+The Following Environment Variables can be set in the docker-compose.yml
file to configure the API:
Parameter | +Description | +
---|---|
ports |
+Datatype: String Default: "3250:80" Only change the left (host) side of the ports. The API will always run on Port 80 internally, and can be forwarded to any port on the host system. In this example 3250 . |
+
volumes |
+Datatype: String Default: "./config:/app/config" The volume mount for the configuration file. Only change the left (host) side of the configuration folder directory. In this example ./config . You can also change the ./uploads directory, for user file uploads like profile pictures etc. |
+
The Prefix for all Parameters here is services.db.environment
.
+When changing the database configuration, make sure to also change the api
section in the docker-compose.yml
file to reflect the new database connection.
+The following environment variables can be set in the docker-compose.yml
file to configure the database connection:
Parameter | +Description | +
---|---|
MONGO_INITDB_ROOT_USERNAME |
+Datatype: String Default: "admin" The Root Username for the Database. |
+
MONGO_INITDB_ROOT_PASSWORD |
+Datatype: String Default: "admin" The Root Password for the Database. |
+
MONGO_INITDB_DATABASE |
+Datatype: String Default: "ezauth" The Database Name. |
+
You can also change the location of the database data by changing the volumes
section of the db
section in the docker-compose.yml
file.
The Prefix for all Parameters here is services.redis
.
+When changing the Redis configuration, make sure to also change the api
section in the docker-compose.yml
file to reflect the new Redis connection.
Parameter | +Description | +
---|---|
command |
+Datatype: String Default: redis-server --requirepass admin You can change the password for the redis server here. It has to be set in the environment of the API section too. |
+
EZAuth offers a way to authenticate users via OAuth. This is a more secure way to authenticate users and also simplifies the registration process for users.
+The following Rules are applied when using OAuth:
A new user is created when the user logs in for the first time with oauth (Username and E-Mail get derived from the OAuth Provider)
+The user can log in with the same OAuth Provider again and again
+The user can reset his password after logging in with OAuth and is the able to log in without OAuth
+If there is a user with the same E-Mail as the OAuth Provider, the OAuth will be linked to the existing user
+OAuth is a full replacement for the normal login process
+Create credentials
and select OAuth client ID
.Web application
as the application type.Authorized redirect URIs
(Where {BASE_URL}
is the Hostname of the server eg. http://test.com
):{BASE_URL}/oauth/google/callback
Add the following scopes +
+Click on Create
and download the credentials as JSON and place them in the config
folder.
+Make sure the name of the file is google_client_secret.env.json
.
New OAuth App
.Authorization callback URL
(Where {BASE_URL}
is the Hostname of the server eg. http://localhost:3250
):{BASE_URL}/oauth/github/callback
Client ID
and Client Secret
and create the following file in the config
folder.If you want to deploy EZAuth you may want to run it via HTTPS
instead of HTTP
. This can be easily achieved with EZAuth, by putting certificates in the config/ssl
directory. The certificates have to be named cert.pem
and key.pem
. The cert.pem
file should contain the certificate and the intermediate certificate, while the key.pem
file should contain the private key.
EZAuth will automatically detect the certificates and run on HTTPS
instead of HTTP
. If you want to run EZAuth on HTTP
again, just remove the certificates from the config/ssl
directory.
If you want to test EZAuth with self-signed certificates, you can use MKCert.
+SSL Certificates
+Make sure that the certificates are valid and not self-signed. Browsers will not accept self-signed certificates and will show a warning to the user. Use Let's Encrypt or a similar service to get valid certificates.
+To generate a self-signed certificate with MKCert, install MKCert and follow the instructions below.
+Run the following commands to generate a Certificate with MKCert
+ +After running the command, you will see two files in the config/ssl
directory: yourdomain.com.pem
and yourdomain.com-key.pem
. Rename the files to cert.pem
and key.pem
respectively. Then restart the EZAuth service to apply the changes.