# Choosing the identity provider type for Amazon WorkSpaces Secure Browser
<a name="choose-type"></a>

WorkSpaces Secure Browser offers two authentication types: **Standard** and **AWS IAM Identity Center**. You choose the authentication type to use with your portal on the **Configure identity provider page**. 
+ For **Standard** (default option), federate your 3rd party SAML 2.0 identity provider (such as Okta or Ping) directly with your portal. For more information, see [Configuring the standard authentication type for Amazon WorkSpaces Secure Browser](configure-standard.md). The standard type supports both SP-initiated and IdP-initiated authentication flows.
+ For **IAM Identity Center** (advanced option), federate the IAM Identity Center with your portal. To use this authentication type, your IAM Identity Center and WorkSpaces Secure Browser portal must both reside in the same AWS Region. For more information, see [Configuring the IAM Identity Center authentication type for Amazon WorkSpaces Secure Browser](configure-iam.md).

**Topics**
+ [Configuring the standard authentication type for Amazon WorkSpaces Secure Browser](configure-standard.md)
+ [Configuring the IAM Identity Center authentication type for Amazon WorkSpaces Secure Browser](configure-iam.md)

# Configuring the standard authentication type for Amazon WorkSpaces Secure Browser
<a name="configure-standard"></a>

The *standard* authentication type is the default authentication type. It can support service provider-initiated (SP-initiated) and identity provider-initiated (IdP-initiated) sign-in flows with your SAML 2.0 compliant IdP. To configure the standard authentication type, follow the steps below to federate your third-party SAML 2.0 IdP (such as Okta or Ping) directly with your portal.

**Topics**
+ [Configuring your identity provider on Amazon WorkSpaces Secure Browser](configure-idp-step1.md)
+ [Configuring your IdP on your own IdP](configure-idp-step2.md)
+ [Finishing IdP configuration on Amazon WorkSpaces Secure Browser](upload-metadata.md)
+ [Guidance for using specific IdPs with Amazon WorkSpaces Secure Browser](idp-guidance.md)

# Configuring your identity provider on Amazon WorkSpaces Secure Browser
<a name="configure-idp-step1"></a>

Complete the following steps to configure your identity provider:

1. On the **Configure identity provider page** of the creation wizard, choose **Standard**.

1. Choose **Continue with Standard IdP**.

1. Download the SP metadata file, and keep the tab open for individual metadata values.
   + If the SP metadata file is available, choose **Download metadata file** to download the service provider (SP) metadata document, and upload the service provider metadata file to your IdP in the next step. Without this, users won't be able to sign in.
   + If your provider doesn't upload SP metadata files, manually enter the metadata values.

1. Under **Choose SAML sign-in type**, choose between **SP-initiated and IdP-initiated SAML assertions**, or **SP-initiated SAML assertions only**.
   + **SP-initiated and IdP-initiated SAML assertions** allow your portal to support both types of sign-in flows. Portals that support IdP-initiated flows allow you to present SAML assertions to the service identity federation endpoint without requiring users to launch a session by visiting the portal URL. 
     + Choose this to allow the portal to accept unsolicited IdP-initiated SAML assertions. 
     + This option requires a **default Relay State** to be configured in your SAML 2.0 Identity Provider. The Relay state parameter for your portal is in the console under **IdP initiated SAML sign in**, or you can copy it from the SP metadata file under `<md:IdPInitRelayState>`.
     +  Note
       + The following is the format of the relay state: `redirect_uri=https%3A%2F%2Fportal-id.workspaces-web.com%2Fsso&response_type=code&client_id=1example23456789&identity_provider=Example-Identity-Provider`. 
       + If you copy and paste the value from the SP metadata file, make sure that you change `&amp; `to `&`. `&amp;` is an XML escape character.
   + Choose **SP-initiated SAML assertions only** for the portal to only support SP-initiated sign in flows. This option will reject unsolicited SAML assertions from IdP-initiated sign-in flows. 
