[HOW-TO] Send automatic email invite during invitation creation

[stiw47]

First of all I would like to say that I am not dev at all. I used google, used little bit help of GPT, made below scripts, and they are working for my use case. Of course, I am open for suggestions and improvements, if anybody is interested to comment.

TBH, I was surprised when I saw that we have possibility to create invitation enrollment URLs, and there is no out of box option to send created URL automatically via email (or some other channel) to the invited person. Similar what the heck surprise as for there is no simple option (out of box) for users to upload their avatar 😂. Luckily, we have this guy @drpetersen who solved avatar mystery here: #6824 (BIG THANKS!), but this is now some other story, and not related with my post. However, no matter, if we ignore these odd's, really good peace of software, and I can see that we getting new features with updates - THANKS FOR THAT! I also understand that Authentik guys most probably cannot implement everything at once.

I will describe how I accomplished to automatically send email invitation to invited person when invitation is created. This email also contain invitation enrollment URL and other important data. I will describe 3 different approaches:

1. Sending text mail invitation with the help of policy in Authentik
2. Sending fancy HTML mail invitation with the help of policy in Authentik
3. Sending fancy HTML mail invitation with the help of the python script on the host, outside of Authentik containers

This guide presume that you already have some enrollment flow, so that invitation URL will open enrollment flow for invited user. I made my enrollment flow with the help of this guide: https://youtu.be/mGOTpRfulfQ?t=424 Please note that first half of this video is about how to enable "Sign Up" link on Authentik login page. This way, everyone from the internet would be able to register in your Authentik. I have some feeling that most of the home lab users wouldn't want that, rather would want that invited people only could register. If you share my opinion/use case, then ignore first part of the video and watch second part, i.e. from the link timestamp. If you already have your enrollment flow - ignore provided video at all.

Ok, once when you have enrollment flow, let's setup automatic email invite. This also presume that you already have your email parameters (username, password, etc.) loaded as environment variables in Authentik, and your email is working. Here is a little background:

• I am running Authentik with docker compose (as most of you)
• I am using official docker-compose.yaml, which is slightly edited. These edits are not relevant with the first and second approaches of this guide, I will describe edits and why I made it, in third approach

So, ok, regarding email environment variables I mentioned before, this is what I have in my .env file (and what is related to email). I will use here some dummy domains, passwords, etc. of course:

AUTHENTIK_EMAIL__HOST=smtp.my.mail
AUTHENTIK_EMAIL__PORT=465
AUTHENTIK_EMAIL__USERNAME=admin@my.domain
AUTHENTIK_EMAIL__PASSWORD=app-password-here
AUTHENTIK_EMAIL__USE_TLS=false
AUTHENTIK_EMAIL__USE_SSL=true
AUTHENTIK_EMAIL__TIMEOUT=10
AUTHENTIK_EMAIL__FROM="Technical Support <admin@my.domain>"

First approach - Sending text mail invitation with the help of policy in Authentik

1. Go to Events > Notification Rules and create dummy empty fake notification rule like this:
   
   As you can see, this ^ rule doing nothing. But I don't know some other way that I can attach policy which would be executed when invitation is created. And in this certain case, policy (going next) is python script which:

• Listening for new events
• Filtering events and waiting for app == authentik_stages_invitation and model_name == invitation, this means invitation created
• Composing and sending email

2. Expand previously created Notification Rule, and go to Create and bind Policy (I already have policy bound on screenshot):
   

3. Choose Expression Policy and Next:
   

4. Give Policy the name, paste python script I will provide in next steps into Expression field, and click Next:
   

5. Click Finish on last screen, you can leave all default:
   

After this, you should have your Policy bound to your Notification Rule.

Python script/expression

This is the script which should be pasted into Expression field from step 4:

# Import necessary modules
import os
import smtplib
from email.mime.text import MIMEText
from django.apps import apps
from datetime import datetime

