Smart MFA API Overview
Early Preview
This API is in early preview and may be subject to change.
The Smart MFA API provides a convenient way to add intelligent risk based MFA to an existing authentication flow.
It is recommended that you use this flow immediately after you have succesfully authenticated a users password but before you create a session and let them into your application.
It is assumed that you already have/use a user database and a way to authenticate username/password. If you are looking for a solution that provides username/password authentication as well as MFA then we have other authentication options for you.
Prerequisites
In order for this API to function correctly you must have the following features configured in your OneLogin account.
API Credentials - A new set configured with Manage All permission
Authentication Factors
- SMS - Only required if you want to support SMS based MFA
- Email - Only required if you want to support Email based MFA
Default Security Policy - Email & SMS security factors must be enabled in the MFA section of your default security policy.
How does it work?
To start the Smart MFA flow you will first Validate a User by sending a unique identifier for the user along with contextual information about their login such as IP, User-Agent and device id. If high risk is detected then an MFA token will be sent via either Email or SMS to the user and a response payload will indicate that a token has been sent.
In the case that a MFA token has been sent, you will need to present a UI to the user that instructs them to enter the token they have just recieved. You will then take that token and use the Verify Token endpoint to complete the MFA verification.
The risk profile for a user will change over time. If the user constantally uses the same computer from the same location then their risk will drop after every successful token verification.
First Time Users
The user will always receieve a token on the first time this api is called for them. This is to register the device as trusted. From that point on the token will only be sent if the risk score exceeds the risk_threshold parameter.
Postman Collection
Replace sample variables indicated by {{ }} with your actual values.
Download for the Smart MFA API
Have a Question?
Found a problem or a bug? Submit a support ticket.
Looking for walkthroughs or how-to guides on OneLogin's user and admin features? Check out the documentation in our Knowledge Base.
Have a product idea or request? Share it with us in our Ideas Portal.