Ntfy and Webhooks in Authentik
How to setup custom webhooks notifications
What is Authentik?
Authentik is an open source identity provider with great usability and flexibility. It offers a wide range of protocol support for authentication and it includes everything you need to connect to other providers.
It also has support for FIDO authentication, which is great!
It is possible to modify the authentication flows as you want in a super easy way. You want the MFA before the password? A click or two and it’s done.
It is impressive to see such product being created and maintained by one single developer, great job!
More information on their documentation official website at https://goauthentik.io/docs/.
Webhooks
The goal of this post is to show how to properly setup webhooks. I personally have an instance of ntfy where I push my notifications and I thought it would be nice to hook up Authentik with it.
How to setup ntfy in Authentik? How to setup webhooks for ntfy in Authentik?
The documentation does not show practical examples, hence why I thought it might be useful to write it down step by step.
Here we are going to setup a webhook to send a message to a ntfy instance when an admin logs in.
Goal: Every defined event will send a notification to ntfy, for example a login from an administrator.
1. Create new notification transport
Under Events > Notification Transports you can Create a new transport.
Fill in the information such as name of the transport and the ntfy URL.
In order to authenticate to ntfy there are two options:
- Embed the auth token as a URL parameter.
- Insert the token a POST body parameter. (untested)
The first option requires the token to be set in the notification rule, the second option requires the token to be set in the property mapping.
For now, I have tested the option n.1 as the HTTPS connection encrypts the conversation and nothing is leaked, but I plan to switch to the n.2 as soon as possible. I have not found out how to add custom headers in the custom request yet, hence why.
Please, always be careful with ntfy token permissions, in this case the token can have the write only permissions to the specific topic and it doesn’t need to be able to read the channel.
2. Create a notification rule
As per the name, the notification rules allow you to define when to trigger the notifications.
In this example, we want to create a push notification when an administrator logs in.
- Input the name for the rule then select the ntfy (test-notification in the previous example) Transport from the list then Apply.
- Click on the newly created Rule and you’ll see two options: Create & bind Policy and Bind Existing Policy.
-
The first time you need to create it, so click the first option.
-
You’ll see many types of policies, you can have fun. For now let’s use the Event Matcher Policy
- Set the name of the policy and then select the Login Action. Note all the possibilities.
- Continue and then select Group. Select the authentik Admins here.
- Finish the policy creation.
3. Create a Property Mapping
Property Mappings let you define the type of payload the request will contain when notifications are triggered.
- Go to Customizations > Property Mappings > Create
- Select Webhook Mapping
Here comes the interesting part. You can use python code here to define your request payload!
In this case I wanted to print information from the user object.
return {
"topic": "gauth",
"message": "User: {} [{}] authenticated!\n".format(request.user.username,request.user.email),
}
More useful examples here:
4. Results
This is how the notification will be rendered when the admin logs in.
That’s all. With this example it will be easy to build more policies and notifications payloads.
I hope you found this post helpful. If you have any questions or feedback, feel free to leave a comment below.
Last modified: 30 July 2023