Magic Link authentication allows users to log in securely without a password. This implementation is designed for Flex Server and Jans Server, providing a seamless authentication experience using a one-time link sent via email.
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-Magiclink 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
To send email messages, ensure you have the Jans Auth Server with SMTP service configured
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-Magiclink project. As shown, it contains configuration parameters for the flows contained in it:
{
"org.gluu.agama.magiclink": {
"hostName": "<host-name>",
"secretKey": "your-secreat-key",
"tokenExpiration": 10
}
}
Tip
openssl rand -base64 32
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.magiclink flow contained in the Agama-magiclink project,
specify the ACR value as agama_<qualified-name-of-the-top-level-flow>,
i.e agama_org.gluu.agama.magiclink.
Fork this repo to start customizing the Agama-magiclink project. It is possible to customize the user interface provided by the flow to suit your organization's branding guidelines. Or customize the overall flow behavior. Follow the best practices and steps listed here to achieve these customizations in the best possible way. This project can be reused in other Agama projects to create more complex authentication journeys. To reuse, trigger the org.gluu.agama.magiclink flow from other Agama projects.
To make it easier to visualize and customize the Agama Project, use Agama Lab.
List of the flows:
The main flow of this project is org.gluu.agama.magiclink . In step one, the person enters their email address, to which the IDP sends an token. After token verification, the flow is successful.
A basic diagram to understand how the agama-magiclink works.
sequenceDiagram
title Agama-magiclink Authentication Flow
actor User
participant Client
participant Server
participant Email
participant Mailbox
User -> Client: Request Login
Client -> Server: Generate Magic Link
Server -> Email: Send Magic Link to User's Email
Email -> Mailbox: Deliver Email with Magic Link
User -> Mailbox: Open Email
User -> Client: Click Magic Link
Client -> Server: Validate Token
alt Token Valid
Server -> Client: Authenticate User
Client -> User: Redirect to Dashboard
else Token Expired/Invalid
Server -> Client: Show Error
Client -> User: Display Error Message
end