The process of setting up your first sample app with authentication can be a bit daunting. If you’re trying out a set up for the first time, the easiest type of authentication Nylas offers is called hosted authentication. What we mean by hosted authentication, is that Nylas handles as much as possible for you. We will auto-detect third-party providers and management of token exchanges. This type of authentication is best for when you don’t mind including Nylas branding in your flow (you have to use our login page) and you want the process handled for you.
What you’ll be doing in this tutorial
Together we will walk through setting up the Hosted Authentication sample application that’s available using the Python SDK (click here for the hosted-oauth repository). We’ll go over possible issues you may encounter and go through all the steps you need to take. At the end, we will do a walkthrough of what’s included in the code, which may be helpful for understanding what you’re setting up.
The set of steps we’re going to cover will include how to:
- Create an app in the Nylas dashboard for use with this project.
- Clone the Python examples repository and navigate to the sample app.
- Update your config.py with your Nylas credentials.
- Set up ngrok.
- Run the app and add your email.
It’s a lot to get through, however at the end you’ll have a running sample application that you can use for a variety of interesting projects involving Nylas hosted authentication!
NOTE FOR MAC USERS: This is a Flask project. By default, Flask runs on localhost:5000. If you get an error where you aren’t authorized to access localhost:5000, check to be sure you don’t have Airplay Receiver turned on for your Mac. Follow these steps to check and shut it off. Airplay Receiver uses port 5000, which will cause you problems with your app if you don’t make this change.
Create an app in the Nylas dashboard for use with this project
You need to create an app in the Nylas dashboard any time you’re starting a new project. If you want to add more than one user account to your app, you can’t use the Quick Start app that Nylas provides. So we will make our own app. To do this, take the following steps:
- Navigate to https://dashboard.nylas.com/sign-in and sign-in to your account.
- If you’ve created apps already, the dashboard opens to a page that displays your applications, like so:
If you don’t see this right away, then click All Applications from the left panel to get this screen.
- Click Create New App.
- Give your app a name in the App Name field. Choose API for application type. And choose Web as your platform. Click the Create App button to build the new application.
- Go to your new application’s dashboard by clicking Dashboard from the choices in the left menu panel. I named my app ‘Example.’ We can see here that I don’t have an account attached. We can add an email account from here, or from the Accounts section. For now, leave this as-is.
At this point in the walkthrough, you should have created an application.
Clone the Python examples repository and navigate to the sample app
You’ll need the repository for the hosted authentication application. Grab the nylas-python repository from GitHub – https://github.com/nylas/nylas-python. Then navigate through the examples folder and into the hosted-auth folder. Let’s configure the config.py file:
- Open config.py in the code editor of your choice.
- For NYLAS_OAUTH_CLIENT_ID, this is going to be your CLIENT_ID for your application. You can grab this by going to the Nylas dashboard and making sure you have your application selected at the top of the panel on the left.
- From the choices in the left panel, click App Settings.
- On the App settings screen, you’ll see your Client ID under Developer Details.
- You should also get the Client Secret from the App settings screen, and put that into the config.py file for NYLAS_OAUTH_CLIENT_SECRET.
- If you think you will want to test using http instead of https, then under the last entry in the config.py file, add OAUTHLIB_INSECURE_TRANSPORT = 1. You shouldn’t put this into production like this as it’s not secure, but it’s ok for testing. If you do this, you can use a localhost address instead of ngrok.
- Install your project’s dependencies from the terminal with: pip install -r requirements.txt in the hosted-auth directory.
Set up ngrok
To run the your first hosted authentication application, you need a way to connect via HTTPS. You can use the OAUTHLIB_INSECURE_TRANSPORT = 1 choice if you want to test with HTTP, but it’s best practice to use HTTPS. This is because it’s more secure and required in production (learn more about HTTP vs HTTPS here). Data sent using HTTP is unencrypted. Take the following steps:
- Make sure ngrok is installed. Go here to learn how – https://ngrok.com/docs/getting-started
- When you run ngrok, note that it gives you two URLs. You want the URL that starts with https. And, you’re going to need to add it as a callback for your application. So start ngrok with the command ngrok http 5000.
- Take the https version of the ngrok URL.
- Open your Nylas dashboard, and make sure you are viewing your app (the name will show at the top of the left panel. If it doesn’t, choose the right one from the drop-down.)
- From the left panel, click App Settings.
- From the App settings screen, click the Authentication tab. Across from Nylas Auth, you’ll see ‘Add your callback.’ Enter your https ngrok URL + /login/nylas/authorized. NOTE: If you stop your ngrok server, you will have to come back here and replace the callback with the new ngrok URL. Click Add Callback to add it.
- Add another callback – http://localhost:5000/login/nylas/authorized. You’re all set!
You should now have ngrok set up and your callback URLs added to your application.
Run the hosted authentication app and add your email account
Now we’re ready to run the app and see hosted authentication in action! You need a yahoo email set up if you want to follow along with this section exactly.
- Type python server.py.
- You’ll see the Nylas Hosted OAuth Example screen if everything is set up correctly:
- Click Connect to Nylas.
- You’ll be asked if your application can integrate with your email account. We are using a yahoo account, so enter a yahoo email in the Email field and click Log in.
You should now be ready to start integrating your account with Nylas using hosted authentication. Depending on what kind of account you add, you will have to take different steps. We are going over Yahoo today, future posts will show you how to walk through with Google and Microsoft email.
Integrate Yahoo mail with Nylas using hosted authentication
Now it’s time to add your email account! After you clicked Log in in the last section, based on the kind of email account you have, a different prompt appears. We’re using Yahoo, so that’s what you should see now. Let’s walk through the log in process:
Learn how to create a Yahoo application password
- You’ll be asked for your email and your application password. Since this is the Yahoo Mail flow, it’s not talking about your Nylas application. When you connect a Yahoo account, you must have your Yahoo application password. Let’s go over how to retrieve that.
- Click Learn more (https://help.yahoo.com/kb/SLN15241.html) to bring up Yahoo’s informational page about creating an application password.
- Click Generate an app password. Yahoo provides you with some instructions for creating the password you’ll need.
- Log in to your Yahoo Account Security page. To do this, go into your Yahoo Mail account and click on your account name in the upper right corner. A drop-down menu opens with a choice labeled Account info.
- Click Account info. This opens the Personal Info screen for your account.
- From the choices on the left side of the Personal Info screen, choose Account Security.
- To use account security, you have to log into your account again, even if you’re already logged in.
- Scroll to the bottom of the Account Security page. You’ll see a section called Other ways to sign in and it will show any app passwords you’ve made. You’ll also see an option to generate or manage app passwords. Click Generate and manage app passwords.
9. On the Generate an app password screen, enter your application’s name and click Generate password. Make a note of it you will need it for the credentials box Nylas prompted you with.
Make sure to save your password
10. You get a screen that displays your application password one time only. As a result, if you lose the password, you will have to delete the application and start over again. Thus you should save the password someplace secure. You’ll also receive instructions for how to use it. You log in with your regular account user name, but instead of your normal password, you put the password for the application you want to access with the account.
11. With the new application password, we can now go back to the Log in with Yahoo Mail screen that Nylas provided us with. Enter your application password in the provided box. If all goes well, you’ll be returned back to the Accounts screen for your Nylas application, and you will see your user account logged in. That’s it!
Not only can you integrate with Yahoo, but also Google and Microsoft. We will go over how to set those up in future posts. But for now, congrats, you’ve completed your first hosted authentication flow!