Merge pull request #4 from GluuFederation/agama-lab-branch

feat: update readme with style guide
GluuFederation · Mar 29, 2024 · 81c70f1 · 81c70f1
2 parents 0b35098 + ad447ad
commit 81c70f1
Show file tree

Hide file tree

Showing 7 changed files with 52 additions and 112 deletions.
diff --git a/README.md b/README.md
@@ -1,134 +1,61 @@
-# Agama Passkey Project
-
 <!-- These are statistics for this repository-->
 [![Contributors][contributors-shield]][contributors-url]
 [![Forks][forks-shield]][forks-url]
 [![Stargazers][stars-shield]][stars-url]
 [![Issues][issues-shield]][issues-url]
 [![Apache License][license-shield]][license-url]
 
-Use this project to authenticate using security devices (Android Touch, iOS Face Id, Yubico Key, Windows Hello, Touch ID on Mac, etc.)
-
-## How it works at a glance
-
-When a main flow of this project is launched (namely `org.gluu.agama.passkey.main`) the user's browser is
-redirected to a view where he/she must first enter your username and password, then show a list of passkeys that you have
-registered, in case you do not have one you must register one, once you have registered your passkey you can complete
-the authentication step with passkey.
-But you can also log in from the initial screen without entering a credential.
+# Agama Passkey
 
-## Project Deployment
+Welcome to the https://github.com/GluuFederation/agama-passkey project. This project is governed by Gluu and published under an Apache 2.0 license.
 