**Note**  
Some third-party IdPs allow you to create a custom SAML application that can deliver IdP-initiated authentication experiences leveraging SP-initiated flows. For example, see [Add an Okta bookmark application](https://help.okta.com/oag/en-us/content/topics/access-gateway/add-app-saml-pass-thru-add-bookmark.htm).

1. Choose whether you want to enable **Sign SAML requests to this provider**. SP-initiated authentication allows your IdP to validate that the authentication request is coming from the portal, which prevents accepting other third-party requests. 

   1. Download the signing certificate and upload it to your IdP. The same signing certificate can be used for single logout.

   1. Enable signed request in your IdP. The name might be different, depending on the IdP.
**Note**  
RSA-SHA256 is the only request and default request signing algorithm supported.

1. Choose whether you want to enable **Require encrypted SAML assertions**. This allows you to encrypt the SAML assertion that comes from your IdP. It can prevent data from being intercepted in SAML assertions between the IdP and WorkSpaces Secure Browser.
**Note**  
The encryption certificate is not available at this step. It will be created after your portal launches. After you launch the portal, download the encryption certificate and upload it to your IdP. Then, enable assertion encryption in your IdP (the name might be different, depending on the IdP. 

1. Choose whether you want to enable **Single Logout**. Single logout allows your end users to sign out of both their IdP and WorkSpaces Secure Browser session with a single action.

   1. Download the signing certificate from WorkSpaces Secure Browser and upload it onto your IdP. This is the same signing certificate used for **Request Signing** in the previous step.

   1. Using **Single Logout** requires you to configure a **Single Logout URL** in your SAML 2.0 identity provider. You can find the **Single Logout URL** for your portal in the console under **Service provider (SP) details - Show individual metadata values**, or from the SP metadata file under `<md:SingleLogoutService>` . 

   1. Enable **Single Logout** in your IdP. The name might be different, depending on the IdP. 

# Configuring your IdP on your own IdP
<a name="configure-idp-step2"></a>

To configure your IdP on your own IdP, follow these steps.

1. Open a new tab in your browser.

1. Add your portal metadata to your SAML IdP.

   Either upload the SP metadata document that you downloaded in the previous step to your IdP, or copy and paste the metadata values into the correct fields in your IdP. Some providers do not allow file upload.

   The details of this process can vary between providers. Find your provider's documentation in [Guidance for using specific IdPs with Amazon WorkSpaces Secure Browser](idp-guidance.md) for help on how to add the portal details to your IdP configuration.

1. Confirm the **NameID** for your SAML assertion.

   Make sure your SAML IdP populates **NameID** in the SAML assertion with the user email field. **NameID** and user email are used for uniquely identifying your SAML federated user with the portal. Use the persistent SAML Name ID format.

1. Optional: Configure the **Relay State** for IdP-initiated authentication.

   If you chose **Accept SP-initiated and IdP-initiated SAML assertions** in the previous step, follow steps in step 2 of [Configuring your identity provider on Amazon WorkSpaces Secure Browser](configure-idp-step1.md) to set the default **Relay State** for your IdP application. 

1. Optional: Configure **Request signing**. If you chose **Sign SAML requests to this provider** in the previous step, follow steps in step 3 of [Configuring your identity provider on Amazon WorkSpaces Secure Browser](configure-idp-step1.md) to upload the signing certificate onto your IdP and enable request signing. Some IdPs such as Okta might require your **NameID** to belong to the “persistent” type to use **Request signing**. Make sure to confirm your **NameID** for your SAML assertion by following the steps above.

1. Optional: Configure **Assertion encryption**. If you chose **Require encrypted SAML assertions from this provider**, wait until portal creation is complete, then follow step 4 in "Upload metadata" below to upload the encryption certificate onto your IdP and enable assertion encryption.

1. Optional: Configure **Single Logout**. If you chose **Single Logout**, follow the steps in step 5 of [Configuring your identity provider on Amazon WorkSpaces Secure Browser](configure-idp-step1.md) to upload the signing certificate onto your IdP, fill in **Single Logout URL**, and enable **Single Logout**.

1. Grant access to your users in your IdP to use WorkSpaces Secure Browser.

1. Download a metadata exchange file from your IdP. You will upload this metadata to WorkSpaces Secure Browser in the next step.

# Finishing IdP configuration on Amazon WorkSpaces Secure Browser
<a name="upload-metadata"></a>

To finish IdP configuration on WorkSpaces Secure Browser follow these steps.

1. Return to the WorkSpaces Secure Browserconsole. On the **Configure identity provider page** of the creation wizard, under **IdP metadata**, either upload a metadata file, or enter a metadata URL from your IdP. The portal uses this metadata from your IdP to establish trust.

1. To upload a metadata file, under **IdP metadata document**, choose **Choose file**. Upload the XML-formatted metadata file from your IdP that you downloaded in the previous step. 

1. To use a metadata URL, go to your IdP that you set up in the previous step and obtain its **Metadata URL**. Go back to the WorkSpaces Secure Browser console, and under **IdP metadata URL**, enter the metadata url that you obtained from your IdP. 

1. When you are done, choose **Next**.

1. For portals where you have enabled the **Require encrypted SAML assertions from this provider** option, you need to download the encryption certificate from the portal IdP details section and upload it onto your IdP. Then, you can enable the option there.
**Note**  
WorkSpaces Secure Browser requires the subject or NameID to be mapped and set in the SAML assertion within your IdP's settings. Your IdP can create these mappings automatically. If these mappings aren't configured correctly, your users can't sign in to the web portal and start a session.  
WorkSpaces Secure Browser requires the following claims to be present in the SAML response. You can find *<Your SP Entity ID>* and *<Your SP ACS URL>* from your portal’s service provider details or metadata document, either through the console or the CLI.  
An `AudienceRestriction` claim with an `Audience` value that sets your SP Entity ID as the target of the response. Example:  

     ```
     <saml:AudienceRestriction>
         <saml:Audience><Your SP Entity ID></saml:Audience>
     </saml:AudienceRestriction>
     ```
A `Response` claim with an `InResponseTo` value of the original SAML request ID. Example:  

     ```
     <samlp:Response ... InResponseTo="<originalSAMLrequestId>">
     ```
A `SubjectConfirmationData` claim with a `Recipient` value of your SP ACS URL, and an `InResponseTo` value that matches the original SAML request ID. Example:  

     ```
     <saml:SubjectConfirmation>
         <saml:SubjectConfirmationData ... 
             Recipient="<Your SP ACS URL>"
             InResponseTo="<originalSAMLrequestId>"
             />
     </saml:SubjectConfirmation>
     ```
WorkSpaces Secure Browser validates your request parameters and SAML assertions. For IdP-initiated SAML assertions, the details of your request must be formatted as a `RelayState` parameter in the body of an HTTP POST request. The request body must also contain your SAML assertion as a `SAMLResponse` parameter. Both of these should be present if you have followed the previous step.  
The following is an example `POST` body for an IdP-initiated SAML provider.  

   ```
   SAMLResponse=<Base64-encoded SAML assertion>&RelayState=<RelayState> 
   ```

# Guidance for using specific IdPs with Amazon WorkSpaces Secure Browser
<a name="idp-guidance"></a>

To make sure you correctly configure the SAML federation for your portal, see the links below for documentation from commonly used IdPs. 


| IdP | SAML application setup | User management | IdP-initiated auth | Request signing | Assertion encryption | Single logout | 
| --- | --- | --- | --- | --- | --- | --- | 
| Okta | [Create SAML app integrations](https://help.okta.com/oie/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm) | [User management](https://help.okta.com/oie/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm) | [Application Integration Wizard SAML field reference](https://help.okta.com/oie/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm) | [Application Integration Wizard SAML field reference](https://help.okta.com/oie/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm) | [Application Integration Wizard SAML field reference](https://help.okta.com/oie/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm) | [Application Integration Wizard SAML field reference](https://help.okta.com/oie/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm) | 
| Entra | [Create your own application](https://help.okta.com/oie/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm) | [Quickstart: Create and assign a user account](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-assign-users) | [Enable single sign-on for an enterprise application](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso) | [SAML Request Signature Verification](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/howto-enforce-signed-saml-authentication) | [Configure Microsoft Entra SAML token encryption](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/howto-saml-token-encryption?tabs=azure-portal) | [Single Sign-Out SAML Protocol](https://learn.microsoft.com/en-us/entra/identity-platform/single-sign-out-saml-protocol) | 
| Ping | [Add a SAML application](https://docs.pingidentity.com/r/en-us/pingone/pingone_p1tutorial_add_a_saml_app) | [Users](https://docs.pingidentity.com/r/en-us/pingone/p1_c_aboutusers) | [Enabling IdP-initiated SSO](https://docs.pingidentity.com/r/en-us/pingone/pingone_configuring_the_oidc_application) | [Configuring authentication request signing in PingOne for Enterprise](https://docs.pingidentity.com/r/en-us/solution-guides/htg_config_authn_req_sign_p14e) | [Does PingOne for Enterprise support encryption?](https://support.pingidentity.com/s/article/Does-PingOne-support-encryption) | [SAML 2.0 single logout](https://docs.pingidentity.com/r/en-us/pingone/pingone_c_saml_2-0_slo?tocId=aKUl0dlpyVDVw3PJmLIGGg) | 
| One Login | [SAML Custom Connector (Advanced) (4266907)](https://support.onelogin.com/kb/4266907/saml-custom-connector-advanced) | [Add Users to OneLogin Manually](https://www.onelogin.com/getting-started/free-trial-plan/add-users-manually) | [SAML Custom Connector (Advanced) (4266907)](https://support.onelogin.com/kb/4266907/saml-custom-connector-advanced) | [SAML Custom Connector (Advanced) (4266907)](https://support.onelogin.com/kb/4266907/saml-custom-connector-advanced) | [SAML Custom Connector (Advanced) (4266907)](https://support.onelogin.com/kb/4266907/saml-custom-connector-advanced) | [SAML Custom Connector (Advanced) (4266907)](https://support.onelogin.com/kb/4266907/saml-custom-connector-advanced) | 
| IAM Identity Center | [Set up your own SAML 2.0 application](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-saml2-setup.html#customermanagedapps-set-up-your-own-app-saml2) | [Set up your own SAML 2.0 application](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-saml2-setup.html#customermanagedapps-set-up-your-own-app-saml2) | [Set up your own SAML 2.0 application](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-saml2-setup.html#customermanagedapps-set-up-your-own-app-saml2) | N/A | N/A | N/A | 

# Configuring the IAM Identity Center authentication type for Amazon WorkSpaces Secure Browser
<a name="configure-iam"></a>

For the **IAM Identity Center** type (advanced), you federate IAM Identity Center with your portal. Only select this option if the following applies to you:
+ Your IAM Identity Center is configured in the same AWS account and AWS Region as your web portal.
+ If you are using AWS Organizations, you are using a management account. 

Before creating a web portal with the IAM Identity Center authentication type, you must set up IAM Identity Center as a standalone provider. For more information, see [Get started with common tasks in IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html). Or, you can connect your SAML 2.0 IdP to IAM Identity Center. For more information, see [Connect to an external identity provider](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html). Otherwise, you won't have any users or groups to assign to your web portal.

If you are already using IAM Identity Center, you can choose IAM Identity Center as a provider type and follow the steps below to add, view, or remove users or groups from your web portal.

**Note**  
In order to use this authentication type, your IAM Identity Center needs to be in the same AWS account and AWS Region as your WorkSpaces Secure Browser portal. If your IAM Identity Center is in a separate AWS account or AWS Region, follow the instructions for the **Standard** authentication type. For more information, see [Configuring the standard authentication type for Amazon WorkSpaces Secure Browser](configure-standard.md).  
If you're using AWS Organizations, you can only create WorkSpaces Secure Browser portals integrated with IAM Identity Center using a management account.

**Topics**
+ [Creating a web portal with IAM Identity Center](web-portal-IAM.md)
+ [Managing your web portal with IAM Identity Center](manage-IAM.md)
+ [Adding additional users and groups to a web portal](add-users-groups.md)
+ [Viewing or removing users and groups for your web portal](remove-users-groups.md)

# Creating a web portal with IAM Identity Center
<a name="web-portal-IAM"></a>

To create a web portal with IAM Identity Center, follow these steps.

**To create a web portal with IAM Identity Center**

1. During portal creation at **Step 4: Configure identity provider**, choose **AWS IAM Identity Center**.

1. Choose **Continue with IAM Identity Center**.

1. On the **Assign users and groups** page, choose the **Users** and/or **Groups** tab.

1. Check the box next to the user(s) or group(s) that you want to add to the portal.

1. After you create your portal, the users that you associated can sign into WorkSpaces Secure Browser with their IAM Identity Center user name and password.

# Managing your web portal with IAM Identity Center
<a name="manage-IAM"></a>

To manage your web portal with IAM Identity Center, follow these steps.

**To manage your web portal with IAM Identity Center**

1. After you create your portal, it is listed in the IAM Identity Center console as a configured application.

1. To access this application’s configuration, choose **Applications** in the sidebar, and look for a configured application with a name that matches the display name for your web portal.
**Note**  
If you haven’t entered a display name, your portal’s GUID is shown instead. The GUID is the ID that is prefixed to your web portal’s endpoint URL.

# Adding additional users and groups to a web portal
<a name="add-users-groups"></a>

To add additional users and groups to an existing web portal, follow these steps.

**To add additional users and groups to an existing web portal**

1. Open the WorkSpaces Secure Browser console at [https://console.aws.amazon.com/workspaces-web/home?region=us-east-1#/](https://console.aws.amazon.com/workspaces-web/home?region=us-east-1#/).

1. Choose **WorkSpaces Secure Browser**, **Web portals**, choose your web portal, and then choose **Edit**.

1. Choose **Identity provider settings** and **Assign additional users and groups**. From here, you can add users and groups to your web portal.
**Note**  
You can't add users or groups from the IAM Identity Center console. You must do this from the edit page of your WorkSpaces Secure Browser portal.

# Viewing or removing users and groups for your web portal
<a name="remove-users-groups"></a>

To view or remove users and groups for your web portal, use the actions available in the **Assigned users **table. For more information, see [Manage access to applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-applications.html)

**Note**  
You can't view or remove users and groups from the edit page of the WorkSpaces Secure Browserportal. You must do this from the edit page of your IAM Identity Center console.