Enable single-sign-on for HAQM WorkMail with IAM Identity Center and Okta Universal Directory

Securing your business email is more critical than ever in today’s digital workplace. To help you protect your users and data in HAQM WorkMail (WorkMail), we regularly introduce security features that give organizations more control and protection for their business email. Thanks to the recently announced integration between WorkMail and AWS Identity and Access Management (IAM) Identity Center (IAM IdC), WorkMail users can now enjoy single sign-on (SSO) via compatible 3rd party external identity providers including Okta Universal Directory (Okta), Microsoft Entra ID, Google Workspace, JumpCloud, OneLogin, Ping Identity products and Active Directory.

This blog post explains the specific steps needed to integrate WorkMail with Okta via IAM IdC. WorkMail customers who use other 3rd party identity providers that are compatible with IdC will also find this post useful alongside the AWS documentation for their specific identity source. Alternatively, WorkMail organization administrators who do not use an external identity provider, but wish to enable multi-factor-authentication (MFA) for WorkMail viaIAM IdC will find guidance in a different blog post.

By integrating WorkMail with Okta via IAM IdC, users benefit from the security, convenience, and familiarity of SSO when accessing their WorkMail inbox and calendars via the WorkMail web-app. WorkMail organization administrators benefit from the security and efficiency of managing WorkMail user additions, modifications, or removals via the Okta admin tools. More detailed information about this integration can be found in the IAM IdC documentation as well as in the WorkMail documentation.

Introduction

Email remains a critical business communication tool, yet it is also one of the most targeted entry points for cyber threats. A single compromised email account can expose sensitive business data, damage an organization’s reputation, and serve as a gateway for further cyber attacks. As traditional username and password authentication becomes increasingly inadequate, organizations must adopt stronger access controls to protect their users and communications.

You can enhance your WorkMail organization’s security and simplify user authentication with SSO and a familiar login experience by integrating WorkMail with IAM IdC and Okta. This (and similar) integrations provide a more seamless authentication experience and helps administrators enforce consistent security policies across their organization.
The integration between WorkMail, IAM IdC and Okta supports these industry standards:

• System for Cross-domain Identity Management (SCIM) – Which enables automated user provisioning and identity synchronization across systems and applications.
• Security Assertion Markup Language (SAML) – Which provides secure authentication and authorization by exchanging identity and privilege information between identity providers and WorkMail.

WorkMail authentication options

When you first set up WorkMail, you use the built-in user directory which relies upon standard username | password authentication for the WorkMail web browser client as well as popular desktop and mobile email clients such as Microsoft Outlook, Apple Mail and Thunderbird.

By default, WorkMail uses username | password authentication

The integration between IAM Identity Center and Okta uses the SCIM protocol to provision and map user attributes in Okta to named attributes in IAM IdC. Once enabled, user and group information from Okta is automatically synchronized with IAM IdC. IAM IdC in turn uses the SAML protocol to provide Okta users with a familiar and convenient SSO experience.

After integrating IAM IdC with Okta, WorkMail uses:

1. Okta SSO for users of the WorkMail web-app.
2. Personal access tokens (PAT) for users of desktop &/or mobile email applications.

After integration with IdC and Okta, WorkMail uses SSO (web-app) and username | PAT (desktop/mobile) for authentication

Prerequisites for the WorkMail, IAM IdC and Okta integration

• Admin access to an AWS account
  • You can evaluate the integration in this post for a limited period of time using an AWS Free Tier Account
• Admin access to an HAQM WorkMail Organization
  • The integration uses the email domain that is configured as WorkMail’s default
• Admin access to HAQM IAM Identity Center
  • Or admin access to the IdC organization account
