This repo is the home of the Gluu Agama-profile-edit project. This Agama project allows users to update their profile after email-based authentication. For email-based authentication, we have a community project called Agama-SMTP. Here, we use the Agama-SMTP project as an example of reusing a community project and applying template overriding.
The project can be deployed to any IAM server that runs an implementation of the Agama Framework like Janssen Server and Gluu Flex.
Different IAM servers may provide different methods and user interfaces from where an Agama project can be deployed on that server. The steps below show how the Agama-profile-edit project can be deployed on the Janssen Server.
Deployment of an Agama project involves three steps.
- Downloading the
.gamapackage from the project repository - Adding the
.gamapackage to the IAM server - Configure the project
Here we re-use our existing Agama-SMTP project, So It's mendatory to deploye Agama-SMTP project from community project. To send email messages, ensure you have the Jans Auth Server with SMTP service configured
To use template overriding set the flow’s current path and basepath (in our case, it is empty). After deploying, copy the derived template from the project directory to the current project directory and modify as needed.
Tip
Skip this step if you use the Janssen Server TUI tool to
configure this project. The TUI tool enables the download and adding of this
project directly from the tool, as part of the community projects listing.
The project is bundled as
.gama package.
Visit the Assets section of the
Releases to download the .gama package.
The Janssen Server provides multiple ways an Agama project can be deployed and configured. Either use the command-line tool, REST API, or a To send email messages, ensure you have the Jans Auth Server set up. It includes an SMTP service for sending emails, but you need to configure it before use. TUI (text-based UI). Refer to Agama project configuration page in the Janssen Server documentation for more details.
The Agama project accepts configuration parameters in the JSON format. Every Agama project comes with a basic sample configuration file for reference.
Below is a typical configuration of the Agama-SMTP project. As shown, it contains configuration parameters for the flows contained in it:
{
"org.gluu.agama.profile.update.main": {
}
}
Use any relying party implementation (like jans-tarp) to send an authentication request that triggers the flow.
From the incoming authentication request, the Janssen Server reads the ACR
parameter value to identify which authentication method should be used.
To invoke the org.gluu.agama.profile.update.main flow contained in the Agama-Profile-Edit project,
specify the ACR value as agama_<qualified-name-of-the-top-level-flow>,
i.e agama_org.gluu.agama.profile.update.main.
[N.B] If you try to direct use this flow then you may experience an error
An unexpected error ocurred:
Template not found for name "/ftl/qhgqww/main.ftlh". The name was interpreted by this TemplateLoader: FileTemplateLoader(baseDir="/opt/jans/jetty/jans-auth/agama", canonicalBasePath="/opt/jans/jetty/jans-auth/agama/").
Try again later
This error occurs if we reference template overriding in our flow without properly implementing the template override mechanism. For example, as shown below, we trigger the agama-smtp flow and want to override its templates as well.
Therefore, we must specify both the directory of the original assets and the actual path of our own assets. By ‘our assets,’ we mean the templates copied from the agama-smtp project directory.
The question is when we should do this:
First, deploy the agama-smtp project. Then, reference its asset paths in our flow.
(See the screenshot below.)
Second, deploy agama-profile-edit and copy the agama-smtp assets into the agama-profile-edit project directory.
In my case:
-
agama-smtp directory:
/opt/jans/jetty/jans-auth/agama/ftl/hyyqd9 -
agama-profile-edit directory:
/opt/jans/jetty/jans-auth/agama/ftl/qhgqww
Finally, if someone wants to use our flow exactly as-is, they must complete these steps. This project serves as an example of how to reuse one Agama project in another and how to override templates correctly.
List of the flows:
The main flow of this project is org.gluu.agama.profile.update.main . In step one, the person enters their email address, to which the IDP sends an OTP code. After OTP verification, if the email is recognized, the user is shown a profile update form. Upon submission, the system updates the user’s profile (if validation succeeds) and then completes the flow with an acknowledgment message If the email address is new, the IDP displays a registration form.