Quick Start Guide

Agama Lab Quick Start Guide

Overview

Agama Lab tool helps developers to make a flow for Jans Agama.

Table of Content

Agama-Lab Online Tool
Make a Project
Make a Flow File
Make a Simple Basic Auth Flow
Download Basic Flow
Make a template file
Make a gama file / Release Project
Deploy a gama file on Jans
Testing using Jans Tent

Agama-Lab Online Tool

Use https://cloud.gluu.org/agama-lab online tool to make an agama flow. Hit the above URL and you will see a page with Login with GitHub button. Click on it and give access to agama-lab.

In the next step, it will ask you to enter the repository path. Right now, Agama Lab always users your personal repository. You just need to enter your repository name. For Example: if your repository URL is https://github.com/temp-user/agama-projects then just enter the repository name agama-projects.

Your repository must have at least one Git Commit to proceed. Just making a fresh new repo with README.md will be good.

Make a Project

The first step is to make a Project.

Navigate to the Project Tree File view to make Agama Flows and .gama files.

Make a Flow File

Right Click on the Code folder and select New Flow file

Enter Details in Form

Make a Simple Basic Auth Flow

Final look at the flow diagram:

Save it and you can click on the Code button to see the actual flow

It will look like this:

Flow co.basic
     Basepath ""
authService = Call io.jans.as.server.service.AuthenticationService#class 
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

Download Basic Flow

If you created the above flow successfully then skip this part. There is an import facility. If you have any existing flow’s JSON file then you can directly import and make a flow quickly. co.basic.zip Download the above zip, extract it, and import the JSON file:

Make a template file

The above flow is using login.ftlh template file. Let’s create it.

Right-click on the web folder and select the new free maker template

Select Template and add details. It is up to you to make a beautiful design using UI-Editor.

Edit HTML to add existing code. You can make your own.

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

Once you save the file. It will add [#ftl output_format="HTML"] which is needed because we are using [#if... instead of <#if....

Notice If you want to add code like <input type="submit" class="btn btn-success px-4" value="${msgs["login.login"]}"> then it will not work instead of add <input type="submit" class="btn btn-success px-4" value="${msgs['login.login']}"/>.You need to use a single quote inside a double quote.

Make a gama file / Release Project

Right-click on anything in File Tree and select Release Project

Deploy a gama file on Jans

Make sure you have enabled Agama and Agama Script on your Jans server. Check Agama Docs for Details
Let’s enable it using TUI, Open TUI in your Jans Server

# cd /opt/jans/jans-cli
# python3 jans_cli_tui.py

Enable Agama Configuration, In TUI, navigate to AuthServer > Properties > agamaConfiguration > Enabled [*] > Save

Enable Agama Script, In TUI, navigate to Scripts > Search 'agama' > Select script Enabled [*] > Save

Move your .gama file to your Jans server

Navigate to Auth Server > Agama > Upload Project

Select a file and upload

You should see now uploaded project in the list

Check your Jans logs for Any Errors

Testing using Jans Tent

Setup Jans-Tent. Instructions
Setup config.py as per your need.
Configuration to run Agama flow

ACR_VALUES = "agama"
ADDITIONAL_PARAMS = {
    'agama_flow': 'co.basic'
}

Run Tent

Successfully login