Last updated: March 12, 2020
The user login takes place through standard RFC 6749 OAuth 2.0 protocol. If you are familiar with how OAuth 2.0 works, then it will be very easy for you to understand the process and follow through. Otherwise, it's highly recommended that you first familiarize yourself with at least the basic mechanisms of the the OAuth 2.0 protocol before continuing. Down below are the steps involved in implementing a user login with Meveto.
To login a user to your application through Meveto, you first need to have your application registered with Meveto. After registration of your application, the next step is to add an action that will trigger the Meveto login process. Usually this is done via a button on your application. For detailed information about this action, click here. Additionally, Meveto users will also be able to login to your application from their Meveto dashboard. For this to work, Meveto will actually trigger the same login URL of your application that your application's login button would do. At the time of registration of your app, Meveto requires you to enter this login URL.
Initiate the login process
The login process is initiated either by a user action (such as clicking a "Login with Meveto" button) on your application or from their Meveto dashboard. On this URL, your app should start the standard OAuth 2.0 process. In case the login URL of your application is triggered externally, i.e. from the user's Meveto dashboard, then sometimes Meveto may pass some important information to your app via query parameters in the login URL. Therefore, your app must always check for the presence of these query parameters from Meveto, and set it on the Meveto login URL as query parameters along with the rest of the required values. At the moment, there are 2 parameters that Meveto might attach to the login URL of your app.
Sometimes Meveto will attach a onetime token to the login URL of your application, in order to bypass the need for logging in to Meveto first, before Meveto can log the user in to your application. Check if there is a
client_token query parameter and pass its value to the Meveto auth endpoint.
If your application allows Meveto account sharing, then you must also check for a
sharing_token in the login URL of your app that was triggered by Meveto, and pass it to the Meveto login URL as a query parameter.
It is possible that Meveto will attach both
sharing_token to the login URL of your app at the same time. Make sure to never miss them.
Generate the state parameter
Before submitting the login request to Meveto, generate an application state and store it. Session or cookie will not work because you will be redirected away from your application to Meveto. You can save the state in your database or more efficiently in some in-memory cache like Redis if your application is using it. This state must be passed to the authorization (login) request, and when the response is received back from Meveto, you must compare this state with the one that's received, (Meveto will respond back with the state parameter) and make sure that both the states are exactly the same before further processing user login.
Handle redirect from Meveto
Once your application submits a login request to the Meveto login URL, Meveto will process the request, login a user securely and then it will trigger the redirect URL of your application. Meveto will pass 2 parameters to this URL that your application will need to continue the process.
This is the authorization code issued by Meveto to your application on behalf of the authenticated user. This will generally be a long random string, that your application will need to prove authorizationfor getting
meveto_id of the authenticated user (also known as resource owner as per OAuth 2.0 standard).
This is the exact same state value that your application generated in the previous step, and passed to Meveto. You must make sure that the state value returned by Meveto to the redirect URL of your application is exactly the same as the one generated. This will prove that your request has been processed by Meveto and that the response your redirect URL is receiving is also genuine and sent by Meveto.
Exchange code with access token
After confirming that the state parameter is valid in your application's redirect URL, the next thing to do is to exchange the code with Meveto for an
access token. Meveto will verify the code and after successful verification, your app will get an access token on behalf of the user that will allow your app to retrieve the user's
meveto_id. For further details of the process, refer to the token endpoint API reference.
Get the user's Meveto ID
Once your application successfully retrieves an access token from Meveto, it's time to use the token as authorization in order to get Meveto ID of the user that wishes to login to your app. The process is detailed at the resource endpoint API reference.
Because Meveto is responsible for safely authenticating a user, when your application receives the Meveto ID of the user, from this point onwards, your application must take over the rest of the login process. This arrangement allows Meveto to remain completely non-invasive and to allow for your application to process the login as per your business logic.
Take over the rest of the login process
Start by looking up the user's Meveto ID in your application's Database. Identify your user locally and perform any process your application needs before logging the user in, such as dispatching an email, triggering an event or processing notifications etc. If the Meveto ID is not known to your app, it means that the user has never logged in to your app using Meveto before. If your application has an alternate authentication system, such as the traditional password based authentication, then let the user authenticate using an alternative authentication (though no other authentication system should ever be used with Meveto) and then map the user's Meveto ID to the local account. Finally, you can safely process the user's login. However, there's quite a bit more to it, read the details at the user account mapping.
Just before logging the user in, set a
last_logged_in attribute for the user to the current time. This attribute should always indicate the last time a user logged in to your app using Meveto. There should also be the opposite flag for each user with the
last_logged_out. This arrangement will allow your app to process user logout.