• Your WorkMail and IAM Identity Center must be in the same AWS region
• IAM Role with the security credentials needed to deploy AWS infrastructure via the AWS CDK
• Administrator access to a fully functional Okta Identity account populated with users and (optionally) group(s) that you want to integrate and synchronize with IAM IdC and WorkMail.
• Access to the AWS Samples GitHub repository, where you’ll find sample code that deploys via AWS CDK. This code sample deploys a customizable AWS Lambda initially configured to perform user synchronization between IAM IdC and WorkMail every 15 minutes.
• A source code editor such as Visual Studio Code with your AWS admin credentials.

High-level Steps

1. Configure Identity Center (See our documentation for detailed information).
2. Configure Okta Identity integration with IAM Identity Center. See this post for more information
3. Provision and synchronize Okta’s Groups (or Okta Users) with IAM Identity Center
4. Configure WorkMail to use Identity Center
5. Deploy the AWS CDK sample project found in aws-samples in GitHub
6. Test user access to WorkMail with and without Okta SSO (web-app) and Personal Access Token (desktop & mobile email clients)
7. Notify WorkMail users of upcoming changes to login procedures.
8. Switch WorkMail Authentication Mode to IAM IdC.

Detailed Configuration Guidance

The instructions that follow walk you through the steps needed to integrate your Okta system with IAM IdC. Once IAM IdC is synchronizing with Okta, you’ll integrate IAM IdC with WorkMail. This process will keep your WorkMail organization’s users and groups synchronized with Okta. Once fully enabled, your WorkMail users will use their Otka SSO credentials to access the WorkMail web-client or a username and unique Personal Access Tokens to access desktop &/or mobile email clients. Let’s get started!

Configure Okta integration with IAM Identity Center (these steps have been adapted from this blog post)

1. 1. Open the Okta admin landing page in a new browser (tab).

1. 2. Click the Applications Section in the left menu.
   3. Click on Applications in the dropdown menu.
   4. Click Browse App Catalog.

1. 5. Type AWS IAM Identity Center in the search box.
   6. Click on the app that matches AWS IAM Identity Center.

1. 7. Click Add Integration to initiate the integration process.

1. 8. Type a memorable name (like Workshop AWS IAM Identity Center) for the application label, and click Done.

1. 9. Click on the Sign On tab, scroll down to view SAML Signing Certificates.

1. 10. Click Actions to download the certificate to your local machine. Keep the Okta Admin dashboard Open, you will need the SAML information found here to configure IdC in the next section.

Configure AWS IAM IdC

1. In a new browser window (or tab), open the IAM IdC console in the same region as your WorkMail Organization (we’re using us-east-1).
2. If this is your first time accessing IAM IdC, you’ll be greeted with the IdC console home page prompting you to “Enable IAM Identity Center”. Click Enable.

3. Check that you are in the correct region, click Enable (note – this will enable an Organization instance of IdC, which is recommended. If you want to use an Account instance of IdC, please see the documentation).

4. Once IdC has been enabled, scroll down to the IAM Identity Center setup section and click Confirm Identity Source.

5. Click Actions, and select Change identity source from dropdown menu.

6. Select External identity provider and click Next.

7. Upload the SAML certificate you downloaded from Okta (above, step xx)
8. Open the Okta dashboard browser/tab. Under the SAML 2.0 configuration, scroll down and expand > More details.

• • Copy the Sign on URL from Okta SAML and paste the URL into the IdP sign-in URL field in IdC.
  • Copy the Issuer URL from Okta SAML and paste the URL into the IdP sign-in URL field in IdC.
  • Click Next.

9. Type ACCEPT in the confirmation text box & click Change identity source.

10. Switch back to the IAM IdC console browser window/tab. On the Settings page, locate the Automatic provisioning information box, and then choose Enable. Leave this browser window/tab open as you’ll need it to copy the values for the SCIM endpoint and Access token into Okta shortly (note – IdC Automatic provisioning uses SCIM protocol to provision users from Okta).

11. Return to the Okta admin dashboard (you should have left it open in another browser window or tab). Under IAM Identity Center applications, select the Workshop AWS IAM Identity Center and open the Provisioning tab.
12. Under Integration, click Configure API Integration.

