README.md

About Agama-Hellō

This repo is home to the Gluu Agama-hello project. This Agama project provides integration with hello.coop platform, which supports a variety of authenticators and social sign-in options.

Where To Deploy

The project can be deployed to any IAM server that runs an implementation of the Agama Framework like Janssen Server and Gluu Flex.

How To Deploy

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-hello project can be deployed on the Janssen Server.

Deployment of an Agama project involves three steps.

• Downloading the .gama package from the project repository
• Adding the .gama package to the IAM server
• Configure the project

Pre-Requisites

• Agama-Hello project calls the flows from the agama-openid project. Hence a working deployment of agama-openid on the same IAM server is required. For instructions on how to deploy and configure the agama-openid project, please visit the README
• Credentials: You will need client credentials from Hellō SaaS to authenticate and authorize access to their platform.

Download The Project

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.

Add The Project To The Server

The Janssen Server provides multiple ways an Agama project can be deployed and configured. Either use the command-line tool, REST API, or a TUI (text-based UI). Refer to the Agama project configuration page in the Janssen Server documentation for more details.

Configure The Project

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-hello project. As shown, it contains configuration parameters for the flows contained in it:

Sample JSON:

{
  "org.gluu.hello.coop": {
    "hello": {
      "oauth": {
        "authzEndpoint": "https://wallet.hello.coop/authorize",
        "tokenEndpoint": "https://wallet.hello.coop/oauth/token",
        "userInfoEndpoint": "https://wallet.hello.coop/oauth/userinfo",
        "clientId": "CLIENT_INDENTIFIER",
        "clientSecret": "CLIENT_SECRET",
        "scopes": [
          "openid"
        ]
      },
      "uidPrefix": "hello-"
    }
  }
}

Test The Flow

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.hello.coop flow contained in the Agama-hello project, specify the ACR value as agama_<qualified-name-of-the-top-level-flow>, i.e agama_org.gluu.hello.coop.

Customize and Make It Your Own

Fork this repo to start customizing the Agama-hello project. It is possible to customize the user interface provided by the flow to suit your organisation'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.hello.coop flow from other Agama projects.

To make it easier to visualise and customize the Agama Project, use Agama Lab.

Flows In The Project

Qualified Name	Description
org.gluu.hello.coop	Main agama flow of this project. It first collects the configuration details and triggers to org.gluu.inbound.oauth2.AuthzCodeWithUserInfo flow of agama-openid project. After successful authentication, redirect to this main flow for the user onboard. Kindly check the diagram for better understanding.

Sequence Diagram

A basic diagram to understand how the agama-hello works.

sequenceDiagram
title Agama-hello Sequence Diagram
actor Person
participant Browser
participant Website
participant OP
participant agama-hello
participant agama-OpenID
participant hello

Person->>Browser: Login
Browser->>Website: Load
Website->>Browser: redirect to OP
Browser->>OP: authn request agama_flow=org.gluu.hello.coop
OP->>agama-hello: invoke
agama-hello->>agama-OpenID: Trigger: org.gluu.inbound.oauth2.AuthzCodeUserinfo
agama-OpenID->>Browser: redriect to hello
Browser->>hello: auth request
hello ->> hello: login happens
hello ->> OP: callback
OP ->> agama-OpenID: hello code
agama-OpenID ->> agama-hello: success
agama-hello ->> Website: OP code

Loading

Demo

Check out this video to see the agama-hello authentication flow in action. Also check the Agama Project Of The Week video series for a quick demo on this flow.

Note: While video shows how the flow works overall, it may be dated. Do check the Test The Flow section to understand the current method of passing the ACR parameter when invoking the flow.

Acknowledgements

This project is based on agama-openid.