AUTHENTIK_DOMAIN_NAME = "my.domain"
invited_email = "admin@my.domain"
invited_name = "Padawan"
invited_username = "Padawan"

# Ensure the policy is triggered by an event
if "event" not in request.context:
    return False

event = request.context["event"]

# Check if the event action is 'model_created' and pertains to the 'invitation' model
if event.action == "model_created" and event.context.get("model", {}).get("app") == "authentik_stages_invitation" and event.context.get("model", {}).get("model_name") == "invitation":
    
    # Retrieve the Invitation model
    Invitation = apps.get_model("authentik_stages_invitation", "invitation")
    
    # Fetch the specific invitation instance using the primary key from the event context
    try:
        invitation = Invitation.objects.get(pk=event.context["model"]["pk"])
    except Invitation.DoesNotExist:
        return False

    # Extract invitation's fixed_data (custom attributes)
    custom_attributes = invitation.fixed_data
    if (custom_attributes.get("email") != None):
        invited_email = custom_attributes.get("email")
    if (custom_attributes.get("name") != None):
        invited_name = custom_attributes.get("name")
    if (custom_attributes.get("username") != None):
        invited_username = custom_attributes.get("username")

    # Extract invitation's expire date and format it to more eye friendly
    expires_date = datetime.fromisoformat(str(invitation.expires))
    expires_friendly = expires_date.strftime("%a, %b %d, %Y, %I:%M%p %Z")

    # Create invitation URL
    invitation_uid = event.context.get("model", {}).get("pk")
    invitation_url = f"https://{AUTHENTIK_DOMAIN_NAME}/if/flow/enrollment-invitation/?itoken={invitation_uid}"
    
    if not invited_email or not invited_name or not invited_username or not expires_date or not invitation_uid or not invitation_url:
        return False

    # Email configuration
    email_sender = os.environ.get('AUTHENTIK_EMAIL__USERNAME')
    email_password = os.environ.get('AUTHENTIK_EMAIL__PASSWORD')
    email_from = os.environ.get('AUTHENTIK_EMAIL__FROM')
    email_server = os.environ.get('AUTHENTIK_EMAIL__HOST')
    email_port = int(os.environ.get('AUTHENTIK_EMAIL__PORT'))

    if not email_sender or not email_password or not email_from or not email_server or not email_port:
        return False

    # Create the email content
    email_subject = f"{invited_name}, you're Invited!"
    email_body = f"Hello {invited_name},\n\nYou've been invited to join. Please use the following link to accept the invitation:\n\n{invitation_url}\n\nInvitation link expires on: {expires_friendly}\n\nBest regards,\nThe {AUTHENTIK_DOMAIN_NAME} Team"
    email_msg = MIMEText(email_body)
    email_msg['Subject'] = email_subject
    email_msg['From'] = email_from
    email_msg['To'] = invited_email

    # Send the email
    try:
        if email_port == 465:
            with smtplib.SMTP_SSL(email_server, email_port) as server:
                server.login(email_sender, email_password)
                server.sendmail(email_sender, email_msg['To'], email_msg.as_string())
        elif email_port == 587:
            with smtplib.SMTP(email_server, email_port) as server:
                server.starttls()  # Secure the connection
                server.login(email_sender, email_password)
                server.sendmail(email_sender, email_msg['To'], email_msg.as_string())
        else:
            return False
    except Exception as e:
        return False

    return True

return False

Few more notes

Lines 8-11 - change variable values to your own values:

AUTHENTIK_DOMAIN_NAME = "my.domain"
invited_email = "admin@my.domain"
invited_name = "Padawan"
invited_username = "Padawan"

AUTHENTIK_DOMAIN_NAME is fixed variable and will not be changed anywhere during script execution.
For other 3 - as soon as I explain how to use this and how to create invitation in order that mail being sent to some desired address, I will also explain why I set them initially to above values.

How to create invitation in order that invited party get email

