fix: SG endpoint moved inside the fido2 server (#4321)

JanssenProject · Mar 27, 2023 · dacb0fa · dacb0fa
1 parent bc0da49
commit dacb0fa
Show file tree

Hide file tree

Showing 3 changed files with 85 additions and 58 deletions.
diff --git a/docs/assets/SG_registration.png b/docs/assets/SG_registration.png
diff --git a/docs/assets/jans-tui-super-gluu-conf.png b/docs/assets/jans-tui-super-gluu-conf.png
diff --git a/...cript-catalog/person_authentication/super-gluu-external-authenticator/README.md b/...cript-catalog/person_authentication/super-gluu-external-authenticator/README.md
@@ -1,33 +1,50 @@
 
-[Super Gluu](supergluu.md) is a push-notification two-factor authentication (2FA) mobile app built to work with the Janssen Server. 
+[Super Gluu](supergluu.md) is Janssen's own push-notification two-factor authentication (2FA) mobile app built to work with the Janssen Server.
+Super Gluu uses public-key encryption as specified in the [FIDO U2F authentication standard](https://fidoalliance.org/specifications/overview/). Upon device enrollment, Super Gluu registers its public key against the Janssen's FIDO Server's `super_gluu_registration_endpoint` endpoint. Authentication takes place at `super_gluu_authentication_endpoint` where a challenge response ensures that the device has the corresponding private key.
 
-### Janssen Server's FIDO U2F endpoint
-Super Gluu uses public-key encryption as specified in the [FIDO U2F authentication standard](https://fidoalliance.org/specifications/overview/). Upon device enrollment, Super Gluu registers its public key against the Janssen Server's FIDO U2F endpoint. When authentication happens, there is a challenge response to ensure that the device has the corresponding private key. 
+### Janssen's Super Gluu endpoint
 
-The URI to invoke registeration and authentication of Super Gluu credentials in the Janssen Auth Server can be found at `https://<my.jans.server>/.well-known/fido-configuration`
+The fido2 server serves the registration and authentication of Super Gluu credentials, the URI of which can be found at `https://<my.jans.server>/.well-known/fido2-configuration`. However, **this feature has to be enabled** first, else the endpoints `super_gluu_registration_endpoint` and `super_gluu_authentication_endpoint` will not show up by default.
 
-### User and Developer Guides
-User and Developer Guides can be found on the [Super Gluu docs site](https://gluu.org/docs/supergluu). 
+### Prerequisites:
+
+#### A. Install the FIDO2 server:
+Ensure that the Fido2 server is installed during the initial server setup.
+
+#### B. Enable the Super Gluu endpoint:
 
-### Prerequisites 
-- An Internet accessible (non-internal or localhost) Janssen Server with DNS pointing at the public Internet address of the server 
+1. Use the TUI to enable "Super Gluu" feature
+![sg diagram](../../../assets/jans-tui-super-gluu-conf.png)
 
-- [Super Gluu interception script](https://github.com/JanssenProject/jans/blob/vreplace-janssen-version/docs/script-catalog/person_authentication/super-gluu-external-authenticator/SuperGluuExternalAuthenticator.py) (included in the default Janssen Server distribution)
+#### C. Mobile device with Super Gluu installed
+   - [Super Gluu for iOS](https://itunes.apple.com/us/app/super-gluu/id1093479646?mt=8)     
+   - [Super Gluu for Android](https://play.google.com/store/apps/details?id=gluu.org.super.gluu)   
 
-- An Android or iOS device with Super Gluu installed 
-    - [Super Gluu for iOS](https://itunes.apple.com/us/app/super-gluu/id1093479646?mt=8)     
-    - [Super Gluu for Android](https://play.google.com/store/apps/details?id=gluu.org.super.gluu)   
+#### D. Publicly Discoverable DNS :
+- An Internet accessible (non-internal or localhost) Janssen Server with DNS pointing at the public Internet address of the server
 
 - If the Jannsen Server is using a self-signed certificate, `Trust All` **must** be enabled in Super Gluu (open the app, navigate to `Menu` > `Trust all (SSL)` and enable)
 
 !!! Note
-    The Janssen Server and Super Gluu can work in the same network, without a DNS server hostname and with a self-signed certificate. There is only one limitation: both components should belong to the same network. Instead of assigning a hostname during Janssen Server installation, an IP address can be specified. In the Super Gluu mobile app, enable `Trust all (SSL)`.    
+    The Janssen Server and Super Gluu can work in the same network, without a DNS server hostname and with a self-signed certificate. There is only one limitation: both components should belong to the same network. Instead of assigning a hostname during Janssen Server installation, an IP address can be specified. In the Super Gluu mobile app, enable `Trust all (SSL)`.
+
+#### E. Push Notification server:
+
+
+### User and Developer Guides
+User and Developer Guides can be found on the [Super Gluu docs site](https://gluu.org/docs/supergluu).
+
+### Interception script
+- [Super Gluu interception script](../SuperGluuExternalAuthenticator.py) is included in the default Janssen Server distribution
+
+The Super Gluu Interception script can be configured to work in 2 modes:
+A. Two step Flow (Default mode)
+B. One step Flow
 
-### Authentication Workflows
-The authentication workflow for Super Gluu is defined in the [Super Gluu interception script](https://github.com/JanssenProject/jans/blob/vreplace-janssen-version/docs/script-catalog/person_authentication/super-gluu-external-authenticator/SuperGluuExternalAuthenticator.py) (included in the default Janssen Server distribution). 
-### A. Default Two step flow:
+
+### A. Two step flow (Default mode):
 #### Enrollment:
-By default, users are put through a two-step, two-factor authentication process with username and password first, and then push notification via Super Gluu second. 
+By default, users are put through a two-step, two-factor authentication process with username and password in the first step, and then push notification via Super Gluu in the second step.
 ```mermaid
 sequenceDiagram
 title SuperGluu Flow Enrollment "Two step"
@@ -49,15 +66,15 @@ Jans AS->>Jans AS: Enrollment entry stored in Database
 Jans AS->>Browser: Enrollment completed.
 
 ```
-##### A. Client data 
+##### A. Client data
 An example of the contents of client data are as follows:
 ```
 {
   "typ": "navigator.id.finishEnrollment",
   "challenge": "Bkpin2iUSEQrkuSC_wDlPwzLfVwRGxLbySpVm8jwkuk",
   "origin": "https://my.jans.server"
 }
-``` 
+```
 
 ##### B. Device data  
 An example of the contents of client data are as follows:
@@ -74,11 +91,32 @@ An example of the contents of client data are as follows:
   "push_token": "8fc4bd31e2ddbc5c5d83e4955cfd36f663ab37b426d0a4ec5c685c3a6335dd2c"
 }
 ```
-The push_token is used by the Notification server.
+The push_token is used by the **Push Notification server**.
 
-##### C. Device data
+##### C. Registration data
 This data contains following information: counter, status, rp-application, userInum, keyHandle, Public Key, attestation certificates
-
+```
+{
+  "createdDate": 1678374227774,
+  "updatedDate": 1678374228300,
+  "createdBy": "johndoe",
+  "updatedBy": "johndoe",
+  "username": "johndoe",
+  "domain": "/my.jans.server",
+  "userId": "DAY7UJzdHaIXuEbQlNwBomQEPmqjsKbN4lblYqfbCZo",
+  "challenge": "jr2LtLFRF2YG65pyo__gaKoiyP9oQbPyW6hGxdZBAS8",
+  "attenstationRequest": "{\"super_gluu_request\":true,\"super_gluu_request_mode\":\"two_step\",\"super_gluu_app_id\":\"https:///my.jans.server/.well-known/openid-configuration\",\"username\":\"madhu1\",\"displayName\":\"madhu1\",\"session_id\":\"3d3f7560-8d83-4770-a6fb-cc83c787a511\",\"attestation\":\"direct\"}",
+  "attenstationResponse": "{\"super_gluu_request\":true,\"super_gluu_request_mode\":\"two_step\",\"type\":\"public-key\",\"response\":{\"deviceData\":\"eyJuYW1lIjoiTmV4dXMgN......lLWU2ZjMtMzRlNC1hYWMxLTlhYTViOGI3MTUyOCJ9\",\"clientDataJSON\":\"eyJjaGFsbGVuZ2UiOiJqcjJM....QuZmluaXNoRW5yb2xsbWVudCJ9\",\"super_gluu_request_cancel\":false,\"attestationObject\":\"v2NmbXRzZmlkby11MmYtc3VwZXItZ2x1....gC5NYTNE-GAS3AUoD-DI9R__8\"},\"id\":\"-G1Bpm_7j0A2UIciKSPz7ku7pA2d9azzJyFQCd4Xh67Hh0gBDXAH9B--IX3hZYxtGEmY7nM01PV5Gq53O5FSsg\"}",
+  "uncompressedECPoint": "v2ExAmEzJmItMQFiLTJYINmwCcnnXf6CxMCOG6bjAT5aXHCqIhgYDrBvEuKW6bWuYi0zWCARbzLZN8ytE1JiVAs0UMLoAuTWEzRPhgEtwFKA_gyPUf8",
+  "publicKeyId": "-G1Bpm_7j0A2UIciKSPz7ku7pA2d9azzJyFQCd4Xh67Hh0gBDXAH9B--IX3hZYxtGEmY7nM01PV5Gq53O5FSsg",
+  "type": "public-key",
+  "status": "registered",
+  "counter": 0,
+  "attestationType": "fido-u2f-super-gluu",
+  "signatureAlgorithm": -7,
+  "applicationId": "https:///my.jans.server/.well-known/openid-configuration"
+}
+```
 #### Authentication:
 ```mermaid
 sequenceDiagram
@@ -92,11 +130,11 @@ Notification server->>Mobile App: Sends push to mobile device
 Jans AS->>Browser:  Present option of authenticating with QR code
 User->>Mobile App: Approve / Reject Push
 Mobile App->>Jans AS: Complete (finish) authentication process, send push_token for storing in Device entry of Gluu server
-Jans AS->Jans AS: validate response, If successful, update device entry, 
+Jans AS->Jans AS: validate response, If successful, update device entry,
 ```
 
 ### B. One step flow
-An alternative authentication workflow, password-less authentication, can be configured by adjusting the script property `authentication_mode`. 
+An alternative authentication workflow, password-less authentication, can be configured by adjusting the script property `authentication_mode`.
 
 ```mermaid
 sequenceDiagram
@@ -115,7 +153,7 @@ User->>Mobile App:  Scans the QR code
 Mobile App->> Mobile App: Enrollment saved on app \n ( appId, keyHandle, date)
 Mobile App->>Jans AS :  Enrollment completed, <br/>enrollment data (registrationData, clientData, deviceData ) sent to Jans AS
 Jans AS->>Jans AS: Enrollment entry stored temp entry in database under ou=registered_devices
-Jans AS->>Browser: Prompt user to login page, to attach the enrollment to a user
+Jans AS->>Browser: Prompt user to username-password page, inorder to link the enrollment to a user
 Browser->>Jans AS: send user creds
 Jans AS->>Jans AS: create enrollment entry attached to the user and delete temp entry under ou=registered_device
 Jans AS->>Browser: enrollment completed
@@ -134,38 +172,30 @@ participant Browser
 Browser->>Jans AS: /authorize request
 Jans AS->>Browser: Present QR code for scanning
 Mobile App->>Browser: Code is scanned
-User->>Mobile App: Approve / Reject 
-Mobile App->> Jans AS:Send authentication request 
+User->>Mobile App: Approve / Reject
+Mobile App->> Jans AS:Send authentication request
 Jans AS->> Jans AS: no username, search by keyhandle
 Jans AS->> Jans AS: verify Super Gluu credentials,  If successful, update device entry
 Jans AS->>Browser: Authentication completed
 ```
 
 ### Custom script Properties
-The Super Gluu authentication script has the following properties: 
+The Super Gluu authentication script has the following properties:
 
 |	Property	|	Description		|	Example	|
 |-----------------------|-------------------------------|---------------|
 |authentication_mode	|Determine factor of authentication - `two_step` or `one_step`|two_step |
 |credentials_file	|JSON file for SuperGluu 		|/etc/certs/super_gluu_creds.json|
-|label  |The name of the application |   Super Gluu| 
+|label  |The name of the application |   Super Gluu|
 |notification_service_mode   | Service used to enable push notifications | gluu|
 |qr_options| Size of the QR code that is used for enrollment and/or authentication|{ size: 500, mSize: 0.05 }|
-|registration_uri | Registration endpoint of the IDP| https://idp.example.com/identity/register| 
+|registration_uri | Registration endpoint of the IDP| https://idp.example.com/identity/register|
 |supergluu_android_download_url| Android app download link, used in the login page | https://play.google.com/store/apps/details?id=gluu.super.gluu|
 |supergluu_ios_download_url| iOS app download link, used in the login page | https://itunes.apple.com/us/app/super-gluu/id1093479646|
 
 
 ### Notes for administrator:
-#### A. Configure `/etc/certs/super_gluu_creds.json`:
-for each Android and apple app: 
-* a. GCM API key **OR**
-* b. SNS platform_arn **OR**
-* c. Access key / Secret key of oxNotify server (which hides the creds of GCM or SNS)
-
-#### B. Notification server: 
-Configure `accessKeyId` and `secretAccessKey` which allows access to SNS services / GCM services -  `/etc/gluu/conf/oxnotify-access.json`
-
+Configure `/etc/certs/super_gluu_creds.json`: For each Android and apple app, configure Access key / Secret key of oxNotify server
 
 ### Enable Sign-in with Super-Gluu Authentication script
 Using the OpenID Connect acr_values parameter, web and mobile clients can request any enabled authentication mechanism. To enable Super Gluu as an authentication method, follow the steps below:
@@ -195,7 +225,7 @@ Steps:
 /opt/jans/jans-cli/config-cli.py --operation-id put-acrs --data /tmp/sg-auth-default.json
 ```
 
-### Test the feature 
+### Test the feature
 To test, enter the complete URL for authorization in a browser or create a simple webpage with a link that simulates the user sign-in attempt. If the server is configured properly, the first page for the selected authentication method will be displayed to the user.
 
 An example of a complete URL looks like this -
@@ -207,26 +237,23 @@ https://<your.jans.server>/jans-auth/authorize.htm?response_type=code&redirect_u
 
 The Gluu Server includes a [default public-facing pages for Super Gluu ](https://github.com/JanssenProject/jans/blob/vreplace-janssen-version/jans-auth-server/server/src/main/webapp/auth/super-gluu/login.xhtml) for enrollment and authentication.
 
-To customize the look and feel of the pages, follow the [customization guide](https://github.com/JanssenProject/jans/blob/vreplace-janssen-version/docs/admin/developer/customization/customize-web-pages.md). 
- 
-### Self-service 
-To offer end-users a portal where they can manage their own account security preferences, including two-factor authentication credentials like Super Gluu, check out our new app, [Gluu Casa](https://casa.gluu.org). 
+To customize the look and feel of the pages, follow the [customization guide](https://github.com/JanssenProject/jans/blob/vreplace-janssen-version/docs/admin/developer/customization/customize-web-pages.md).
+
+### Self-service
+To offer end-users a portal where they can manage their own account security preferences, including two-factor authentication credentials like Super Gluu, check out our new app, [Gluu Casa](https://casa.gluu.org).
 
 ### Manual Device Management
-![image](https://user-images.githubusercontent.com/12072533/207616512-d4486a9d-f4cf-4d56-9256-d558e2ab567f.png)
-
-A user's Super Gluu device(s) can be removed by a Janssen administrator by directly locating the user entry in LDAP. For example, let's say user `abc` loses their device and wants to enroll a new device to use Super Gluu. 
-
-1. Find the `DN` of the user in LDAP 
-
-1. Find the `jansId DN` associated with the user
-
-1. Remove the `jansId DN` 
-
-Now the old device is gone and the user can enroll a new device 
-
-### Device management using SCIM
-See the [SCIM documentation](...) for a discussion on how to manage FIDO devices, including Super Gluu, using the SCIM protocol. 
+![image](../../../assets/SG_registration.png)
+
+A user's Super Gluu device(s) can be removed by a Janssen administrator by directly locating the user entry in LDAP. For example, let's say user `abc` loses their device and wants to enroll a new device to use Super Gluu.
 
+1. Find the `DN` of the user in LDAP
 
+1. Find the registation under `ou=fido2_register` for associated with the user
 
+1. Remove the `jansId DN`
+
+Now the old device is gone and the user can enroll a new device
+
+### Device management using SCIM
+See the [SCIM documentation](...) on how to manage Super Gluu devices, using the SCIM protocol.