Welcome to the https://github.com/GluuFederation/agama-OATH-TOTP project. This project is governed by Gluu and published under an Apache 2.0 license.
Use this project to add user authentication with TOTP(Time-based One-time Passwords) 2-factor authentication.
IDP | Description |
---|---|
Jans Auth Server | Deployment instructions |
Gluu Flex | Deployment instructions |
The project consists of four flows that provide incremental functionality:
Qualified Name | Description |
---|---|
org.gluu.agama.totp.main |
This is the main flow which you can directly launch from the browser. It first proceeds for user authn by triggering org.gluu.agama.totp.pw flow. Then helps to check user is already enrolled for TOTP 2FA or not. If a new user then trigger org.gluu.agama.enroll otherwise org.gluu.agama.otp and validate TOTP. |
org.gluu.agama.totp.pw |
This flow is used for user authn. It first asks the user to enter a username, and password, and validate the user. |
org.gluu.agama.enroll |
This flow is used to enroll new users into TOTP 2FA. It provides an enrollment page with a QR-Code. Users need to scan the QR-Code in any Authenticator App and enter OTP. At the end, it returns a validation response. |
org.gluu.agama.otp |
This flow is used to validate OTP. If the user is already enrolled in TOTP 2FA then it provides an OTP page and asks the user to enter an OTP and return a validation response. |
Configuration parameters for org.gluu.agama.totp.main
flow:
Name | Description | Notes |
---|---|---|
issuer |
Issuer of the OTP service | Keep it simple and little e.g. gluu.org |
qrCodeLabel |
This config is used to add your brand name into the center of QR Code | Keep it simple and little |
qrCodeKeyLength |
Key length to generate Secret Key | Default is 20 |
qrCodeAlg |
Algorithm used to validate TOTP | Default is sha1 |
{
"org.gluu.agama.totp.main": {
"issuer": "your-host-or-title",
"qrCodeLabel": "Gluu",
"qrCodeAlg": "sha1",
"qrCodeKeyLength": 20
}
}
When the main flow of this project is launched (namely, org.gluu.agama.totp.main
) it shows the login page. The user enters a username and password. After the user authn, the OTP enrollmen page opens for new user and if a user is already enrolled then it will directly ask for OTP.
sequenceDiagram
title Agama TOTP Project Flow
participant browser as Browser
participant rp as RP
participant jans as Jans Authz Server
autonumber
browser->>rp: Request page
rp->>jans: Invoke /authorize endpoint
loop n times - (multistep authentication)
jans->>browser: Present Login screen
browser->>jans: Present Login credentials
end
jans->>jans: Authenticate user
opt if new user
jans->>browser: Present OTP enrollment page with QR-Code
browser->>browser: Scan QR-Code in OTP Auth App
browser->>jans: Enter OTP
jans->>jans: Validate OTP and save secrey key to user
end
opt if enrolled user
jans->>browser: Present OTP page to enter OTP
browser->>jans: enter OTP
jans->>jans: Validate OTP
end
jans->>jans: Create internal Jans session
jans->>rp: Redirect with Success response
rp->>rp: Validate response
rp->>browser: Page is accessed
Check out this video of the org.gluu.agama.totp.main
flow.
Kiran Mali |
This project is licensed under the Apache 2.0