Login User
User Login Guide
Welcome to the User Login Guide. This document will walk you through the process of logging in a user to your application.
We will be creating a simple login flow that will allow users to log in to your application using the Endaoment OAuth service. This guide will cover adding a login button to your frontend, preparing a login URL, and verifying a login to issue an authentication token.
In order to do this, we will be creating 2 endpoints on your backend service:
/init-login
: This endpoint will initiate the login process and return a URL to redirect the user to the Endaoment OAuth page./verify-login
: This endpoint will verify the login and exchange the code for an authentication token.
Prerequisites
Before you begin, ensure you have the following:
- A webserver or API to handle verification requests
- A frontend application or client to allow users to interact with
- Basic understanding of HTTP requests
- A
clientId
andclientSecret
provided to you by Endaoment (stored securely on your backend)- You can request your OAuth credentials here.
- On the code samples provided in this document, the credentials will be stored on the
ENDAOMENT_CLIENT_ID
andENDAOMENT_CLIENT_SECRET
environment variables.
Flow Overview
Issuing Tokens Without OAuth Integration
While your team is working on the OAuth integration, you can immediately start building and testing your API integration without waiting for an OAuth client. Use our Access Token Issuer Tool to issue access tokens for users with your OAuth Credentials.
Please note that this tool is for development only. Production credentials require enhanced security measures when stored and handled.
Step-by-Step Instructions
1. Prepare the user interface
Before you can log in a user, you need to create a way for them to initiate the login process. This can be as simple as a button that sends a request to your backend service.
Your UI must send a request to your backend service to initiate the login process and then redirect the user to the Endaoment OAuth page to log in.
It is extremely important that you do not store the
clientId
andclientSecret
in your frontend application. This information should be kept secure on your backend service.
2. Create a Verifier and Challenge
Once your frontend has initiated the login process, your backend service must create a verification request for the user. This will require generating a codeVerifier
, codeChallenge
, and state
.
The following code snippet, taken from the backend/utils/init-login.ts file in the quickstart example, demonstrates how to generate the codeVerifier
, codeChallenge
, and state
:
3. Prepare the Login URL
Now that you have generated the codeVerifier
, codeChallenge
, and state
, you can prepare the URL to redirect the user to the Endaoment OAuth page.
The URL that you have generated will be sent to the frontend whenever the user initiates the login process. The frontend will then redirect the user to the Endaoment OAuth page to log in. Once the user has logged in, they will be redirected back to your redirectUri
.
4. Verify the Login and Exchange for an Access Token
Development Redirect URL
Since the Endaoment Authorization Server requires a fixed set of redirect URIs to be defined for a given client, make sure to host the application handling the redirect on one of the following URLs:
http://localhost:5454
http://localhost:5454/dev/token
When moving the integration from your local environment to cloud environments, make sure to reach out to us with the URLs you will be using to properly configure the integration.
Handling the redirect
Once the user has logged in and been redirected back to your redirectUri
, you must verify the login. This will require verifying the state
and code
and exchanging the code
for an authentication token.
The following code snippet, taken from the backend/routes/verify-login.ts file in the quickstart example, demonstrates how to verify the login and exchange the code
for an authentication token:
The response from the Endaoment OAuth token endpoint will look like this:
with the type:
Now that you have verified the login and exchanged the code
for an access_token
, you can store the token and return control to the frontend. The frontend can now use the token to make authenticated requests to your application.
Conclusion
You have successfully logged in a user and can now make authenticated requests to your application. If you would like to learn more about what is possible for setting up the oauth flow, please refer to the Open ID Connect Docs.
Next Steps
With the user logged in, your app is now open to performing a host of new actions on their account. You should now consider implementing the creating a new DAF flow.
If you would like to skip ahead, you can use the tool provided here to generate a development JWT token. Remember that this functionality is only available in development and should be replaced with your own OAuth server in production.