13. Select the checkbox next to Enable API integration to enable provisioning.
14. Refer to the IAM IcC console browser window/tab you left open and copy (from IdC) and paste (into Okta) the values for:

• • Base URL field – paste the IdC SCIM endpoint value (make sure there is no trailing forward slash at the end of the URL).
  • API Token field, enter the Access token value.
  • Import Groups should be checked

15. Click Test API Credentials to verify the credentials entered are valid (the message AWS IAM Identity Center was verified successfully! should appear).

16. Save.
17. Under Settings, choose To App, click Edit and select Enable for Create Users, Update User Attributes and Deactivate Users. Click Save.

18. In the Okta admin dashboard’s left-hand menu pane, click on Directory.

• • Choose Groups to see the list of existing groups.
  • Click on the Add Group button to create a new group called workmail_users.
  • Fill in the required details for the new group, including:
    • Group Name: Enter workmail_users for the group.
    • Group Description (optional): Provide a description for the group’s purpose (WorkMail_users).
  • Save the New Group
  • Reload the page to see the newly created group
  • Click Assign people
  • Add Okta users to the workmail_users group
  • Click Save

19. In the Okta admin dashboard’s left-hand menu pane, click on Applications and open the AWS IAM Identity Center application.
20. Click the Assignments tab, choose Assign, then choose Assign to people.
21. Choose the Okta users that you want to have access to WorkMail via IAM Identity Center app.
22. For each user, click Assign, review the user info, and click Save then Go Back
23. When all Okta users for whom you want WorkMail users created/synced have been assigned, click Done to start the process of provisioning the users into IAM Identity Center.

24. On the Assignments page, choose Assign, and then choose Assign to groups.
25. Click the Okta group (workmail_users) that you want to have access to WorkMail via IAM Identity Center.
26. Click Assign, review the selections, click Save and Go Back. Click Done. This starts the process of provisioning the users in the workmail_users group into IAM Identity Center.
27. Choose the Push Groups tab.
28. Choose the workmail_users group that contains all the users that you assigned to the IAM Identity Center app.
29. If the group is not found in the list, choose the Find groups by name option by clicking (+)Push Groups Menu.
30. Enter the group name ( workmail_users) that you created in the previous step and select it from the search results
31. Click Save. The group status changes to “pushing” then “Active” (this can take several minutes), once the Okta workmail_users group and all its members have been pushed to IAM Identity Center.
32. Return to the browser window/tab with the IAM Identity Center console.
33. In the left navigation, select Groups (or Users) (you should see the Group (or users) list that was just populated by the Okta “push” action).

Enable IAM Identity Center in HAQM WorkMail

1. Open a new browser window (tab) to the WorkMail console in the same region as IdC, and open your WorkMail Organization.
2. In WorkMail’s left navigation rail click Identity Center
3. Click on Multi-factor authentication setup guide, Click Enable Identity Center, read the default configuration notice ,and click Enable

4. Under Identity Center Settings, click the Authentication mode tab and ensure it is set for WorkMail directory and Identity center (this is the default).
5. This mode is needed for testing and to allow desktop & mobile email client users to retrieve their unique personal access tokens.
6. Once the integration with IdC is successfully tested, and those WorkMail users who rely on desktop or mobile email clients for access have had the opportunity to login to the WorkMail web app to retrieve a PAT, you will change the Authentication mode to Identity center only.

Deploy the sample solution from GitHub

Solution prerequisites:

– AWS Account
– AWS IAM user with Administrator permissions
– Python (> v3.x) and Pip fully installed and configured on your computer
– AWS CLI (v2) installed and configured on your computer
– AWS CDK (v2) installed and configured on your computer
– Sample CDK project that creates and deploys an AWS Lambda in your AWS account to perform users synchronization between IAM IdC and WorkMail.

