Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 1 commit into from
Mar 27, 2023
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/assets/SG_registration.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/jans-tui-super-gluu-conf.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
143 changes: 85 additions & 58 deletions ...cript-catalog/person_authentication/super-gluu-external-authenticator/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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 -
Expand All @@ -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.