-To deploy this project we need to meet the requirements.
+Use this project to add user authentication with **Passkey**(passwordless authentication that uses a device to verify a user's identity before allowing them to access an account) 2-factor authentication.
 
-### Requirements
+For more information you can also see
+* [Passkey](https://passkey.io)
+* [FIDO Specs](https://www.w3.org/TR/webauthn-1)
 
-1. Running instance of
-   - `Jans Auth Server`
-   - `Jans Fido2`
-   - `Jans Casa`
-   - `Jans Scim`
+## Requirements
 
-### Add Java dependencies
+* Register a client to integrate with SCIM (Used to list passkeys and edit), minimum scopes:
+  - https://jans.io/scim/fido2.read
+  - https://jans.io/scim/fido2.write
 
-1. cd /opt/jans/jetty/jans-auth/custom/libs
-2. wget https://github.com/GluuFederation/agama-passkey/releases/latest/download/agama-passkey-custom.jar
-3. If you are not using *.jar, update extractClasspath in /opt/jans/jetty/jans-auth/webapps/jans-auth.xml
-4. Restart server
+## Supported IDPs
 
-### Deployment
-
-Run these instructions on the server where you have `Janssen` or `Gluu` installed:
-
-- Download the
-  latest [agama-passkey.gama](https://github.com/GluuFederation/agama-passkey/releases/latest/download/agama-passkey.gama), you can use `wget`
-```shell
-wget https://github.com/GluuFederation/agama-passkey/releases/latest/download/agama-passkey.gama
-```
+| IDP              | Description                                                         |
+|:-----------------|:--------------------------------------------------------------------| 
+| Jans Auth Server | [Deployment instructions](https://docs.jans.io/head/admin/install/) | 
+| Gluu Flex        | [Deployment instructions](https://docs.jans.io/head/admin/install/) | 
 
-![TUI_AGAMA_DEPLOY](https://github.com/GluuFederation/agama-passkey/assets/86965029/1d6b8cab-ddad-451c-b620-d19be1b7f9e3)
+## Flows
 
-### Configure Jans Scim
+| Qualified Name                    | Description                                                                                                                                                                                                                                                                                                        |
+|-----------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 
+| `org.gluu.agama.passkey.main`     | This is the main flow which you can directly launch from the browser. If you have not configured a passkey, you must first log in with your credentials and register your passkey(s) `org.gluu.agama.passkey.list`. If you have at least 1 passkey configured, then you can click the "Login with passkey" button. | 
+| `org.gluu.agama.passkey.list`     | This flow is used to list the passkeys that the logged-in user has registered. If you do not have a passkey, an option to add a new passkey `org.gluu.agama.passkey.add` is enabled. If you already have at least one passkey, you can click `Login with passkey`.                                                 | 
+| `org.gluu.agama.passkey.add`      | This flow is used to register a new passkey. The user has to validate his FIDO device, which can be a (Yubico key, Device fingerprint, Windows Hello, Apple Face ID, etc.).                                                                                                                                        | 
+| `org.gluu.agama.passkey.nickname` | This flow is used to add a nickname to the newly registered passkey. Once completed this stream returns to the `org.gluu.agama.passkey.list`                                                                                                                                                                       |                                                                                                                                                                                                                                                                                                                    |
 
-- Once we have deployed the `agama project`, we need to configure the `jans scim` parameters, then we proceed to create
-  a new client `jans scim` with scope `https://jans.io/scim/fido2.read` and `https://jans.io/scim/fido2.write`.
+## Configuration
 
-You can create the client using the registration web service.
+| Flow                          | Property         | Value Description  |
+|-------------------------------|:-----------------|:-------------------|
+| `org.gluu.agama.passkey.main` | scimClientId     | SCIM Client id     |
+| `org.gluu.agama.passkey.main` | scimClientSecret | SCIM Client secret |
 
-**Request**
+Sample JSON:
 
-```
-curl --location 'https://<YOUR_DOMAIN>/jans-auth/restv1/register' \
---header 'Content-Type: application/json' \
---data '{
-  "client_name": "SCIM Agama Client",
-  "scope": [
-    "https://jans.io/scim/fido2.read",
-    "https://jans.io/scim/fido2.write"
-  ],
-  "grant_types": [
-    "client_credentials"
-  ],
-  "token_endpoint_auth_method": "client_secret_basic"
-}'
-```
-
-**Response**
-
-```
+``` json
 {
-  "allow_spontaneous_scopes": false,
-  "application_type": "web",
-  "rpt_as_jwt": false,
-  "registration_client_uri": "https://<YOUR_DOMAIN>/jans-auth/restv1/register?client_id=27975f1c-eee6-4bf8-b393-5fb47d44c566",
-  "tls_client_auth_subject_dn": "",
-  "run_introspection_script_before_jwt_creation": false,
-  "registration_access_token": "<YOUR_REGISTRATION_ACCESS_TOKEN>",
-  "client_id": "<YOUR_CLIENT_ID>",
-  "client_secret": "<YOUR_SECRET_KEY>",
-  "token_endpoint_auth_method": "client_secret_basic",
-  "scope": "https://jans.io/scim/fido2.read https://jans.io/scim/fido2.write",
-  "client_id_issued_at": 1710469308,
-  "backchannel_logout_session_required": false,
-  "client_name": "Scim custom client",
-  "par_lifetime": 600,
-  "spontaneous_scopes": [],
-  "id_token_signed_response_alg": "RS256",
-  ...,
-  ...,
-  ...
+    "org.gluu.agama.passkey.main": {
+        "scimClientId": "PUT_YOUR_SCIM_CLIENT_ID_HERE",
+        "scimClientSecret": "PUT_YOUR_SCIM_CLIENT_SECRET"
+    }
 }
 ```
 
-- Now that we have the jans scim client, we proceed to configure this client using `TUI`.
-- We open `TUI` and we are located in agama, we select in the table where our application is deployed and press `c`, this
-  will open a configuration panel, where we must first hit `Export Sample Config` and save the file in some path.
-- Now we go to the exported file and edit it and enter the credentials
-
-
-```
-{
-  "org.gluu.agama.passkey.add": {},
-  "org.gluu.agama.passkey.nickname": {},
-  "org.gluu.agama.passkey.list": {},
-  "org.gluu.agama.passkey.main": {
-    "scimClientId": "YOUR_SCIM_CLIENT_ID",
-    "scimClientSecret": "YOUR_SCIM_CLIENT_SECRET"
-  }
-}
-```
-
-- We go back to the TUI and click on `Import Configuration` and select the modified configuration file with our parameters.
-- With this, our `agama project` is now configured and we can start testing.
-
-![TUI_SCIM_CONFIGURATION](https://github.com/GluuFederation/agama-passkey/assets/86965029/404b066e-a6f3-4c1e-9bf8-afe3f63121e7)
-
-## Testing
-
-You'll need an OpenID Connect test RP. You can try [oidcdebugger](https://oidcdebugger.com/),
-[jans-tarp](https://github.com/JanssenProject/jans/tree/main/demos/jans-tarp)
-or [jans-tent](https://github.com/JanssenProject/jans/tree/main/demos/jans-tent). Check out this video to see an example
-of **agama-passkey** in action:v
+## Demo
 
 ### Use case 1:
 

diff --git a/code/org.gluu.agama.passkey.main.flow b/code/org.gluu.agama.passkey.main.flow
@@ -30,6 +30,7 @@ Repeat 5 times max
                     Finish it_zoswe
      When mainForm.loginWithPasskeyBtn is ""
           // Generates an assertion request without username
+
           detestable = Call fidoValidator assertionRequest null
           // Starts the authentication process
           obj.showError = false

diff --git a/lib/org/gluu/agama/passkey/CasaWSBase.java b/lib/org/gluu/agama/passkey/CasaWSBase.java
@@ -7,7 +7,6 @@
 import io.jans.casa.model.ApplicationConfiguration;
 import io.jans.orm.PersistenceEntryManager;
 import io.jans.service.cdi.util.CdiUtil;
-import io.jans.util.NetworkUtils;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 

diff --git a/lib/org/gluu/agama/passkey/IdentityProcessor.java b/lib/org/gluu/agama/passkey/IdentityProcessor.java
@@ -9,13 +9,15 @@
 
 import java.util.Map;
 
-import static io.jans.inbound.Attrs.*;
-
 public class IdentityProcessor {
 
     private static final Logger log = LoggerFactory.getLogger(IdentityProcessor.class);
 
     private static final String INUM_ATTR = "inum";
+    private static final String UID = "uid";
+    private static final String GIVEN_NAME = "givenName";
+    private static final String DISPLAY_NAME = "displayName";
+    private static final String MAIL = "mail";
 
     public static Map<String, String> accountFromUid(String uid) throws InvalidClaimException {
         User user = getUser(UID, uid);

diff --git a/lib/org/gluu/agama/passkey/NetworkUtils.java b/lib/org/gluu/agama/passkey/NetworkUtils.java
@@ -0,0 +1,12 @@
+package org.gluu.agama.passkey;
+
+import io.jans.service.cdi.util.CdiUtil;
+import jakarta.servlet.http.HttpServletRequest;
+
+public class NetworkUtils {
+
+    public static String urlBeforeContextPath() {
+        HttpServletRequest req = CdiUtil.bean(HttpServletRequest.class);
+        return req.getScheme() + "://" + req.getServerName();
+    }
+}
diff --git a/lib/org/gluu/agama/passkey/ScimWSBase.java b/lib/org/gluu/agama/passkey/ScimWSBase.java
@@ -3,7 +3,6 @@
 import com.nimbusds.oauth2.sdk.ParseException;
 import com.nimbusds.oauth2.sdk.http.HTTPRequest;
 import com.nimbusds.oauth2.sdk.http.HTTPResponse;
-import io.jans.util.NetworkUtils;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 

diff --git a/lib/org/gluu/agama/passkey/authn/FidoValidator.java b/lib/org/gluu/agama/passkey/authn/FidoValidator.java
@@ -2,9 +2,9 @@
 
 import io.jans.fido2.client.AssertionService;
 import io.jans.fido2.client.Fido2ClientFactory;
-import io.jans.util.NetworkUtils;
 import jakarta.ws.rs.core.Response;
 import net.minidev.json.JSONObject;
+import org.gluu.agama.passkey.NetworkUtils;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;