The instructions that follow guide you in deploying a sample solution for the AWS Samples Serverless-Mail repository that programmatically creates/syncs WorkMail users from IAM Identity Center using the AWS CDK CLI. The sample uses naming conventions used in this blog. For example, the Lambda only syncs those users found in the IdC Group named "workmail_users". If your IdC group has a different name, or you want to sync multiple IdC groups with WorkMail, you will need to modify the sample code before proceeding. (BE AWARE: The sample code base is an Open Source starter project designed to provide a demonstration and a base to start from for specific use cases. It should not be considered fully Production-ready, nor should it be deployed in a production environment. Refer to the README.md and License.md for more information.)

1. Clone the sample project to your computer (git clone http://github.com/aws-samples/serverless-mail/tree/main/idc_okta-workmail). CD into the ‘idc_okta-workmail‘ directory.
2. Create a virtual environment for packaging in Python (Docker must already be running locally) with python3 -m venv .venv
3. Activate the virtual environment with source .venv/bin/activate
4. Make sure cdk.json references the correct path to Python (by default cdk.json refers to .venv/bin/python app.py). If you need to locate Python, run the which python command.
5. Install the project dependencies with pip3 install -r requirements.txt
6. Check the AWS CLI local credentials and region with aws sts get-caller-identity . If you need to change any parameter, run aws configure
7. Prepare the `app.py` file by running python3 get-my-variables.py  . The ‘get-my-variables.py’ script fetches the necessary variables from your AWS account and create the `app.py` file needed by the CDK. You may want to review the auto-generated `app.py` file for accuracy, especially if the AWS account has been used for other IdC or WorkMail related projects. The app.py file requires the following account variables:
   • AWS accountId
   • AWS Region – the region must be the same for IdC and WorkMail.
   • IDENTITYSTORE_ID – – found in the Identity Center console under settings or via the AWS CLI aws identitystore list-groups --identity-store-id {identity_store_id}
   • IDENTITY_CENTER_INSTANCE_ARN – found in the Identity Center console under settings or via the AWS CLI aws sso-admin list-instances
   • IDENTITY_CENTER_APPLICATION_ARN – found in the Identity Center console under Applications or via the AWS CLI aws sso-admin list-applications --instance-arn {instance_arn}`
   • WORKMAIL_ORGANIZATION_ID – found in the WorkMail console under Organizations or via the AWS CLI aws workmail list-organizations
   • OKTA_GROUP_ID_TO_ASSIGN_TO_WORKMAIL – found in the Identity Center console under Groups > General Information or via the AWS CLI aws identitystore list-groups --identity-store-id {identity_store_id}
8. Bootstrap the package (this step may take several minutes to complete) with cdk bootstrap
9. Synthesize the package (this step may take several minutes to complete) with cdk synthesize
10. Deploy your package (this step may take several minutes to complete) with cdk deploy and follow the prompts in the AWS CDK CLI.
11. Once deployment to your AWS account starts, you can view the deployment status in the CloudFormation console.

Confirm WorkMail Authentication mode

WorkMail’s default Authentication mode should be set to WorkMail directory and Identity center. Don’t change this yet. This mode will allow WorkMail web-app users to continue to login to the WorkMail client directly, without Okta SSO. WorkMail’s Personal access token configuration default is set to active, and token lifespan set to 365 days. You can change this if your security needs differ from the default. PATs are used by desktop and mobile email clients to login to WorkMail. Leaving WorkMail’s default Authentication mode set to WorkMail directory allows desktop and mobile email clients to continue to login to the WorkMail with their username and password, without yet requiring a PAT instead of password.

Conduct a few spot tests to verify WorkMail web-app users can properly access their WorkMail accounts via:

1. The HAQM WorkMail web application URL (found on the WorkMail organization page)

2. Your organization’s unique AWS access portal URL (found on the setting page of the IAM IdC dashboard).

3. This will open a new browser tab that redirects to the Okta user login page.

4. Once user has authenticated, this page will redirect to the AWS access portal with linked application tiles to all of the AWS applications that have been integrated with IAM Identity Center.

5. Click on the WorkMail logo, and the WorkMail web-app will load.

6. Desktop or mobile email software users need to create a WorkMail Personal Access Token (PAT) to access WorkMail. These users must retrieve their own PATs after logging into the WorkMail web-client. Open the Webmail login link found on the WorkMail Organization page under User Login

7. In the WorkMail web-app,
   1. click the settings gear (in top right)
   2. Click Personal Access token and enter a token name (i.e. desktop-thunderbird-pat)
   3. Click Create token.
   4. Click Create token.
   5. Copy the token value (this is the only time you can retrieve this token value).
8. Open your desktop or mobile email software, enter your username and your PAT (the PAT replaces your existing user password).

9. In settings, click Personal Access token and Create token
10. Enter a token name (typically the device on which you’ll use this PAT) and select create token.
11. Copy the token value (this is the only time you can retrieve this token value).
12. Open your desktop or mobile email software, enter your username and your PAT (the PAT replaces your existing user password), and test your new login (username | PAT).

Notify your WorkMail users of upcoming changes to login procedures

Once you have tested the integration between WorkMail and IAM Identity Center with a few test users, you should prepare your WorkMail users for the increased login security. For example, you could send them an email that explains:

• The organization is adding an additional login security step to help protect their inboxes.
• Inform them that they should anticipate an email from the AWS IAM Identity Center with info about the upcoming implementation of MFA for web-app users and PATs for desktop and mobile client users.
• Users should accept the invitation and create a new password for the AWS IAM Identity Center.
• Inform them that once WorkMail MFA is enabled, all WorkMail web-app users will be required to use their username, password and MFA.
• Inform them that once WorkMail PATs are enabled, all WorkMail desktop and mobile email client users will need to login to the WorkMail web client (with MFA) via the AWS access portal URL, create one PAT per software client (the same PAT can not be used on desktop and mobile). They then must update their desktop or mobile email software to use their username and PAT, instead of their current password. Explain that the PAT is now their email client application password and their personal desktop or mobile email software passwords will no longer work.
• Provide users with a way to request support.

Switch WorkMail Authentication Mode to Identity Center only

1. Once you are satisfied that your WorkMail users have incorporated Okta SSO and/or PATs into their WorkMail login routines, the WorkMail administrator should disable the WorkMail directory Authentication mode found in the WorkMail console under Organization > Identity Center.

2. Optional – Ask several trusted users to test their ability to login to WorkMail web app via Okta credentials.

Congratulations, your WorkMail organization’s authentication is now being managed by IAM Identity Center and your external identity provider, Okta.

Conclusion

By integrating IAM Identity Center with Okta Identity and WorkMail, you can provide your users with the convenience of Okta SSO for the WorkMail web-app. This allows your organization to improve it’s email security posture, better safeguard sensitive communications and protect you WorkMail organization against unauthorized access. Furthermore, this integration reduces admin overhead as user access to WorkMail is allowed, or revoked via the Okta administration dashboard.

Take control of your email communications today with HAQM WorkMail:

1. Visit the WorkMail Console to begin configuration.
2. Enable IAM Identity Center Integration with Okta and WorkMail.
3. Connect your WorkMail organization to centralized access management.
4. Configure WorkMail to require:
   1. Okta SSO – Adds an extra layer of security for web-app users.
   2. Personal Access Tokens (PAT) – Add an extra layer of security for desktop and mobile client access.

Need guidance? Check out our technical documentation. Contact your AWS account team.

To help keep your WorkMail organization secure, we recommend:

• Regularly reviewing your WorkMail audit logs for unexpected activity.
• Monitoring for unauthorized access attempts.
• Staying informed about the latest security practices.

Dive deeper into WorkMail security with these resources:

• HAQM WorkMail Security Documentation
• WorkMail Audit Logging Overview
• Custom Security Alarm Setup

Join the Conversation:
Connect with other administrators and security professionals on the AWS re:Post community to share insights and learn best practices.