# Configure SAML 2.0 and create a WorkSpaces Pools directory
You can enable WorkSpaces client application registration and signing in to WorkSpaces in a WorkSpaces Pool by setting up identity federation using SAML 2.0. To do this, you use an AWS Identity and Access Management (IAM) role and a relay state URL to configure your SAML 2.0 identity provider (IdP) and enable it for AWS. This grants your federated users access to a WorkSpace Pool directory. The relay state is the WorkSpaces directory endpoint to which users are forwarded after successfully signing in to AWS.
**Important**
WorkSpaces Pools doesn't support IP-based SAML 2.0 configurations.
**Topics**
+ [Step 1: Consider the requirements](#saml-directory-consider-the-requirements)
+ [Step 2: Complete the prerequisites](#saml-directory-complete-the-prereqs)
+ [Step 3: Create a SAML identity provider in IAM](#saml-directory-create-saml-idp)
+ [Step 4: Create WorkSpace Pool directory](#saml-directory-create-wsp-pools-directory)
+ [Step 5: Create a SAML 2.0 federation IAM role](#saml-directory-saml-federation-role-in-iam)
+ [Step 6: Configure your SAML 2.0 identity provider](#saml-directory-configure-saml-idp)
+ [Step 7: Create assertions for the SAML authentication response](#saml-directory-create-assertions)
+ [Step 8: Configure the relay state of your federation](#saml-directory-configure-relay-state)
+ [Step 9: Enable integration with SAML 2.0 on your WorkSpace Pool directory](#saml-directory-enable-saml-integration)
+ [Troubleshooting](#saml-pools-troubleshooting)
+ [Specify Active Directory details for your WorkSpaces Pools directory](pools-service-account-details.md)
## Step 1: Consider the requirements
The following requirements apply when setting up SAML for a WorkSpaces Pools directory.
+ The workspaces\$1DefaultRole IAM role must exist in your AWS account. This role is automatically created when you use the WorkSpaces Quick Setup or if you previously launched a WorkSpace using the AWS Management Console. It grants Amazon WorkSpaces permission to access specific AWS resources on your behalf. If the role already exists, you might need to attach the AmazonWorkSpacesPoolServiceAccess managed policy to it, which Amazon WorkSpaces uses to access required resources in the AWS account for WorkSpaces Pools. For more information, see [Create the workspaces\$1DefaultRole Role](workspaces-access-control.md#create-default-role) and [AWS managed policy: AmazonWorkSpacesPoolServiceAccess](managed-policies.md#workspaces-pools-service-access).
+ You can configure SAML 2.0 authentication for WorkSpaces Pools in the AWS Regions that support the feature. For more information, see [AWS Regions and Availability Zones for WorkSpaces Pools](wsp-pools-regions.md).
+ To use SAML 2.0 authentication with WorkSpaces, the IdP must support unsolicited IdP-initiated SSO with a deep link target resource or relay state endpoint URL. Examples of IdPs that support this include ADFS, Azure AD, Duo Single Sign-On, Okta, PingFederate, and PingOne. Consult your IdP documentation for more information.
+ SAML 2.0 authentication is supported only on the following WorkSpaces clients. For the latest WorkSpaces clients, see the [Amazon WorkSpaces Client Download page](https://clients.amazonworkspaces.com/).
+ Windows client application version 5.20.0 or later
+ macOS client version 5.20.0 or later
+ Web Access
## Step 2: Complete the prerequisites
Complete the following prerequisites before configuring your SAML 2.0 IdP connection to a WorkSpaces Pool directory.
+ Configure your IdP to establish a trust relationship with AWS.
+ See [Integrating third-party SAML solution providers with AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml_3rd-party.html) for more information on configuring AWS federation. Relevant examples include IdP integration with IAM to access the AWS Management Console.
+ Use your IdP to generate and download a federation metadata document that describes your organization as an IdP. This signed XML document is used to establish the relying party trust. Save this file to a location that you can access from the IAM console later.
+ Create a WorkSpaces Pool directory by using the WorkSpaces console. For more information, see [Using Active Directory with WorkSpaces Pools](active-directory.md).
+ Create a WorkSpaces Pool for users who can sign in to the IdP using a supported directory type. For more information, see [Create a WorkSpaces Pool](set-up-pools-create.md).
## Step 3: Create a SAML identity provider in IAM
To get started, you must create a SAML IdP in IAM. This IdP defines your organization's IdP-to-AWS trust relationship using the metadata document generated by the IdP software in your organization. For more information, see [Creating and managing a SAML identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html#idp-manage-identityprovider-console) in the *AWS Identity and Access Management User Guide*. For information about working with SAML IdPs in AWS GovCloud (US) Regions, see [AWS Identity and Access Management](https://docs.aws.amazon.com//govcloud-us/latest/UserGuide/govcloud-iam.html) in the *AWS GovCloud (US) User Guide*.
## Step 4: Create WorkSpace Pool directory
Complete the following procedure to create a WorkSpaces Pool directory.
1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).
1. Choose **Directories** in the navigation pane.
1. Choose **Create directory**.
1. For **WorkSpace type**, choose **Pool**.
1. In the **User identity source** section of the page:
1. Enter a placeholder value into the **User access URL** text box. For example, enter `placeholder` into the text box. You will edit this later after setting up the application entitlement in your IdP.
1. Leave the **Relay state parameter name** text box blank. You will edit this later after setting up the application entitlement in your IdP.
1. In the **Directory information** section of the page, enter a name and a description for the directory. The directory name and description must be less than 128 characters, can contain alphanumeric characters and the following special characters: `_ @ # % * + = : ? . / ! \ -`. The directory name and description cannot start with a special character.
1. In the **Networking and security** section of the page:
1. Choose a VPC and 2 subnets that have access to the network resources that your application needs. For increased fault tolerance, you should choose two subnets in different Availability Zones.
1. Choose a security group that allows WorkSpaces to create network links in your VPC. Security groups control what network traffic is allowed to flow from WorkSpaces to your VPC. For example, if your security group restricts all inbound HTTPS connections, users accessing your web portal won't be able to load HTTPS websites from the WorkSpaces.
1. The **Active Directory Config** section is optional. However, you should specify your Active Directory (AD) details during the creation of your WorkSpaces Pools directory if you plan to use an AD with your WorkSpaces Pools. You can't edit the **Active Directory Config** for your WorkSpaces Pools directory after you create it. For more information about specifying your AD details for your WorkSpaces Pool directory, see [Specify Active Directory details for your WorkSpaces Pools directory](pools-service-account-details.md). After you complete the process outlined in that topic, you should return to this topic to finish creating your WorkSpaces Pools directory.
You can skip the **Active Directory Config** section if you don't plan on using an AD with your WorkSpaces Pools.
1. In the **Streaming properties** section of the page:
+ Choose the clipboard permissions behavior, and enter a copy to local character limit (optional), and paste to remote session character limit (optional).
+ Choose to allow or not allow print to local device.
+ Choose to allow or not allow diagnostic logging.
+ Choose to allow or not allow smart card sign in. This feature applies only if you enabled AD configuration earlier in this procedure.
1. In the **Storage** section of the page, you can choose to enable home folders.
1. In the **IAM role section** of the page, choose an IAM role to be available to all desktop streaming instances. To create a new one, choose **Create new IAM role**.
When you apply an IAM role from your account to a WorkSpace Pool directory, you can make AWS API requests from a WorkSpace in the WorkSpace Pool without manually managing AWS credentials. For more information, see [Creating a role to delegate permissions to an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html) in *AWS Identity and Access Management User Guide*.
1. Choose **Create directory**.
## Step 5: Create a SAML 2.0 federation IAM role
Complete the following procedure to create a SAML 2.0 federation IAM role in the IAM console.
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/secretsmanager/).
1. Choose **Roles** in the navigation pane.
1. Choose Create role.
1. Choose **SAML 2.0 federation** for the trusted entity type.
1. For SAML 2.0-based provider, choose the identity provider you created in IAM. For more information, see [Create a SAML identity provider in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html?).
1. Choose **Allow programmatic access only** for the access to be allowed.
1. Choose ** SAML:sub\$1type** for the attribute.
1. For **Value**, enter `https://signin.aws.amazon.com/saml`. This value restricts role access to SAML user streaming requests that include a SAML subject type assertion with a value of `persistent`. If the SAML:sub\$1type is persistent, your IdP sends the same unique value for the `NameID` element in all SAML requests from a particular user. For more information, see [Uniquely identifying users in SAML-based federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml.html#CreatingSAML-userid) in *AWS Identity and Access Management User Guide*.
1. Choose **Next** to continue.
1. Don't make changes or selections in the **Add permissions** page. Choose **Next** to continue.
1. Enter a name and a description for the role.
1. Choose **Create role**.
1. In the **Roles** page, choose the role you must created.
1. Choose the **Trust relationships** tab.
1. Choose **Edit trust policy**.
1. In the **Edit trust policy** JSON text box, add the **sts:TagSession** action to the trust policy. For more information, see [Passing session tags in AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html) in *AWS Identity and Access Management User Guide*.
The result should look like the following example.
![\[An example of a trust policy.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/iam-saml-federation-policy-sts-tagsession.png)
1. Choose **Update policy**.
1. Choose the **Permissions** tab.
1. In the **Permissions policies** section of the page choose **Add permissions** and then choose **Create inline policy**.
1. In the **Policy editor** section of the page, choose **JSON**.
1. In the **Policy editor** JSON text box, enter the following policy. Be sure to replace:
+ ** with the code of the AWS Region in which you created your WorkSpace Pool directory.
+ ** with the AWS account ID.
+ ** with the ID of the directory you created earlier. You can get this in the WorkSpaces console.
For resources in AWS GovCloud (US) Regions, use the following format for the ARN: `arn:aws-us-gov:workspaces:::directory/`.
1. Choose Next.
1. Enter a name for the policy, and then choose **Create policy**.
## Step 6: Configure your SAML 2.0 identity provider
Depending on your SAML 2.0 IdP, you might need to manually update your IdP to trust AWS as a service provider. You do this by downloading the `saml-metadata.xml` file found at [https://signin.aws.amazon.com/static/saml-metadata.xml](https://signin.aws.amazon.com/static/saml-metadata.xml), and then uploading it to your IdP. This updates your IdP’s metadata.
For some IdPs, the update might already be configured. You can skip this step if it's already configured. If the update isn't already configured in your IdP, review the documentation provided by your IdP for information about how to update the metadata. Some providers give you the option to type the URL of the XML file into their dashboard, and the IdP obtains and installs the file for you. Others require you to download the file from the URL and then upload it to their dashboard.
**Important**
At this time, you can also authorize users in your IdP to access the WorkSpaces application you have configured in your IdP. Users who are authorized to access the WorkSpaces application for your directory don't automatically have a WorkSpace created for them. Likewise, users that have a WorkSpace created for them are not automatically authorized to access the WorkSpaces application. To successfully connect to a WorkSpace using SAML 2.0 authentication, a user must be authorized by the IdP and must have a WorkSpace created.
## Step 7: Create assertions for the SAML authentication response
Configure the information that your IdP sends to AWS as SAML attributes in its authentication response. Depending on your IdP, this is might already be configured. You can skip this step if it's already configured. If it's not already configured, provide the following:
+ **SAML Subject NameID** — The unique identifier for the user who is signing in. Don't change the format/value of this field. Otherwise, the home folder feature will not work as expected because the user will be treated as different user.
**Note**
For domain-joined WorkSpaces Pools, the `NameID` value for the user must be provided in the `domain\username` format using the `sAMAccountName`, or in the `username@domain.com` format using `userPrincipalName`, or just `userName`. If you are using the `sAMAccountName` format, you can specify the domain by using either the NetBIOS name or the fully qualified domain name (FQDN). The `sAMAccountName` format is required for Active Directory one-way trust scenarios. For more information, see [Using Active Directory with WorkSpaces Pools](active-directory.md). if just `userName` is provided, the user will be logged in to the primary-domain
+ **SAML Subject Type (with a value set to `persistent`)** — Setting the value to `persistent` ensures that your IdP sends the same unique value for the `NameID` element in all SAML requests from a particular user. Make sure that your IAM policy includes a condition to only allow SAML requests with a SAML `sub_type` set to `persistent`, as described in the [Step 5: Create a SAML 2.0 federation IAM role](#saml-directory-saml-federation-role-in-iam) section.
+ **`Attribute` element with the `Name` attribute set to https://aws.amazon.com/SAML/Attributes/Role** — This element contains one or more `AttributeValue` elements that list the IAM role and SAML IdP to which the user is mapped by your IdP. The role and IdP are specified as a comma-delimited pair of ARNs. An example of the expected value is `arn:aws:iam:::role/,arn:aws:iam:::saml-provider/`.
+ **`Attribute` element with the `Name` attribute set to https://aws.amazon.com/SAML/Attributes/RoleSessionName** — This element contains one `AttributeValue` element that provides an identifier for the AWS temporary credentials that are issued for SSO. The value in the `AttributeValue` element must be between 2 and 64 characters long, can contain alphanumeric characters and the following special characters: `_ . : / = + - @`. It can't contain spaces. The value is typically an email address or a user principal name (UPN). It shouldn't be a value that includes a space, such as a user's display name.
+ **`Attribute` element with the `Name` attribute set to https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email** — This element contains one `AttributeValue` element that provides the email address of the user. The value must match the WorkSpaces user email address as defined in the WorkSpaces directory. Tag values may include combinations of letters, numbers, spaces, and `_ . : / = + - @` characters. For more information, see [Rules for tagging in IAM and AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html#id_tags_rules) in the *AWS Identity and Access Management User Guide*.
+ (Optional) **`Attribute` element with the `Name` attribute set to https://aws.amazon.com/SAML/Attributes/PrincipalTag:UserPrincipalName** — This element contains one `AttributeValue` element that provides the Active Directory `userPrincipalName` for the user who is signing in. The value must be provided in the `username@domain.com` format. This parameter is used with certificate-based authentication as the Subject Alternative Name in the end user certificate. For more information, see [Certificate-based authentication and WorkSpaces Personal](certificate-based-authentication.md).
+ (Optional) **`Attribute` element with the `Name` attribute set to https://aws.amazon.com/SAML/Attributes/PrincipalTag:ObjectSid (optional) ** — This element contains one `AttributeValue` element that provides the Active Directory security identifier (SID) for the user who is signing in. This parameter is used with certificate-based authentication to enable strong mapping to the Active Directory user. For more information, see [Certificate-based authentication and WorkSpaces Personal](certificate-based-authentication.md).
+ (Optional) **`Attribute` element with the `Name` attribute set to https://aws.amazon.com/SAML/Attributes/PrincipalTag:Domain** — This element contains one `AttributeValue` element that provides the Active Directory DNS fully qualified domain name (FQDN) for users signing in. This parameter is used with certificate-based authentication when the Active Directory `userPrincipalName` for the user contains an alternative suffix. The value must be provided in the `domain.com` format, and must include any subdomains.
+ (Optional) **`Attribute` element with the `Name` attribute set to https://aws.amazon.com/SAML/Attributes/SessionDuration** — This element contains one `AttributeValue` element that specifies the maximum amount of time that a federated streaming session for a user can remain active before re-authentication is required. The default value is `3600` seconds (60 minutes). For more information, see the [SAML SessionDurationAttribute](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html#saml_role-session-duration) in the *AWS Identity and Access Management User Guide*.
**Note**
Although `SessionDuration` is an optional attribute, we recommend that you include it in the SAML response. If you don't specify this attribute, the session duration is set to a default value of `3600` seconds (60 minutes). WorkSpaces desktop sessions are disconnected after their session duration expires.
For more information about how to configure these elements, see [Configuring SAML assertions for the authentication response](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html) in the *AWS Identity and Access Management User Guide*. For information about specific configuration requirements for your IdP, see your IdP's documentation.
## Step 8: Configure the relay state of your federation
Use your IdP to configure the relay state of your federation to point to the WorkSpaces Pool directory relay state URL. After successful authentication by AWS, the user is directed to the WorkSpaces Pool directory endpoint, defined as the relay state in the SAML authentication response.
The following is the relay state URL format:
```
https://relay-state-region-endpoint/sso-idp?registrationCode=registration-code
```
The following table lists the relay state endpoints for the AWS Regions where WorkSpaces SAML 2.0 authentication is available. AWS Regions in which the WorkSpaces Pools feature is not available have been removed.
| Region | Relay state endpoint |
| --- | --- |
| US East (N. Virginia) Region | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/create-directory-pools.html) |
| US West (Oregon) Region | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/create-directory-pools.html) |
| Asia Pacific (Mumbai) Region | workspaces.euc-sso.ap-south-1.aws.amazon.com |
| Asia Pacific (Seoul) Region | workspaces.euc-sso.ap-northeast-2.aws.amazon.com |
| Asia Pacific (Singapore) Region | workspaces.euc-sso.ap-southeast-1.aws.amazon.com |
| Asia Pacific (Sydney) Region | workspaces.euc-sso.ap-southeast-2.aws.amazon.com |
| Asia Pacific (Tokyo) Region | workspaces.euc-sso.ap-northeast-1.aws.amazon.com |
| Canada (Central) Region | workspaces.euc-sso.ca-central-1.aws.amazon.com |
| Europe (Frankfurt) Region | workspaces.euc-sso.eu-central-1.aws.amazon.com |
| Europe (Ireland) Region | workspaces.euc-sso.eu-west-1.aws.amazon.com |
| Europe (London) Region | workspaces.euc-sso.eu-west-2.aws.amazon.com |
| South America (São Paulo) Region | workspaces.euc-sso.sa-east-1.aws.amazon.com |
| AWS GovCloud (US-West) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/create-directory-pools.html) For information about working with SAML IdPs in AWS GovCloud (US) Regions, see [ Amazon WorkSpaces](https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-workspaces.html) in the *AWS GovCloud (US) User Guide*. |
| AWS GovCloud (US-East) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/create-directory-pools.html) For information about working with SAML IdPs in AWS GovCloud (US) Regions, see [ Amazon WorkSpaces](https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-workspaces.html) in the *AWS GovCloud (US) User Guide*. |
## Step 9: Enable integration with SAML 2.0 on your WorkSpace Pool directory
Complete the following procedure to enable SAML 2.0 authentication for the WorkSpaces Pool directory.
1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home).
1. Choose **Directories** in the navigation pane.
1. Choose the **Pools directories** tab.
1. Choose the ID of the directory you want to edit.
1. Choose **Edit** in the **Authentication** section of the page.
1. Choose **Edit SAML 2.0 Identity Provider**.
1. For the **User Access URL**, which is sometimes know as the "SSO URL", replace the placeholder value with the SSO URL provided to you by your IdP.
1. For the **IdP deep link parameter name**, enter the parameter that is applicable to your IdP and the application you have configured. The default value is `RelayState` if you omit the parameter name.
The following table lists the user access URLs and deep link parameter names that are unique to various identity providers for applications.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/create-directory-pools.html)
1. Choose **Save**.
**Important**
Revoking SAML 2.0 from a user won't directly disconnect their session. They will be removed only after the timeout kicks in. They can also terminate it using the [ TerminateWorkspacesPoolSession](https://docs.aws.amazon.com//workspaces/latest/api/API_TerminateWorkspacesPoolSession.html) API.
## Troubleshooting
The following information can help you troubleshoot specific issues with your WorkSpaces Pools.
### I am receiving an "Unable to login" message in the WorkSpaces Pools client after completing SAML authentication
The `nameID` and `PrincipalTag:Email` in the SAML claims need to match the username and email configured in Active Directory. Some IdP's may require an update, refresh, or redeploy after adjusting certain attributes. If you make an adjustment and it is not reflected in your SAML capture, refer to your IdP's documentation or support program regarding the specific steps required to make the change take effect.
# Specify Active Directory details for your WorkSpaces Pools directory
In this topic, we show you how to specify your Active Directory (AD) details within the **Create WorkSpaces Pool directory** page of the WorkSpaces console. As you create your WorkSpaces Pool directory, you should specify your AD details if you plan to use an AD with your WorkSpaces Pools. You cannot edit the **Active Directory Config** for your WorkSpaces Pools directory after you create it. Following is an example of the **Active Directory Config** section of the **Create WorkSpaces Pool directory** page.
![\[The Active Directory Config section of the Create WorkSpaces Pool directory page\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/pools-wsp-active-directory-config.png)
**Note**
The full process for creating a WorkSpaces Pool directory is outlined in the [Configure SAML 2.0 and create a WorkSpaces Pools directory](create-directory-pools.md) topic. The procedures outlined on this page represent only a subset of steps of the full process to create a WorkSpaces Pool directory.
**Topics**
+ [Specify the organization unit and directory domain name for your AD](#pools-specify-ou-and-directory-domain)
+ [Specify the service account for your AD](#pools-specify-access-account)
## Specify the organization unit and directory domain name for your AD
Complete the following procedure to specify an organizational unit (OU) and a directory domain name for your AD in the **Create a WorkSpaces Pool directory** page.
1. For **Organization Unit**, enter the OU that the pool belongs to. WorkSpace machine accounts are placed in the organizational unit (OU) that you specify for the WorkSpaces Pool directory.
**Note**
The OU name can't contain spaces. If you specify an OU name that contains spaces, when it attempts to rejoin the Active Directory domain, WorkSpaces cannot cycle the computer objects correctly and the domain rejoin doesn't work.
1. For **Directory domain name**, enter the fully qualified domain name (FQDN) of the Active Directory domain (for example, `corp.example.com`). Each AWS Region can have only one directory config value with a specific directory name.
+ You can join your WorkSpaces Pool directories to domains in Microsoft Active Directory. You can also use your existing Active Directory domains, either cloud-based or on-premises, to launch domain-joined WorkSpaces.
+ You can also use AWS Directory Service for Microsoft Active Directory, also known as AWS Managed Microsoft AD, to create an Active Directory domain. Then, you can use that domain to support your WorkSpaces resources.
+ By joining WorkSpaces to your Active Directory domain, you can:
+ Allow your users and applications to access Active Directory resources, such as printers and file shares from streaming sessions.
+ Use Group Policy settings that are available in the Group Policy Management Console (GPMC) to define the end user experience.
+ Stream applications that require users to be authenticated using their Active Directory login credentials.
+ Apply your enterprise compliance and security policies to your WorkSpaces streaming instances.
1. For **Service account**, continue to the [Specify the service account for your AD](#pools-specify-access-account) next section of this page.
## Specify the service account for your AD
When you configure Active Directory (AD) for your WorkSpaces Pools as part of the directory creation process, you must specify the AD service account to be used for managing the AD. This requires that you provide the service account credentials, which must be stored in AWS Secrets Manager and encrypted using a AWS Key Management Service (AWS KMS) customer managed key. In this section, we show you how to create the AWS KMS customer managed key and the Secrets Manager secret to store your AD service account credentials.
### Step 1: Create an AWS KMS customer managed key
Complete the following procedure to create an AWS KMS customer managed key
1. Open the AWS KMS console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. Choose **Create a key**, and then choose **Next**.
1. Choose **Symetric** for the key type, and **Encrypt and decrypt** for the key usage, and then choose **Next**.
1. Enter an alias for the key, such as `WorkSpacesPoolDomainSecretKey`, and then choose **Next**.
1. Don't choose a key administrator. Choose **Next** to continue.
1. Don't define key usage permissions. Choose **Next** to continue.
1. In the Key policy section of the page, add the following:
```
{
"Sid": "Allow access for Workspaces SP",
"Effect": "Allow",
"Principal": {
"Service": "workspaces.amazonaws.com"
},
"Action": "kms:Decrypt",
"Resource": "*"
}
```
The result should appear like the following example.
![\[An example of a AWS KMS key policy.\]](http://docs.aws.amazon.com/workspaces/latest/adminguide/images/kms-key-policy-for-wsp-pools-service-account.png)
1. Choose **Finish**.
Your AWS KMS customer managed key is now ready to be used with Secrets Manager. Continue to the [Step 2: Create Secrets Manager secret to store your AD service account credentials](#pools-create-asm-secret) section of this page.
### Step 2: Create Secrets Manager secret to store your AD service account credentials
Complete the following procedure to create a Secrets Manager secret to store your AD service account credentials.
1. Open the AWS Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).
1. Choose **Create a new secret**.
1. Choose **Other type of secret**.
1. For the first key/value pair, enter `Service Account Name` for the key, and the name of the service account for the value, such as `domain\username`.
1. For the second key/value pair, enter a `Service Account Password` for the key, and the password of the service account for the value.
1. For the encryption key, choose the AWS KMS customer managed key that you created earlier, and then choose **Next**.
1. Enter a name for the secret, such as `WorkSpacesPoolDomainSecretAD`.
1. Choose **Edit permissions** in the **Resource permissions** section of the page.
1. Enter the following permission policy:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"workspaces.amazonaws.com"
]
},
"Action": "secretsmanager:GetSecretValue",
"Resource": "*"
}
]
}
```
------
1. Choose **Save** to save the permission policy.
1. Choose **Next** to continue.
1. Don't configure automatic rotation. Choose **Next** to continue.
1. Choose **Store** to finish storing your secret.
Your AD service account credentials are now stored in Secrets Manager. Continue to the [Step 3: Select the Secrets Manager secret that contains your AD service account credentails](#continue-creating-pools-directory) section of this page.
### Step 3: Select the Secrets Manager secret that contains your AD service account credentails
Complete the following procedure to select the Secrets Manager secret you created in the Active Directory config for your WorkSpaces Pool directory.
+ For **Service account**, choose the AWS Secrets Manager secret that contains your service account credentials. Complete the following steps to create the secret if you haven't already done so. The secret must be encrypted using a AWS Key Management Service customer managed key.
Now that you've completed all of the fields within the **Active Directory Config** section of the **Create WorkSpaces Pool directory** page, you can continue to finish creating your WorkSpaces Pool directory. Go to [Step 4: Create WorkSpace Pool directory](create-directory-pools.md#saml-directory-create-wsp-pools-directory) and start on step 9 of the procedure.