Skip to content

Quick Start Using Agama Lab#

In this quick start guide, we will build, deploy and test a simple password-based authentication flow using Agama and Agama Lab.

Agama Lab is an online visual editor to build authentication flows. A flow built on Agama Lab is packaged as a .gama project file. .gama package needs to be manually deployed on Janssen Server where the Agama engine will execute the flow when an authentication request is received.

Major Steps involved in this process are:

  • Create Agama project using Agama Lab
  • Deploying .gama package on Janssen Server
  • Testing the authentication flow

This guide covers these steps in the following sections.


  • Janssen Server instance
  • A public GitHub repository with at least one prior commit

Create Agama Project#

We will use Agama Lab to create a simple username-password based user authentication flow. This involves defining the authentication steps, designing the user interface to capture user inputs, and lastly, releasing the flow as an Agama project.

Defining The Authentication Flow#

Log Into Agama Lab#

  1. Go to Agama Lab login page.

  2. Authenticate on the GitHub authentication page.

  3. Input the name of the repository where Agama Lab should release the project artifacts. Click Next

  4. Project listing page will be shown. All the existing projects for your GitHub user are listed here. Projects can be created, edited, and deleted from the project listing page.

Create A New Project#

  1. To create a new project, click on the New Project button on the project listing page above. Enter the name and the description for the new project and click the Create button.

  2. This will create a new project and it'll be listed on the project listing page.

Create The Authentication Flow#

  1. Create A Flow File

    Click on

    The flow authoring view will open with a blank canvas. To start creating the flow, we need to create a Flow File. To do that,

    Right-click on code and then select New > Flow File

    Give name and description for the flow file and then click Create

    A newly created flow file has one block in it by default.

    Clicking on the block will allow you to add further blocks using or to edit the existing block using .

  2. Create AuthenticationService Call block

    Click on the block and then . Then select call

    A new Call block should appear with a link to Start block

    Click Call block and then click to open the configuration screen.

    Add configuration values as shown below.

    This will create a new instance of AuthenticationService class. This instance will be used to authenticate the user. The new instance will be stored in a variable called authService.

  3. Create CdiUtil Call block

    To perform authentication we will also need a bean instance of CdiUtil class. This bean instance
    takes AuthenticationService instance that we created in the previous step as an argument.

    Click the New Authentication Service block and then click on . Then click Call

    Click on the newly created Call block and by clicking open the configuration page. Input values as shown below in the configuration screen

  4. Create Assignment(s) block

    Next, we need to create an empty variable that the flow will use in the future to store authentication results.

    Click on New CdiUtil Object and then click . Select Assignment(s)

    Click on the newly created Assign block. Click . Input values as shown below in the configuration screen

  5. Create repeat block

    Repeat block represents the Repeat instruction of Agama DSL.

    Repeat block creates a loop to iterate over certain steps(blocks). We will create a repeat loop that allows 3 retries if the authentication fails.

    Click on the Result Object block and then click . Select Repeat.

    Click on the newly created Repeat block. Click . Input values as shown below in the configuration screen

  6. Create An RRF block

    RRF block represents the RRF instruction of Agama DSL.

    Click on the Repeat block. Click . Check the In Repeat Block and then click on RRF.

    Click on the newly created Repeat block. Click . Input values as shown below in the configuration screen

    Since we have checked the In Repeat Block at the time of adding the RRF block, the RRF block as well as all the blocks that we add to the RRF block iterated blocks.

    At this stage, let's save the flow. Click Save on the flow canvas.

  7. Create a CdiUtil Call block

    Create a Call block to process the username and password received from the user (in RRF) and validate them. The result of validation should be stored in a variable.

    Click on the RRF block. Click . Click on Call.

    Click on the newly created Call block. Click . Input values as shown below in the configuration screen

  8. Create An Assignment block

    In case of authentication failure, we want to show the username to the user while reentering the password on the web page. For this, we will save the username in a variable using the Assignment(s) block.

    Click on the Call block. Click . Click on Assignment(s).

    Click on the newly created Call block. Click . Input values as shown below in the configuration screen

  9. Create A Conditional When block

    When block represents the When instruction of Agama DSL.

    Create a conditional check using the When block to check if the authentication (validated in validate credentials block) has been successful.

    Click on Assignment(s) block. Click . Click on When.

    Click on the newly created When block. Click . Input values as shown below in the configuration screen

  10. Create finish blocks

    The Finish block represents the Flow finish instruction of Agama DSL.

    If the authentication was successful then the flow should finish and return the username. This will be achieved by adding a Finish block to the When block. And if authentication fails after 3 attempts, we need another Finish block following the Repeat block.

    Click on the When block. Click . Click on Condition met and then click Finish

    Click on the newly created Finish block. Click . Input values as shown below in the configuration screen

    Click on the Repeat block. Click . Click Finish

    Click on the newly created Finish block. Click . Input values as shown below in the configuration screen and click Save.

    Save the flow using the Save button on flow canvas.

    The completed flow looks like below:

  11. Check Generated code

    Agama Lab flow gets translated in Agama DSL. Click the Code button to see the code generated by the flow.

     Flow co.acme.password
      Basepath ""
     authService = Call
     cdiUtil = Call io.jans.service.cdi.util.CdiUtil#bean authService
     authResult = {}
     Repeat 3 times max
       creds = RRF "login.ftlh" authResult
       authResult.success = Call cdiUtil authenticate creds.username creds.password
       authResult.uid = creds.username
       When authResult.success is true
         Finish authResult.uid
     Finish false

