diff --git a/docs/assets/agama-create-assignment.png b/docs/assets/agama-create-assignment.png new file mode 100644 index 00000000000..22138255e05 Binary files /dev/null and b/docs/assets/agama-create-assignment.png differ diff --git a/docs/assets/agama-create-cdiutil.png b/docs/assets/agama-create-cdiutil.png new file mode 100644 index 00000000000..c66ed1cdc43 Binary files /dev/null and b/docs/assets/agama-create-cdiutil.png differ diff --git a/docs/assets/agama-create-repeat.png b/docs/assets/agama-create-repeat.png new file mode 100644 index 00000000000..03370ae1231 Binary files /dev/null and b/docs/assets/agama-create-repeat.png differ diff --git a/docs/assets/agama-lab-add-git-repo.png b/docs/assets/agama-lab-add-git-repo.png new file mode 100644 index 00000000000..b9797c6f481 Binary files /dev/null and b/docs/assets/agama-lab-add-git-repo.png differ diff --git a/docs/assets/agama-lab-create-assignment-uid.png b/docs/assets/agama-lab-create-assignment-uid.png new file mode 100644 index 00000000000..92c740710c8 Binary files /dev/null and b/docs/assets/agama-lab-create-assignment-uid.png differ diff --git a/docs/assets/agama-lab-create-cdiutil-instance.png b/docs/assets/agama-lab-create-cdiutil-instance.png new file mode 100644 index 00000000000..9f11faf8ecb Binary files /dev/null and b/docs/assets/agama-lab-create-cdiutil-instance.png differ diff --git a/docs/assets/agama-lab-flow-passwd-edit-assignment-uid.png b/docs/assets/agama-lab-flow-passwd-edit-assignment-uid.png index 619ff783f49..a6a60e84561 100644 Binary files a/docs/assets/agama-lab-flow-passwd-edit-assignment-uid.png and b/docs/assets/agama-lab-flow-passwd-edit-assignment-uid.png differ diff --git a/docs/assets/agama-lab-flow-passwd-edit-finish.png b/docs/assets/agama-lab-flow-passwd-edit-finish.png index 8cfe83c83b2..97058427098 100644 Binary files a/docs/assets/agama-lab-flow-passwd-edit-finish.png and b/docs/assets/agama-lab-flow-passwd-edit-finish.png differ diff --git a/docs/assets/agama-lab-flow-password-create-when.png b/docs/assets/agama-lab-flow-password-create-when.png new file mode 100644 index 00000000000..4f997b75e15 Binary files /dev/null and b/docs/assets/agama-lab-flow-password-create-when.png differ diff --git a/docs/assets/agama-lab-flow-password-edit-when.png b/docs/assets/agama-lab-flow-password-edit-when.png new file mode 100644 index 00000000000..46bee9b079f Binary files /dev/null and b/docs/assets/agama-lab-flow-password-edit-when.png differ diff --git a/docs/assets/agama-lab-flow-render-template.png b/docs/assets/agama-lab-flow-render-template.png new file mode 100644 index 00000000000..b1cf0150db7 Binary files /dev/null and b/docs/assets/agama-lab-flow-render-template.png differ diff --git a/docs/assets/agama-lab-flow-save-template.png b/docs/assets/agama-lab-flow-save-template.png new file mode 100644 index 00000000000..3225816914c Binary files /dev/null and b/docs/assets/agama-lab-flow-save-template.png differ diff --git a/docs/assets/agama-lab-git-login.png b/docs/assets/agama-lab-git-login.png new file mode 100644 index 00000000000..87183c7e0ec Binary files /dev/null and b/docs/assets/agama-lab-git-login.png differ diff --git a/docs/assets/agama-login.png b/docs/assets/agama-login.png new file mode 100644 index 00000000000..2b6ac2bfa38 Binary files /dev/null and b/docs/assets/agama-login.png differ diff --git a/docs/assets/agama-loginpage.png b/docs/assets/agama-loginpage.png new file mode 100644 index 00000000000..6689699a381 Binary files /dev/null and b/docs/assets/agama-loginpage.png differ diff --git a/docs/assets/agamalab-flow-passwd-1.png b/docs/assets/agamalab-flow-passwd-1.png new file mode 100644 index 00000000000..af7a3c3ff0f Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-1.png differ diff --git a/docs/assets/agamalab-flow-passwd-call.png b/docs/assets/agamalab-flow-passwd-call.png new file mode 100644 index 00000000000..89108fb9210 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-call.png differ diff --git a/docs/assets/agamalab-flow-passwd-create-call.png b/docs/assets/agamalab-flow-passwd-create-call.png new file mode 100644 index 00000000000..f58f98f03ba Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-create-call.png differ diff --git a/docs/assets/agamalab-flow-passwd-create-fail-finish.png b/docs/assets/agamalab-flow-passwd-create-fail-finish.png new file mode 100644 index 00000000000..5ece17bccf9 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-create-fail-finish.png differ diff --git a/docs/assets/agamalab-flow-passwd-create-finish.png b/docs/assets/agamalab-flow-passwd-create-finish.png new file mode 100644 index 00000000000..9f99230868f Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-create-finish.png differ diff --git a/docs/assets/agamalab-flow-passwd-edit-assignment.png b/docs/assets/agamalab-flow-passwd-edit-assignment.png new file mode 100644 index 00000000000..e1935360d47 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-edit-assignment.png differ diff --git a/docs/assets/agamalab-flow-passwd-edit-cdiUtil-instance.png b/docs/assets/agamalab-flow-passwd-edit-cdiUtil-instance.png new file mode 100644 index 00000000000..8543e0d5b02 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-edit-cdiUtil-instance.png differ diff --git a/docs/assets/agamalab-flow-passwd-edit-cdiutil-instance.png b/docs/assets/agamalab-flow-passwd-edit-cdiutil-instance.png new file mode 100644 index 00000000000..f688ed3a121 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-edit-cdiutil-instance.png differ diff --git a/docs/assets/agamalab-flow-passwd-edit-cdiutil.png b/docs/assets/agamalab-flow-passwd-edit-cdiutil.png new file mode 100644 index 00000000000..7e2cbf5c718 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-edit-cdiutil.png differ diff --git a/docs/assets/agamalab-flow-passwd-edit-fail-finish.png b/docs/assets/agamalab-flow-passwd-edit-fail-finish.png new file mode 100644 index 00000000000..c1c64fcf5f0 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-edit-fail-finish.png differ diff --git a/docs/assets/agamalab-flow-passwd-edit-repeat.png b/docs/assets/agamalab-flow-passwd-edit-repeat.png new file mode 100644 index 00000000000..25081cd90b4 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-edit-repeat.png differ diff --git a/docs/assets/agamalab-flow-passwd-edit-rrf.png b/docs/assets/agamalab-flow-passwd-edit-rrf.png new file mode 100644 index 00000000000..2d7fcea5be0 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-edit-rrf.png differ diff --git a/docs/assets/agamalab-flow-passwd-edit-template.png b/docs/assets/agamalab-flow-passwd-edit-template.png new file mode 100644 index 00000000000..79b3d199d35 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-edit-template.png differ diff --git a/docs/assets/agamalab-flow-passwd-edit-validationService-instance.png b/docs/assets/agamalab-flow-passwd-edit-validationService-instance.png new file mode 100644 index 00000000000..f11eaa4d8d8 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-edit-validationService-instance.png differ diff --git a/docs/assets/agamalab-flow-passwd-editcdiutil.png b/docs/assets/agamalab-flow-passwd-editcdiutil.png new file mode 100644 index 00000000000..c89d5b44ee2 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-editcdiutil.png differ diff --git a/docs/assets/agamalab-flow-passwd-new-call.png b/docs/assets/agamalab-flow-passwd-new-call.png new file mode 100644 index 00000000000..97dd3b5741e Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-new-call.png differ diff --git a/docs/assets/agamalab-flow-passwd-publish-project-gh.png b/docs/assets/agamalab-flow-passwd-publish-project-gh.png new file mode 100644 index 00000000000..401527d42b6 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-publish-project-gh.png differ diff --git a/docs/assets/agamalab-flow-passwd-publish-project.png b/docs/assets/agamalab-flow-passwd-publish-project.png new file mode 100644 index 00000000000..c4f7d212ce0 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-publish-project.png differ diff --git a/docs/assets/agamalab-flow-passwd-release-project-gh.png b/docs/assets/agamalab-flow-passwd-release-project-gh.png new file mode 100644 index 00000000000..3391d04fc8b Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-release-project-gh.png differ diff --git a/docs/assets/agamalab-flow-passwd-release-project.png b/docs/assets/agamalab-flow-passwd-release-project.png new file mode 100644 index 00000000000..0881b3a0727 Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-release-project.png differ diff --git a/docs/assets/agamalab-flow-passwd-select-template.png b/docs/assets/agamalab-flow-passwd-select-template.png new file mode 100644 index 00000000000..a046e41554a Binary files /dev/null and b/docs/assets/agamalab-flow-passwd-select-template.png differ diff --git a/docs/assets/agamalab-new-flow-name.png b/docs/assets/agamalab-new-flow-name.png new file mode 100644 index 00000000000..a5a9dcbc1d3 Binary files /dev/null and b/docs/assets/agamalab-new-flow-name.png differ diff --git a/docs/assets/agamalab-new-flow.png b/docs/assets/agamalab-new-flow.png new file mode 100644 index 00000000000..333f5eb58b3 Binary files /dev/null and b/docs/assets/agamalab-new-flow.png differ diff --git a/docs/assets/agamalab-new-proj.png b/docs/assets/agamalab-new-proj.png new file mode 100644 index 00000000000..90058769b07 Binary files /dev/null and b/docs/assets/agamalab-new-proj.png differ diff --git a/docs/assets/agamalab-project-listing.png b/docs/assets/agamalab-project-listing.png new file mode 100644 index 00000000000..529c3fef2b6 Binary files /dev/null and b/docs/assets/agamalab-project-listing.png differ diff --git a/docs/assets/agamalab-project-page.png b/docs/assets/agamalab-project-page.png new file mode 100644 index 00000000000..27436f3e663 Binary files /dev/null and b/docs/assets/agamalab-project-page.png differ diff --git a/docs/assets/authentication-flow-input.png b/docs/assets/authentication-flow-input.png new file mode 100644 index 00000000000..aea238c2aed Binary files /dev/null and b/docs/assets/authentication-flow-input.png differ diff --git a/docs/assets/check-repeat.png b/docs/assets/check-repeat.png new file mode 100644 index 00000000000..7fd00bf6b0d Binary files /dev/null and b/docs/assets/check-repeat.png differ diff --git a/docs/assets/image-agama-lab-edit-authn-instance.png b/docs/assets/image-agama-lab-edit-authn-instance.png new file mode 100644 index 00000000000..c8ba6eb7189 Binary files /dev/null and b/docs/assets/image-agama-lab-edit-authn-instance.png differ diff --git a/docs/assets/image-agama-lab-flow-quick-start-guide.png b/docs/assets/image-agama-lab-flow-quick-start-guide.png new file mode 100644 index 00000000000..8753996399a Binary files /dev/null and b/docs/assets/image-agama-lab-flow-quick-start-guide.png differ diff --git a/docs/assets/select-agama-project.png b/docs/assets/select-agama-project.png new file mode 100644 index 00000000000..7730acf1347 Binary files /dev/null and b/docs/assets/select-agama-project.png differ diff --git a/docs/assets/select-community-agamaproject.png b/docs/assets/select-community-agamaproject.png new file mode 100644 index 00000000000..8440ddfb1c5 Binary files /dev/null and b/docs/assets/select-community-agamaproject.png differ diff --git a/docs/assets/successful-tarp-auth-screen.png b/docs/assets/successful-tarp-auth-screen.png new file mode 100644 index 00000000000..8ddacb3d196 Binary files /dev/null and b/docs/assets/successful-tarp-auth-screen.png differ diff --git a/docs/assets/tarp-client-reg.png b/docs/assets/tarp-client-reg.png new file mode 100644 index 00000000000..9729b53042f Binary files /dev/null and b/docs/assets/tarp-client-reg.png differ diff --git a/docs/assets/upload-gama-file.png b/docs/assets/upload-gama-file.png new file mode 100644 index 00000000000..1bf2a3cbcfd Binary files /dev/null and b/docs/assets/upload-gama-file.png differ diff --git a/docs/janssen-server/developer/agama/quick-start-using-agama-lab.md b/docs/janssen-server/developer/agama/quick-start-using-agama-lab.md index df56dce9e18..3fa815a231a 100644 --- a/docs/janssen-server/developer/agama/quick-start-using-agama-lab.md +++ b/docs/janssen-server/developer/agama/quick-start-using-agama-lab.md @@ -4,277 +4,370 @@ tags: - developer - agama - agama lab + - quick start --- -# Quick Start Using Agama Lab +# 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](https://cloud.gluu.org/agama-lab). - -[Agama Lab](https://cloud.gluu.org/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. +In this quick start guide, we will build, deploy and test a simple Agama +project using the [Agama Lab](https://cloud.gluu.org/agama-lab). +This project will enable user authentication using password when deployed on +an IDP. Major Steps involved in this process are: -- Create Agama project using Agama Lab -- Deploying `.gama` package on Janssen Server -- Testing the authentication flow +- [Create a new Agama project on the Agama Lab](#create-a-new-agama-project) +- [Defining the authentication flow](#defining-the-authentication-flow) +- [Design the user interface](#design-user-interface) +- [Deploy Agama project](#deploy-agama-project) +- [Test using Tarp](#testing-using-janssen-tarp) -This guide covers these steps in the following sections. +This guide covers steps above in the following sections. ## Prerequisites -- Janssen Server instance -- A public GitHub repository with at least one prior commit +- We will use the [Janssen Server](https://jans.io) to deploy the Agama project. +Follow the instructions [here](https://docs.jans.io/head/janssen-server/install/) +to install the Janssen Server. +- You will need a GitHub account where Agama Lab GitHub app has been [integrated](https://gluu.org/agama/sign-up-sign-in/). GitHub +account can be a personal account or an organizational account. For this guide +we will assume that a personal account is being used. +- Two new public GitHub repositories in your GitHub Account. These repositories +will be used as [development repository](https://gluu.org/agama/flow-designer/) and [release repository](https://gluu.org/agama/flow-designer/). Each repository should have at least one +commit. +- Agama Lab should have permissions to access the development and the release repositories. This can be configured +using the [Agama Lab GitHub app](https://gluu.org/agama/how-to-integrate-agama%e2%80%90lab-github-app-with-your-github-account/) in your user account. + + +## Create a new Agama project + +We will use [Agama Lab](https://cloud.gluu.org/agama-lab/) to create a simple +username-password based user authentication project. The authentication flow +will be similar to the one shown below. + +![](../../../assets/image-agama-lab-flow-quick-start-guide.png) -## Create Agama Project +An Agama project may include multiple components. For example, an authentication +flow, a user interface, assets like organization's logo, external libraries, etc. +In this project, we will see how to -We will use [Agama Lab](https://cloud.gluu.org/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. +- Define the authentication steps of a flow +- Design the user interface to capture user inputs -### Defining The Authentication Flow +Let's get started. -#### Log Into Agama Lab +### Log into the Agama Lab -1. Go to [Agama Lab](https://cloud.gluu.org/agama-lab) login page. - ![](../../../assets/agama-lab-login.png) +1. Go to [Agama Lab](https://cloud.gluu.org/agama-lab) login page. Sign in using +GitHub. + + ![](../../../assets/agama-loginpage.png) 2. Authenticate on the GitHub authentication page. - ![](../../../assets/agama-lab-GH-login.png) + ![](../../../assets/agama-lab-git-login.png) -3. Input the name of the repository where Agama Lab should release the project artifacts. Click `Next` +3. After successful sign in, the [project dashboard](https://gluu.org/agama/agama-lab-project-dashboard/) +will be shown. Next step is to select the repository where you want to create +the project. Select the `development` repository by clicking on +`Change Repository` -> `Your Repositories` -> select the repository -> `Select`. + + ![](../../../assets/agama-lab-add-git-repo.png) - ![](../../../assets/agama-lab-add-gh-repo.png) -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. +4. The project dashboard with all the existing projects (if any) from the GitHub +repository will be shown. New projects can be created, edited, and deleted +from this project listing page. - ![](../../../assets/agama-lab-project-page.png) + ![](../../../assets/agamalab-project-page.png) -#### Create A New Project +### Create a new project -1. To create a new project, click on the `New Project` button on the project listing page above. +1. To create a new project, click on the `New Project` button. Enter the name and the description for the new project and click the `Create` button. - ![](../../../assets/agama-lab-new-proj.png) + ![](../../../assets/agamalab-new-proj.png) -2. This will create a new project and it'll be listed on the project listing page. +2. This will create a new project. - ![](../../../assets/agama-lab-project-listing.png) + ![](../../../assets/agamalab-project-listing.png) +### Defining the authentication flow -#### Create The Authentication Flow +1. Create a flow file -1. Create A Flow File + Open the newly created project by clicking on :material-arrow-top-right:. + This will open the project in the [project editor](https://gluu.org/agama/project-editor/). + + To start creating the flow, right-click on the `code` directory > `New` > `Flow File`. - _Click on :material-arrow-top-right:_ + ![](../../../assets/agamalab-new-flow.png) - 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, + Give name and description for the flow file and then click `Create`. - _Right-click on `code` and then select `New` > `Flow File`_ + ![](../../../assets/agamalab-new-flow-name.png) - ![](../../../assets/agama-lab-new-flow.png) + A newly created flow file contains one `start` block. - _Give name and description for the flow file and then click `Create`_ + ![](../../../assets/agamalab-flow-passwd-1.png) + - ![](../../../assets/agama-lab-new-flow-name.png) + In the subsequent steps, we are going to create nodes in the flow using the + flow editor. Refer to [this](https://gluu.org/agama/project-editor/) guide if you need to understand how + to create, delete and configure nodes. - A newly created flow file has one block in it by default. +2. Create `Get class reference` Call block - ![](../../../assets/agama-lab-flow-passwd-1.png) + To perform authentication we need to validate username and password + provided by the user with the IDP. This operation is done using an instance + reference of `AuthenticationService` class. - Clicking on the block will allow you to add further blocks using :material-plus-circle: or to edit the existing - block using :material-pencil:. + To get the instance reference from the IDP, we first need the class + reference of the `AuthenticationService` class. That is what we will do + in this step. -2. Create _AuthenticationService_ Call block + Drag the colored dot available on the right edge of the `start` node to + create the next node in the flow. A list of available node types will be + presented. - _Click on the block and then :material-plus-circle:. Then select `call`_ + ![](../../../assets/agamalab-flow-passwd-create-call.png) - ![](../../../assets/agama-lab-flow-passwd-create-call.png) + Select `Call` node. A new `Call` block should appear with a link to the + `Start` block - A new `Call` block should appear with a link to `Start` block + ![](../../../assets/agamalab-flow-passwd-new-call.png) - ![](../../../assets/agama-lab-flow-passwd-new-call.png) + Click the `Call` block and then click :material-pencil: to open the + configuration screen. Add configuration values as shown below. + This configuration will fetch a class reference of the + `AuthenticationService` class and + store the reference in a variable called `authServiceClass`. This reference will + be used to fetch an instance of this class from IDP in the subsequent steps. - _Click `Call` block and then click :material-pencil: to open the configuration screen._ + `Call type`: `Call static method` - _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`. + `class name`: `io.jans.as.server.service.AuthenticationService` + + `method name`: `class` + + `assign result to`: `authServiceClass` + + ![](../../../assets/image-agama-lab-edit-authn-instance.png) + +3. Create `Get instance reference` Call block + + In this step, we will fetch the instance reference of the `AuthenticationService` + using the class reference that we obtained in the previous step. To fetch this + instance reference from the IDP, we will use `CdiUtil` class's `bean` method and + pass the class reference of the `AuthenticationService` + as an input to it. Use the steps and configuration below to do this. + + After the `Get class reference` node, create a new `Call` node. - ![](../../../assets/agama-lab-flow-passwd-edit-call.png) + Click on the newly created `Call` block and by clicking :material-pencil: open the configuration page. + Input values as shown below in the configuration screen. -3. Create _CdiUtil_ Call block + `Call type`: `Call static method` - 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. + `class name`: `io.jans.service.cdi.util.CdiUtil` - _Click the `New Authentication Service` block and then click on :material-plus-circle:. Then click `Call`_ + `method name`: `bean` - ![](../../../assets/agama-lab-flow-passwd-create-cdiutil.png) + `arguments`: `authServiceClass` - _Click on the newly created `Call` block and by clicking :material-pencil: open the configuration page. - Input values as shown below in the configuration screen_ + `assign result to`: `authService` - ![](../../../assets/agama-lab-flow-passwd-edit-cdiutil.png) + ![](../../../assets/agamalab-flow-passwd-editcdiutil.png) -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. +4. Create `result object` Assignment block - _Click on `New CdiUtil Object` and then click :material-plus-circle:. Select `Assignment(s)`_ + Next, we need to create an empty variable to store authentication results + when we validate the credentials in subsequent steps. - ![](../../../assets/agama-lab-flow-passwd-create-assignment.png) + Create a `Assignment` block after the `Get instance reference` call block and configure it as shown below. - _Click on the newly created `Assign` block. Click :material-pencil:. - Input values as shown below in the configuration screen_ + `Resultant variable`: `authResult` - ![](../../../assets/agama-lab-flow-passwd-edit-assignment.png) + ![](../../../assets/agamalab-flow-passwd-edit-assignment.png) -5. Create [repeat]() block +5. Create Repeat block `Repeat` block represents the [Repeat](../../../agama/language-reference.md#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. + + Create a Repeat block after the `Create result object` block - _Click on the `Result Object` block and then click :material-plus-circle:. Select `Repeat`._ - - ![](../../../assets/agama-lab-flow-passwd-create-repeat.png) + ![](../../../assets/agama-create-repeat.png) _Click on the newly created `Repeat` block. Click :material-pencil:. Input values as shown below in the configuration screen_ - ![](../../../assets/agama-lab-flow-passwd-edit-repeat.png) + ![](../../../assets/agamalab-flow-passwd-edit-repeat.png) -6. Create An RRF block +6. Create a `Show login form` RRF block `RRF` block represents the [RRF](../../../agama/language-reference.md#rrf) - instruction of Agama DSL. + instruction of Agama DSL. We will present the login form to the user using + this node. - _Click on the `Repeat` block. Click :material-plus-circle:. Check the `In Repeat Block` and then click on `RRF`._ + Create an RRF block after the `Retry Authentication` block. + + Remember that + the `Retry Authentication` is a `Repeat` type of block. It has two possible + paths. + + - One that originates from the colored dot on the bottom edge will be + labeled as `repeat`. Execution of the blocks along this path will be + repeated as configured in the `Repeat` block. + - Second path originates from the colored dot on the right edge of the + `Repeat` block. This path is labeled as `Continue`. These blocks will be + executed after `repeat` path completes the execution. - ![](../../../assets/agama-lab-flow-passwd-check-repeat.png) + The new `RRF` block should be created on the `Repeat` path. - _Click on the newly created `Repeat` block. Click :material-pencil:. Input values as shown below in the configuration - screen_ + ![](../../../assets/check-repeat.png) - ![](../../../assets/agama-lab-flow-passwd-edit-rrf.png) + Click on the newly created `RRF` block. Click :material-pencil:. 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. + `Template path`: `login.ftlh` - _At this stage, let's save the flow. Click `Save` on the flow canvas._ + `Data variable to inject`: `authResult` -7. Create a _CdiUtil_ Call block + `Assign result to`: `creds` - 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. + ![](../../../assets/agamalab-flow-passwd-edit-rrf.png) + + + With this configuration, the RRF block will - _Click on the `RRF` block. Click :material-plus-circle:. Click on `Call`._ + - Present an input form to the user. We will build the `login.ftlh` in a [later section](#design-user-interface) + - Capture and store user inputs like the user-name and password into the + `creds` variable - ![](../../../assets/agama-lab-flow-passwd-create-cdiutil-instance.png) + At this stage, let's save the flow using the `Save` button. This creates a new + commit in your GitHub repository. - _Click on the newly created `Call` block. Click :material-pencil:. Input values as shown below in the configuration - screen_ +7. Create `validate credentials` call block - ![](../../../assets/agama-lab-flow-passwd-edit-cdiutil-instance.png) + Create a `Call` block to process the username and password received from the user (in RRF) and + validate them. The result of the validation is stored in a variable. + + Create a new call block after the `Show login page` block. -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. + ![](../../../assets/agama-lab-create-cdiutil-instance.png) - _Click on the `Call` block. Click :material-plus-circle:. Click on `Assignment(s)`._ + Click on the newly created `Call` block. Click :material-pencil:. + Configure it as shown below. - ![](../../../assets/agama-lab-flow-passwd-create-assignment-uid.png) + `Call type`: `Call method on instance` - _Click on the newly created `Call` block. Click :material-pencil:. - Input values as shown below in the configuration screen_ + `Variable name`: `authService` - ![](../../../assets/agama-lab-flow-passwd-edit-assignment-uid.png) + `Method name`: `authenticate` -9. Create A Conditional When block + `Arguments`: `creds.username` and `creds.password` + + `Assign result to`: `authResult.success` + + ![](../../../assets/agamalab-flow-passwd-edit-cdiUtil-instance.png) + +8. Create a conditional When block `When` block represents the [When](../../../agama/language-reference.md#conditionals-and-branching) - instruction - of Agama DSL. + 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. + Create a conditional check using the `When` block to check if the + user credentials were successfully validated. - _Click on `Assignment(s)` block. Click :material-plus-circle:. Click on `When`._ + Create a new `When` block after the `Validate credentials` block. - ![](../../../assets/agama-lab-flow-passwd-create-when.png) + ![](../../../assets/agama-lab-flow-password-create-when.png) _Click on the newly created `When` block. Click :material-pencil:. Input values as shown below in the configuration screen_ - ![](../../../assets/agama-lab-flow-passwd-edit-when.png) + ![](../../../assets/agama-lab-flow-password-edit-when.png) -10. Create [finish]() blocks +9. Create Finish blocks The `Finish` block represents the [Flow finish](../../../agama/language-reference.md#flow-finish) instruction of Agama DSL. + We will need to create two finish blocks. + + - One finish block to terminate the flow when the authentication is successful. + - Second finish block to terminate the flow when the authentication is still not successful after 3 repeated attempts. + 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 + username. This will be achieved by adding a Finish block to the `Condition met` branch of 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 :material-plus-circle:. Click on `Condition met` and then click - `Finish`_ + Drag and drop the colored dot on the lower vertex of the `When` block to create + a `Condition met` branch. Create a `Finish` block on this branch. - ![](../../../assets/agama-lab-flow-passwd-create-finish.png) + ![](../../../assets/agamalab-flow-passwd-create-finish.png) _Click on the newly created `Finish` block. Click :material-pencil:. Input values as shown below in the configuration screen_ ![](../../../assets/agama-lab-flow-passwd-edit-finish.png) + + Let's create a second finish block that will terminate the flow when all 3 + authentication attempts have failed. + + Create a `Finish` block on the `Continue` branch of the `Repeat` block. - _Click on the `Repeat` block. Click :material-plus-circle:. Click `Finish`_ - - ![](../../../assets/agama-lab-flow-passwd-create-fail-finish.png) + ![](../../../assets/agamalab-flow-passwd-create-fail-finish.png) _Click on the newly created `Finish` block. Click :material-pencil:. Input values as shown below in the configuration screen and click `Save`._ - ![](../../../assets/agama-lab-flow-passwd-edit-fail-finish.png) + ![](../../../assets/agamalab-flow-passwd-edit-fail-finish.png) Save the flow using the `Save` button on flow canvas. The completed flow looks like below: - ![](../../../assets/agama-lab-flow-passwd-complete-flow.png) + ![](../../../assets/image-agama-lab-flow-quick-start-guide.png) -11. Check Generated code +10. Check generated code - Agama Lab flow gets translated in [Agama DSL](../../../agama/language-reference.md). Click the `Code` button to see the code - generated by the flow. + The flow is translated into [Agama DSL](../../../agama/language-reference.md). Click the `Code` button to see the + generated code. - ``` - Flow co.acme.password + ``` + Flow co.acme.password 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 - ``` - -### Design User Interface + // Get authentication service class reference from the IDP + authServiceClass = Call io.jans.as.server.service.AuthenticationService#class + // Get authentication service instance reference from the IDP + authService = Call io.jans.service.cdi.util.CdiUtil#bean authServiceClass + // Create empty object to store the authentication result + authResult = {} + // Retry 3 times to get the correct username and password + Repeat 3 times max + // Load login page for username and password input + creds = RRF "login.ftlh" authResult + // Validate username and password with IDP + authResult.success = Call authService authenticate creds.username creds.password + // Check if the authentication was successful + When authResult.success is true + // Authentication successful. Return the username. + Finish creds.username + // Max number of failed authentication attempts reached. return error and end the flow + it_yrwmc = {success:false, error: "Maximum authentication attempts reached. Authentication failed."} + Finish it_yrwmc + ``` + +### 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. +We need to add `login.ftlh` to the Agama project so that the flow can use it during the execution. Use the steps below to create the page. 1. Create a template file @@ -285,15 +378,16 @@ Use the steps below to create the page. _Select `+ Create` under the `New Blank Template`_ - ![](../../../assets/agama-lab-flow-passwd-select-template.png) + ![](../../../assets/agamalab-flow-passwd-select-template.png) _Give `Name` and `Description` as shown below and click `Create`_ - ![](../../../assets/agama-lab-flow-passwd-edit-template.png) + ![](../../../assets/agamalab-flow-passwd-edit-template.png) -3. Use the visual editor +2. Use the visual editor - This opens a visual editor to create a freemarker template. Use this visual editor to create a template + This opens a visual editor to create an Apache FreeMarker template. + Use this visual editor to create a template as per the need. For this article, we will use the code below. ![](../../../assets/agama-lab-flow-passwd-edit-template-2.png) @@ -301,68 +395,87 @@ Use the steps below to create the page. _Click `Edit HTML`. This opens a text editor. Remove existing code in the editor and paste the code shown below._ ```html - - -
-${msgs["login.errorMessage"]}
- [/#if] - -Enter your Username and Password +
+