Ceptor Docs
There are many different ways of authenticating users using Ceptor, here is an example on how to do it by creating a small html/javascript application and hosting it in the Ceptor Gateway
This javascript application will be calling a REST API exposed in Ceptor, called CeptorAuthenticate - this API is provided with Ceptor in samples/ceptor_apis.zip.
You can find an example application in the /auth folder of your Ceptor distribution. This is very easy to modify and style according to your needs. It uses the modern Materialize Front-End javascript framework, available at https://materializecss.com/ - this is very lightweight and allows for easy customization.
This application supports signing up new users, authenticating them using OTP sent via SMS, TOTP Authenticator, or OTP sent via email.
Password reset using one of these MFA methods are also supported.
Sample screenshots
Below are sample screenshots:
Authentication page
2nd step, asking for TOTP (Google Authenticator, Microsoft Authenticator or equivalent) code.
Password reset.
Enter new password, after OTP has been verified.
Auth application
You can find a javascript application in the /auth folder of your Ceptor installation, it contains the following files:
index.html
css/checkforce-stylke.css
css/materialize.min.css
icon/favicon.png
js/ceptor.js
js/axios.min.js
js/checkforce.min.js
js/jquery-3.4.1.min.js
js/materialize.min.jss
Simply change the name in the call to "Ceptor.init('#main', 'Ceptor')" replacing it with your preferences to control the name on login screen.
All of the front-end logic is contained in the javascript file ceptor.js
From the html page, Ceptor.ini() is called first, then Ceptor.loginPage() which displays the input promting for userid and password.
You can add your own customizations here.
Ceptor Gateway Location
To serve the application to the clients, on /auth/* you need to create a new Location in the gateway, from which the static files in the applications are served to the user.
Create a location called "auth", and section the action to "serve".
Set conditions to match /auth/*
and create an URL rewrite rule, which rewrites /auth/(.*) to /$1 - effectively stripping the /auth/ prefix from the request.
Select the WebServer section, and point the webserver at ${ceptor.home}/auth where the html / javascript application is then served from.
Below is a location configuration which can be copied into the gateway configuration, with the configuration described above.
CeptorAuthenticate API
The CeptorAuthenticate API is called by JavaScript in the authentication application running in the browser.
The API offers these features:
- Authenticate users using Multi Factor Authentication (MFA)
- Create new users using self-service
- Password reset
OpenAPI Specification
Below is the OpenAPI specification for this API:
Implementation
This API is implemented as scripts within the gateway, below is example of the implementation for each operation in the API:
Note that this implementation uses some of the Authentication Plugins included with Ceptor - these plugins use Ceptors own Ceptor User Administration Server and UserAdmin API to store users. You should modify the implementation to suit your requirements and plugins, in case they differ.
You should remove any operations that offers functionality which you do not wish to expose to your clients - if you e.g. do not want to offer self-registration to clients, remove the part for the UI, and remove the relevant API offering this functionality.
GET /info
This operation returns information about the current session, for use by the application.
POST /auth/uidpw
This operation supports authenticating using userid and password. By default, it treats this as first step of a multifactor authentication, where the user must complete authentication using either OTP sent as SMS, OTP sent as Email, or a TOTP code using a previously registered Authenticator application.
If you remove this line:
context.agent.setStateVariable(pSessionId, "require_otp", "true", false);
then two-factor authentication will be disabled, and login will complete after the first userid/password login.
POST /auth/logoff
This operation simply logs off the user.
POST /auth/sendsms
This operation generates an OTP code and sends it using SMS/Text to the users mobile number.
POST /auth/sendemail
This operation generates an OTP and sends it using email to the users email address.
POST /auth/verifysmsotp
This operation is used for verifying an entered OTP value sent earlier using SMS/Text message.
POST /auth/verifytotp
This operation is used for verifying a TOTP code entered using a previously registered TOTP authenticator.
POST /auth/verifyemailotp
This operation is used for verifying an OTP code earlier sent as email.
POST /initiateresetpassword
This operation initiates a reset password flow - this uses an entered userid/email address, as well as an otptype specyfing if sms, totp or email shoudl be used.
It then compares them against known information, and sends out the OTP code if relevant using the chosen mechanism.
POST /resetpasswordotp
This operation is called after /initiateresetpassword with the entered OTP, to validate if it is correct.
POST /resetpassword
This operation is the last step of a password reset, after the OTP has been validated. It allows the user to choose a new password.
POST /register
This operation is used for registering new users, allowing them to input their information and get an account created.
POST /totp/qr
This operation is used for registering a new Authenticator Application by retrieving the QR code and secret that can be registered in a mobile authenticator such as MS Authenticator or Google Authenticator
Import API directly
If you prefer, you can create a new API from this API Version specification directly.