{"id":22781984,"url":"https://github.com/gluufederation/agama-typekey","last_synced_at":"2025-08-15T22:38:48.061Z","repository":{"id":218960395,"uuid":"731771510","full_name":"GluuFederation/agama-typekey","owner":"GluuFederation","description":"Agama Project to authenticate people using typing keyboard dynamics","archived":false,"fork":false,"pushed_at":"2024-11-29T16:19:44.000Z","size":111,"stargazers_count":1,"open_issues_count":0,"forks_count":3,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-04-15T16:34:15.880Z","etag":null,"topics":["jans","security","typekey"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GluuFederation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-12-14T20:58:03.000Z","updated_at":"2024-11-18T15:02:03.000Z","dependencies_parsed_at":"2024-09-18T09:02:09.306Z","dependency_job_id":"9bf6f0f2-06b9-4939-aae2-f858140a2c92","html_url":"https://github.com/GluuFederation/agama-typekey","commit_stats":null,"previous_names":["gluufederation/agama-typekey"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/GluuFederation/agama-typekey","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GluuFederation%2Fagama-typekey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GluuFederation%2Fagama-typekey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GluuFederation%2Fagama-typekey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GluuFederation%2Fagama-typekey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GluuFederation","download_url":"https://codeload.github.com/GluuFederation/agama-typekey/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GluuFederation%2Fagama-typekey/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270639257,"owners_count":24620695,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jans","security","typekey"],"created_at":"2024-12-11T21:09:13.117Z","updated_at":"2025-08-15T22:38:48.040Z","avatar_url":"https://github.com/GluuFederation.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agama Typekey\n\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![Apache License][license-shield]][license-url]\n\n## About Agama-typekey\n\nThis repo is home to the Gluu Agama-typekey project. This project allows you to\nRecord behavioral keystroke data and use it as a second factor of authentication\nby leveraging the Typekey API.\n\n\n\n\n## Where To Deploy\n\nThe project can be deployed to any IAM server that runs an implementation of \nthe [Agama Framework](https://docs.jans.io/head/agama/introduction/) like \n[Janssen Server](https://jans.io) and [Gluu Flex](https://gluu.org/flex/).\n\n\n## How To Deploy\n\nDifferent IAM servers may provide different methods and \nuser interfaces from where an Agama project can be deployed on that server. \nThe steps below show how the Agama-typekey project can be deployed on the \n[Janssen Server](https://jans.io). \n\nDeployment of an Agama project involves three steps.\n\n- [Downloading the `.gama` package from the project repository](#download-the-project)\n- [Adding the `.gama` package to the IAM server](#add-the-project-to-the-server)\n- [Configure the project](#configure-the-project)\n\n\n#### Pre-Requisites\n\n* SCAN subscription: Visit [Agama Lab](https://gluu.org/agama-lab) \nand sign up for a free SCAN subscription, which gives you 500 credits. \nEach successful Typekey API call costs 4 credits.ts. \n\n\n##### Software Statement Assertion\n\nIn order to call the Typekey API, you will need an OAuth client. Once you have \na SCAN subscription on Agama Lab, navigate to `Market` \u003e `SCAN` and create an \nSSA with the software claim `typekey`. The Typekey flow will register its own \nclient via DCR with the SSA you provide in the configuration. \n\n\n### Download the Project\n\n\u003e [!TIP]\n\u003e Skip this step if you use the Janssen Server TUI tool to \n\u003e configure this project. The TUI tool enables the download and adding of this \n\u003e project directly from the tool, as part of the `community projects` listing. \n\nThe project is bundled as \n[.gama package](https://docs.jans.io/head/agama/gama-format/). \nVisit the `Assets` section of the \n[Releases](https://github.com/GluuFederation/agama-typekey/releases) to download \nthe `.gama` package.\n\n### Add The Project To The Server\n\nThe Janssen Server provides multiple ways an Agama project can be \ndeployed and configured. Either use the command-line tool, REST API, or a \nTUI (text-based UI). Refer to \n[Agama project configuration page](https://docs.jans.io/head/admin/config-guide/auth-server-config/agama-project-configuration/) in the Janssen Server documentation for more details.\n\n### Configure The Project\n\nThe Agama project accepts configuration parameters in the JSON format. Every Agama \nproject comes with a basic sample configuration file for reference.\n\nBelow is a typical configuration of the Agama-typekey project. As shown, it contains\nconfiguration parameters for the [flows contained in it](#flows-in-the-project):\n\n```json\n{\n    \"org.gluu.agama.typekey\": {\n      \"keystoreName\": \"\",\n      \"keystorePassword\": \"\", \n      \"orgId\": \"\",\n      \"scan_ssa\": \"\",\n      \"authHost\": \"https://account.gluu.org\",\n      \"scanHost\": \"https://cloud.gluu.org\",\n      \"phrases\": {\n        \"1\": \"itwasthebestoftimes\",\n        \"2\": \"itwastheworstoftimes\"\n      }\n    }\n}\n```\nCheck the flow detail section for details about configuration parameters.\n\n\n### Test The Flow\n\nUse any relying party implementation (like [jans-tarp](https://github.com/JanssenProject/jans/tree/main/demos/jans-tarp)) \nto send an authentication request that triggers the flow.\n\nFrom the incoming authentication request, the Janssen Server reads the `ACR` \nparameter value to identify which authentication method should be used. \nTo invoke the `org.gluu.agama.typekey` flow contained in the Agama-typekey project, \nspecify the ACR value as `agama_\u003cqualified-name-of-the-top-level-flow\u003e`, \ni.e `agama_org.gluu.agama.typekey`.\n\n\n## Customize and Make It Your Own\n\nFork this repo to start customizing the Agama-PW project. It is possible to \ncustomize the user interface provided by the flow to suit your organization's \nbranding \nguidelines. Or customize the overall flow behavior. Follow the best \npractices and steps listed \n[here](https://docs.jans.io/head/admin/developer/agama/agama-best-practices/#project-reuse-and-customizations) \nto achieve these customizations in the best possible way.\nThis project can be reused in other Agama projects to create more complex\nauthentication journeys. To re-use, trigger the [org.gluu.agama.typekey](#orggluuagamatypekey) \nflow from other Agama projects.\n\nTo make it easier to visualize and customize the Agama Project, use \n[Agama Lab](https://cloud.gluu.org/agama-lab/login).\n\n\n## Flows In The Project\n\nList of the flows: \n\n- [org.gluu.agama.typekey](#orggluuagamatypekey)\n\n\n### org.gluu.agama.typekey\n\nThe first time a user starts the Typekey flow, Typekey will choose a random \nphrase from the `phrases` dict in the configuration and store it in persistence. \nThen, the Typekey API is called to provide the keystroke data recorded during \nthe flow. The first 5 times, the Typekey API will train on the data provided. \nThis phase is called \"Enrollment\". On the 6th attempt onward, Typekey API will \nvalidate the provided keystroke data using the training data stored during \nenrollment. If the behavioral data is sufficiently different from the trained \ndata, Typekey API will deny the request.\n\nIn case the Typekey API denies the request, Agama Typekey falls back to password authentication, and retrains the API on the provided data.\n\n\n#### Parameter Details\n\n\n| Name | Description | Notes |\n| ----------------- | --------------------------------------------------------------------- | --------------------------------------- |\n| `keystoreName` | Optional name for the keystore if you want to include a signature when sending Typekey data. | Leave blank if not needed.|\n| `keystorePassword` | Optional password for the keystore for signature inclusion. | Leave blank if not needed.|\n| `orgId` | Organization ID obtained by decoding the software statement JWT.| Look for the org_id claim; use https://jwt.io to decode.|\n| `scan_ssa` | JWT string obtained from Agama Lab.| |\n| `authHost` | Host URL for authentication. | Can be left as is.|\n| `scanHost` | Host URL for scanning. | Can be left as is.|\n| `phrases` | Dictionary of strings for selecting phrases used in behavioral metrics. | Use format string:string with unique keys and values.|\n\n\n\n## Demo\n\n\nCheck out this video to see the **agama-typekey** authentication flow in action.\nAlso check the\n[Agama Project Of The Week](https://gluu.org/agama-project-of-the-week/) video\nseries for a quick demo on this flow.\n\n*Note:*\nWhile the video shows how the flow works overall, it may be dated. Do check the\n[Test the Flow](#test-the-flow) section to understand the current\nmethod of passing the ACR parameter when invoking the flow.\n\n### Enrollment\n\nhttps://github.com/SafinWasi/agama-typekey/assets/6601566/2256877b-3b49-48d8-b292-3d9da4a3a4c5\n\n\n\n### Typekey API approval\n\n\n\nhttps://github.com/SafinWasi/agama-typekey/assets/6601566/de5dcb19-9fbb-41f3-b897-606fc52fce85\n\n\n\n\n### Typekey API denied, fallback to password\n\n\nhttps://github.com/SafinWasi/agama-typekey/assets/6601566/b0288f5c-6a84-4ea0-b6a4-ac9052409189\n\n\n\n\u003c!-- This are stats url reference for this repository --\u003e\n\n[contributors-shield]: https://img.shields.io/github/contributors/GluuFederation/agama-typekey.svg?style=for-the-badge\n\n[contributors-url]: https://github.com/GluuFederation/agama-typekey/graphs/contributors\n\n[forks-shield]: https://img.shields.io/github/forks/GluuFederation/agama-typekey.svg?style=for-the-badge\n\n[forks-url]: https://github.com/GluuFederation/agama-typekey/network/members\n\n[stars-shield]: https://img.shields.io/github/stars/GluuFederation/agama-typekey?style=for-the-badge\n\n[stars-url]: https://github.com/GluuFederation/agama-typekey/stargazers\n\n[issues-shield]: https://img.shields.io/github/issues/GluuFederation/agama-typekey.svg?style=for-the-badge\n\n[issues-url]: https://github.com/GluuFederation/agama-typekey/issues\n\n[license-shield]: https://img.shields.io/github/license/GluuFederation/agama-typekey.svg?style=for-the-badge\n\n[license-url]: https://github.com/GluuFederation/agama-typekey/blob/main/LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgluufederation%2Fagama-typekey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgluufederation%2Fagama-typekey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgluufederation%2Fagama-typekey/lists"}