Go to Directory > Invitations > Create, and except of invitation Name, Expires and Flow, fill also some data in Custom attributes. This is important, because the script/policy will get the value of the email field from Custom attributes and this will be receiver email address for your invitation. I am usually using following data (not mandatory, will explain):

{
  "name": "Johnny Silverhand",
  "username": "stiw47",
  "email": "stiw47@some.mail
}

At this point, you are done. Once when you click Create, if you followed previous guide carefully and set everything without mistake, stiw47@some.mail should receive the email with invitation URL and rest of the basic body text and subject from this part of the script:

    email_subject = f"{invited_name}, you're Invited!"
    email_body = f"Hello {invited_name},\n\nYou've been invited to join. Please use the following link to accept the invitation:\n\n{invitation_url}\n\nInvitation link expires on: {expires_friendly}\n\nBest regards,\nThe {AUTHENTIK_DOMAIN_NAME} Team"

As said, any of above fields is not mandatory, but I'm using username and name cause I figured out if I fill it like this, then Sign Up form will be already pre-populated with respective values, once when invited user open invitation URL, like below:

This not limiting username, name not even the email to ones pre-populated. Enrolled user can change any of those (and in my flow, user will have email verification stage), but people are usually lazy and not thinking too much outside of box, so in 99% cases I know I will find new user as I set it in Custom attributes.

Little more background

Once when you create invitation, it ends in Authentik's PostgreSQL DB, in table authentik_stages_invitation_invitation:

 < 👙 root@archmedia: docker-compose-nginx 🛃 > # docker exec -it authentik-postgresql psql -U authentik -d authentik -c "select * from authentik_stages_invitation_invitation;"
             invite_uuid              |        expires         |                                    fixed_data                                    | created_by_id | single_use | expiring |     name     |               flow_id                
--------------------------------------+------------------------+----------------------------------------------------------------------------------+---------------+------------+----------+--------------+--------------------------------------
 9be55f5a-7ece-472c-b15a-a5477c64a365 | 2025-02-28 17:04:00+00 | {"name": "Johnny Silverhand", "email": "stiw47@some.mail", "username": "stiw47"} |            41 | t          | t        | ytgiuojuigyu | fdac801a-ee0c-4539-92e3-a4ab458b219e
(1 row)

As you can see, all your Custom attributes ends in column fixed_data. So below part of the Python script is in charge to pull them:

    # Retrieve the Invitation model
    Invitation = apps.get_model("authentik_stages_invitation", "invitation")
    
    # Fetch the specific invitation instance using the primary key from the event context
    try:
        invitation = Invitation.objects.get(pk=event.context["model"]["pk"])
    except Invitation.DoesNotExist:
        return False

    # Extract invitation's fixed_data (custom attributes)
    custom_attributes = invitation.fixed_data
    if (custom_attributes.get("email") != None):
        invited_email = custom_attributes.get("email")
    if (custom_attributes.get("name") != None):
        invited_name = custom_attributes.get("name")
    if (custom_attributes.get("username") != None):
        invited_username = custom_attributes.get("username")

So what I said few paragraphs before, I am setting above variables to some initial values in order that email has some Hey <name> if I decide to skip the name, or that email goes to my inbox if I decide to skip email. TBH, now when I'm looking, I am not using username anywhere in email 😂😂.

One more thing: From my knowledge, SMTP IMAP mails are using either 465 or 587 port. If anyone anywhere is using some other port except of these two (I don't think so, right?), then script would need to be edited.

I think this is enough for now, probably already starts to be confusing. I will write second and third approaches most probably tomorrow, and much more short. Basically, setting workflow for second approach is the same, with the difference that you have prepared HTML mail template on storage, and python script should be slightly edited to replace text placeholders such as {{ url }}, {{ user.name }}... with actual data, and send this HTML template instead of plain text.

Be free to ask if something is not clear, and I would really like to hear opinions, suggestions, etc.
Cheers