Alternate way to sign in - maduvena/jans-docs GitHub Wiki
Janssen's authentication server can integrate with any number of authentication mechanisms from different vendors. Factoring the pros and cons of each method, organizations can offer a diverse set of options. A users can register multiple types of credentials and use any preferred credential to perform a login.
An ACRouter Script is a PersonAuthenticationType
script orchestrates a 2FA flow by delegating specific implementation details of authentication methods to other scripts. This allows the flow to present users with alternatives in case some credential is not working as expected or is lost.
sequenceDiagram
autonumber
title User selects authentication mechanism
User agent->>Jans AS: Invoke /authorize endpoint
Jans AS->>User agent: Present "username" only screen <br/> OR <br/>username - password screen
User agent->>Jans AS: Present username <br/> OR username and password
Jans AS ->> Jans AS: verify user
Jans AS->>User agent: Show UI for preferred authentication method, <br>and also a link "Alternate way to sign in"
loop n times - (enter creds or select alternate way to sign in)
User agent->>Jans AS: Enter credentials (Or click on "Alternate way to sign in")
Jans AS->>User agent: Present page for authentication <br/> or <br/> present alternate authentication mechanisms
end
Jans AS->Jans AS: 8. validate id_token,<br/>create internal Jans session
opt if new user
Jans AS->Jans AS: 9. Dynamic enrollment or registration
end
Jans AS->User agent: 10. write Jans session cookie
Currently, the Jans Auth server comes with 2 PersonAuthenticationType
interception scripts that integrate multiple authentication methods and offer alternative options to users for sign-in.
-
Casa Script The
casa
script offers a 2 steps authentication flow with login and password prompted in the first step and a user-preferred authentication mechanism in the second step. -
Passwordless script The
passwordless
script offers a 2 steps authentication flow with username prompted in the first step and a user-preferred authentication mechanism in the second step.
Casa is a self-service web portal for end-users can be used to
- Enroll, delete and manage two-factor authentication (2FA) credentials for their account (e.g. FIDO security keys, mobile apps, phone numbers, etc.)
- Turn 2FA on and off
Ensure the following preconditions are met so that the authentication mehtod integrates seamlessly within flow:
- The orchestrator script looks for authentication method scripts under
/opt/jans/python/libs
. Write a custom script that focuses only on authentication. The script file name should follow naming convention likeorchestratorName-external_acrName
e.g.casa-external_fido2
orpwdless-external_fido2
- For step 1,
prepareForStep
must only returnTrue
- For step 1,
getExtraParametersForStep
must only returnNone
- For step 1, the
authenticate
routine must check if there is already an authenticated user, and if so bypass validating the username and password. This is because a user may have previously attempted authentication with a different method. - Keep in mind that
getPageForStep
won't be called whenstep=1
in your script. The orchestrator script i.e.casa
orpasswordless
script takes charge of this specific step/method combination - Add a
hasEnrollments
routine with a signature like thisdef hasEnrollments(self, configurationAttributes, user):
hasEnrollments
must returnTrue
orFalse
, describing whetheruser
has one or more credentials enrolled for the type you are interested in
Objects:
Object name | Object description |
---|---|
customScript |
The custom script object. Reference |
configurationAttributes |
configurationProperties passed in when adding custom script. Map<String, SimpleCustomProperty> configurationAttributes
|
SimpleCustomProperty |
Map of configuration properties. Reference |
User |
User object Reference |
- Ensure that custom pages returned by
getPageForStep
for step 2 (or higher) contain the fragment:
<ui:include src="/casa/casa.xhtml" />
This will display a set of links for the user to navigate to alternate 2FA pages. The list will be shown when clicking on a link which should be provided this way:
<a href="javascript:showAlternative('ELEMENT_ID')" id="alter_link" class="green hover-green f7-cust">#{msgs['casa.alternative']}</a>
Here ELEMENT_ID
is the identifier for the HTML node that wraps all visual elements of your page (excluding casa.xhtml
). It is required to preserve alter_link
as id
for the a
tag.
- Place the modified xhtml page under the path specified in
getPageForStep
, for e.g./opt/jans/jetty/jans-auth/custom/pages/casa/fido2.xhtml
Once your script is enabled in the Jans-auth server, you can test it for authentication purposes. Try your script by creating an authentication request passing casa
or passwordless
as acr value.