Design User Interface#

In the RRF configuration step, we mentioned login.ftlh to render the login page elements. We need to add login.ftlh to the Agama project so that the flow can use during the flow execution. Use the steps below to create the page.

  1. Create a template file

    On the left project explorer menu, click on web > New > Freemarker Template

    Select + Create under the New Blank Template

    Give Name and Description as shown below and click Create

  2. Use the visual editor

    This opens a visual editor to create a freemarker template. Use this visual editor to create a template as per the need. For this article, we will use the code below.

    Click Edit HTML. This opens a text editor. Remove existing code in the editor and paste the code shown below.

    <!doctype html>
    <html xmlns="">
         <title> Jans Agama Basic Auth flow </title>
         <hr />
         [#if !(success!true)]
           <p class="fs-6 text-danger mb-3">${msgs["login.errorMessage"]}</p>
         <hr />
         <form method="post" enctype="application/x-www-form-urlencoded">
               Username: <input type="text" class="form-control" name="username" id="username" value="${uid!}" required>
               Password: <input type="password" class="form-control" id="password" name="password">
               <input type="submit" class="btn btn-success px-4" value="Login">
           input {
               border: 1px solid #000000;

    Click Save changes

    This will render the page in the visual editor.

Release The Project#

To use the flow for authentication in the Janssen Server, the flow needs to be released. Agama Lab releases the flow and the related artifacts (like template) in the form of a .gama file in the GitHub repository.

To release the project, click on any of the files in the left project explorer, and click Release Project.

Enter a desired version number and click Save

Upon successful release, Agama Lab Releases dashboard is shown. It lists all projects that are released.

Click on the project name to go to the GitHub repository release page where .gama file has been released

Download the .gama file from here to deploy on to the Janssen Server.

Deploy Agama Project#


Please ensure that Agama engine and scripts are enabled in Janssen Server deployment

  1. Download the .gama file from the GitHub repository
  2. Open TUI using following commands on Janssen Server

    cd /opt/jans/jans-cli
  3. Navigate to Auth Server > Agama > Upload Project. Select the .gama file to upload.


  1. Setup Janssen Tent
  2. Change the configuration as given below in

    ACR_VALUES = "agama_co.acme.password.flow"
  3. Run the Tent test by accessing it via the browser

Last update: 2024-06-21
Created: 2023-05-05