Conditions
In this article, you will learn how to customize your authentication flow with conditions. Conditional statements can be a crucial part of any authentication flow. With Descope, you can drag and drop them right into your authentication process with no code required.
Overview of Conditions
When customizing your flow with Descope, you might notice that many of the pre-configured flows contain this "Is new user?" condition:
When customizing your flow, if you want to add something like this or any other conditions like it to your project, you can create a new one by following these simple steps:
Add the Condition
Head to Flows, and select the Blue + button in the bottom left corner:
The Condition Box
Click on Condition, and a condition box will appear. Place this anywhere on the Flows panel and a popup will appear will all of the possible customizable options:
Conditional Statements
To create a conditional statement, select which key you would like to use, along with the respective value. In the case of "Is new user?", you will set the conditional using an authInfo property, as if it was a basic if-else statement:
Dynamic Fields
You can check keys for specific strings, integers, boolean values, location data, and more. The options will change depending on the key you wish to add a conditional statement for:
Final Result
Finally, you can take your conditional statements and add them to your flow by dragging arrows to and from the previous and next step, as shown here:
Use cases
First Seen
A use case that can benefit an organization is differentiating between new users and those already onboard. For example, the condition can help invoke a second factor for authentication. Using the "authInfo.firstSeen" boolean key as shown below:
User Roles
Implementing a flow to triage based on a user's role can benefit an organization by determining the user journey according to their role. In this example, you can see that we can add a second layer of authentication for "Admin" users to ensure that the person logging into such a powerful account is indeed the administrator:
Please note that we cover multiple options for using roles, such as tenant-level roles, project-based roles for Descopers, and roles for unauthenticated users.
Authentication Methods (Post Authentication)
Using conditions to check whether some authentication methods are configured for a user can benefit certain use cases. For instance, if a user authenticates via email, they should also authenticate using TOTP if it is configured. This condition assists the Descoper in distinguishing between the authentication methods their users have:
Of course, more authentication methods exist, and are also available to be conditioned, such as Oauth, SAML, password, WebAuthn. These authentication methods are also added to the claims inside the JWT, and to the user response from any kind of SDK.
Impossible Traveler
The term "Impossible Traveler" asserts that users cannot physically connect from different locations within a defined period. For example, people cannot physically log in to their user account from their home computer and from a foreign country within the same hour. However, the user can log in from their neighbor's home computer at the same period of time. When this scenario happens, most of the time, this means that the person's account has been compromised. In Descope, you can use this flag:
IsEmail and IsPhone Handling
It is possible to condition login handling on whether a phone or email is being used to easily handle login requests and create a more robust and automated framework. By conditioning IsEmail and IsPhone it allows simple streamlining of convenient authentication for user login based on which ever is most suitable for the end user and determining whether they want to log in via phone or email and direct them to the appropriate flow.
Check for Disabled Users
A Descoper can check for disabled users in their user management using isDisabled flag. This way one can provide a different path in the flow if they need to work with disabled users. This is done by
adding a condition in the flow with the context key unauthUser.isDisabled to check for a disabled user.
Check for Approved Domain
For use cases where you need to validate if a given domain is in the approved domain list, Descope supports "is Approved Domain" operator in a flow condition. This operator will check against the approved domain list within the project settings. This is usually helpful in scenarios where a malicious user could potentially manipulate the current hostname using browser injection techniques which could inturn be used to send embedded links (or other types) with a fraudulent URL. This operator ensures that the current domain matches against the trusted domains for the project.
Access non Descope cookies
Users can enable access to non-Descope cookies within the flow context to support advanced use cases. Descope allows adding a cookie value by its name in a flow.
The value of this cookie can be used in various ways, such as passing it to connectors for further analysis or including it as a JWT claim in a token, for example. In flow conditions, this capability can be accessed using the cookies.<name> key, where <name> represents your cookie's name (e.g., sess_id for session ID).
If you have any additional questions, feel free to reach out.