How to Create an App Password for Gmail, Google Workspace and Outlook

Why DevOpser apps need an app password

DevOpser app templates send email, such as sign-in links, through SMTP or Amazon SES. When you send through Gmail or Google Workspace, the app signs in to smtp.gmail.com with a username and password, and Google doesn't accept your regular account password from apps like this. The open-source DevOpser template reads these settings:

USE_SES=false
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=you@yourdomain.com
MAIL_PASSWORD=your-16-character-app-password
MAIL_DEFAULT_SENDER=you@yourdomain.com

MAIL_USERNAME must be the same account that created the app password. On DevOpser hosting, use the secret names in your site's Environment Template and change values with Update Environment Secrets. To avoid app passwords entirely, set USE_SES=true and SES_FROM_EMAIL to send through Amazon SES.

Before you start: turn on 2-Step Verification

Google and Microsoft only offer app passwords on accounts with 2-Step Verification (Microsoft calls it two-step verification) turned on.

• Google Account: open your Google Account security settings, select 2-Step Verification and follow the steps.
• Personal Microsoft account: open Microsoft account security, go to Advanced security options and turn on two-step verification.
• Work or school account: your administrator controls multifactor authentication. Ask them if you can't turn it on yourself.

How to create a Gmail app password

1. Turn on 2-Step Verification for your Google Account.
2. Go to myaccount.google.com/apppasswords and sign in if asked. You can also reach it from Security → 2-Step Verification → App passwords.
3. Enter a name that reminds you where the password is used, for example "DevOpser app".
4. Create the password. Google shows a 16-character code.
5. Copy the code into your app's password field (for a DevOpser app, MAIL_PASSWORD), then select Done.

Google recommends "Sign in with Google" over app passwords whenever an app supports it. Use an app password only for apps that ask for a username and password, such as an SMTP mail library.

Google Workspace app passwords

For users

Follow the Gmail steps above while signed in to your work account. If App passwords doesn't appear, ask your administrator to check the settings below.

For admins: allow users to manage app passwords

In Google Workspace, app passwords follow your 2-Step Verification settings. Users can create them when they're allowed to turn on 2-Step Verification and aren't restricted to security keys.

1. Sign in to the Google Admin console as a super administrator.
2. Go to Menu → Security → Authentication → 2-step verification.
3. Select the organizational unit or group that needs app passwords, or keep the top-level organizational unit selected to apply the setting to everyone.
4. Check Allow users to turn on 2-Step Verification.
5. If you enforce 2-Step Verification, don't limit these users to Only security key. Enforcing security keys disables app passwords.
6. Click Save, or Override for a child organizational unit.

If users connect an email client over IMAP, also make sure POP and IMAP access is turned on for them in the Admin console.

Outlook and Microsoft 365 app passwords

Personal Microsoft account (Outlook.com, Hotmail, Live)

1. Turn on two-step verification for your Microsoft account.
2. Go to Microsoft account security and open Advanced security options.
3. Scroll to the App passwords section and create a new app password.
4. Enter the app password in the app where it asks for your Microsoft account password.

Work or school account (Microsoft 365)

1. Sign in to My Account and select Security info.
2. Select Add method, choose App password and select Add.
3. Enter a name for the app and select Next.
4. Copy the password and paste it into the app.

If App password isn't in the list, your organization doesn't allow app passwords. Each user can have up to 40. Exchange Online has already turned off Basic authentication for IMAP and POP, and Microsoft has announced it will retire Basic authentication for SMTP AUTH too, so check with your administrator before relying on an app password with smtp.office365.com.

SMTP and IMAP settings to use with an app password

For a DevOpser app on Gmail or Google Workspace, keep the template default MAIL_PORT=587. Google Workspace accounts can send up to 2,000 messages a day through smtp.gmail.com; for more, send through Amazon SES.

Using and storing your app password

1. Use it in place of your regular password when configuring email in your application
2. Store it securely in your environment variables or secrets management system
3. Never share or reuse app passwords across different applications

How to manage or revoke app passwords

• Google: open App passwords, find the app in the list and select Remove. The app can't access your account after that. Google also revokes all your app passwords when you change your Google Account password.
• Microsoft work or school account: delete the app password from your Security info page.
• Personal Microsoft account: manage them in the App passwords section of Advanced security options.

If you revoke a password a DevOpser app uses, create a new one and update MAIL_PASSWORD, or the app will stop sending email.

Troubleshooting: app password missing or not working

The App passwords option is missing (Google)

Google lists these reasons:

• 2-Step Verification isn't turned on.
• 2-Step Verification is set up only with security keys.
• You're signed in to a work, school or other organization account. Ask your administrator, or see the admin steps above.
• The account is enrolled in Google's Advanced Protection.

The App password option is missing (Microsoft)

• Two-step verification isn't turned on.
• On a work or school account, your organization doesn't allow app passwords.

"Username and Password not accepted" or the app password stopped working

• Use your full email address as the username (MAIL_USERNAME), and make sure it's the account that created the app password.
• If you copied the code with spaces, try it without them.
• Match the port to the encryption: 587 with TLS (STARTTLS), or 465 with SSL.
• If you changed your Google Account password, every app password was revoked. Create a new one.
• Check that the app password is still listed on your App passwords page.
• For Outlook.com or Microsoft 365, the account may require OAuth instead; see the Microsoft section above.

Lost app password

You can't view an app password again. Remove the old one, create a new one and update the password in your application.

App password FAQ