docs: IDP configuration guide (#569)

* <docs: added hyperlinks in packer readme>

* Revert "<docs: added hyperlinks in packer readme>"

This reverts commit 501b7de.

* docs: idp guide

docs/docs/configuration_guide/activedirectory.md

@@ -0,0 +1,26 @@
+---
+id: activedirectory
+title: Configuring Service Workbench using Microsoft Active Directory
+sidebar_label: Configuring Service Workbench using Microsoft Active Directory
+---
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+### Updating accounts
+
+You can use Microsoft Active Directory to create and manage domains, users, and objects within a network. It provides a way to organize a large number of users into logical groups and subgroups. It also provides access control at each level. For more information about IdPs, see [Identity Providers](https://docs.microsoft.com/en-us/azure/active-directory/external-identities/identity-providers).
+
+Microsoft Active Directory (or any IdP) is a source of authentication. It authenticates users for Service Workbench login. After successful Active Directory login, it sends user information to an Amazon Cognito user pool created by Service Workbench. Service Workbench then uses the Amazon Cognito user pool for its internal use as described in [Service Workbench and IdP workflow](/configuration_guide/workflow).
+
+To configure Active Directory authentication:
+
+1. Create an IdP if you don’t have one. For more information about creating an IdP, see [sign up your organization](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/sign-up-organization).
+2. Download SAML metadata (XML file).
+3. Using Amazon Cognito on the AWS Management Console, create an Amazon Cognito user pool. The name of the pool must be `<stage>-<solution_name>-userPool`, where`stage` and `solution_name` are configured in the main configuration file.
+4. Gather the relying party information, such as `User Pool Id`, `Relying Party Id`, and `User Pool Signing Cert`.
+5. Run the following script from the root of Service Workbench repository: 
+ `scripts/get-relying-party.sh`
+6. Copy the output of this script and provide it to your Active Directory administrator.
+
+<img src={useBaseUrl('img/deployment/post_deployment/scripts.png')} />
+
+**Figure: Script output**

docs/docs/configuration_guide/adfs.md

@@ -0,0 +1,92 @@
+---
+id: adfs
+title: Configuring Service Workbench using Microsoft Active Directory Federation Services
+sidebar_label: Configuring Service Workbench using Microsoft Active Directory Federation Services
+---
+
+Microsoft ADFS is another IdP and it uses SAML 2.0 standard. For SAML federation, the Amazon Cognito user pool is the Service Provider (SP). Mutual trust between the SP and the IdP must be established. Service Workbench on AWS uses Amazon Cognito user pools to federate identities from Microsoft Active Directory using ADFS and SAML 2.0. 
+
+### Creating a Relying Party in Microsoft ADFS
+
+Follow these steps to establish trust from the IdP (Microsoft ADFS) to Service Provider (Amazon Cognito user pool) and create a relying party in Microsoft ADFS. See [Service Workbench and IdP workflow](/configuration_guide/workflow).
+
+#### Establishing trust between Microsoft ADFS (IdP) and Amazon Cognito user pool
+
+1. Log in to your Active Directory domain controller. Type `AD FS` in the **Run** window and open **AD FS 2.0 Management**.
+2. Choose **Add Relying Party Trust**.
+3. Choose **Start** on the **Welcome** screen.
+4. For **Select Data Source**, choose **Enter Data About the Relying Party Manually**.
+5. For **Specify Display Name** pane, enter a display name and relevant notes about the relying party. For example, enter `Amazon Cognito User Pool Relying Party`.
+6. For **Choose Profile**, choose **AD FS 2.0 Profile**.
+7. Do not configure any certificate in the **Configure Certificate** pane. Configuring certificates is for encrypting SAML claims. The SP (that is, the Amazon Cognito user pool) needs a private key to decrypt the claims if you configure a certificate. The Amazon Cognito user pool does not currently support encrypted SAML assertions.
+8. Do not select any option in the **Configure URL** pane. Choose **Next**.
+9. At this point, there is no need to configure anything in the **Configure Identifiers** pane.
+10. In the **Choose Issuance Authorization Rules** pane, choose **Permit All Users to Access this Relying Party**.
+11. For **Ready to Add Trust**, choose **Next**.
+12. For **Finish**, choose **Close**.
+
+#### Configuring IdP attributes
+
+1. Configure the attributes that you want for the SAML assertion. The attributes are read by the Amazon Cognito user pool and aligned to the standard Amazon Cognito attributes from the mapping configuration in Amazon Cognito.
+2. The **Edit Claims** window may already be open from the last wizard. If not, you can open it by choosing the **Edit Claim Rules** link and configure the claims. Add the following claims:
+      + **Name ID** (Optional)
+      + **Name**
+      + **Email**
+      + **Surname**
+      + **Given Name**
+3. For **Name ID** claim, choose **Add Rule**.
+4. Choose **Transform an Incoming Claim**, then choose **Next** and configure the claim.
+5. Follow the same actions from to add the **Name** claim.
+6. To add the **Email** claim, choose **Add Rule**. 
+7. For **Send LDAP Attributes as Claims**, choose **Next** and then configure the claim.
+8. Similarly, add the **Surname** and **Given Name** claims.
+
+### Configuring relying party information in Service Workbench
+
+After creating a relying party in Microsoft ADFS, you can configure it within the Service Workbench. Follow these steps to configure the relying party.
+
+1. Extract the SAML metadata file from Microsoft ADFS. The location of the metadata file might be different depending upon your version of Microsoft AD/ADFS. By default, it is located at:
+
+`https://<DomainControllerDNSName>/FederationMetadata/2007-06/FederationMetadata.xml`
+
+2. Copy the metadata file and place it at the following location: 
+
+`/solution/post-deployment/config/saml-metadata/metadata.xml`
+
+3. Modify the component-specific settings file for post-deployment.
+
+`/solution/post-deployment/config/settings/<your-environment-name>.yml`
+
+4. Enter the following `fedIdpMetadatas` settings:
+
+`fedIdpMetadatas: '["s3://${self:custom.settings.namespace}-artifacts/saml-metadata/metadata.xml"]'`
+
+### Adding relying party trust for the Amazon Cognito user pool in Microsoft ADFS
+
+After you have deployed the solution, an Amazon Cognito user pool is created. Follow these steps to add relying party trust for the Amazon Cognito user pool:
+
+1. Sign in to the AWS Management Console and navigate to Amazon Cognito.
+2. Choose User Pool to see a user pool for your environment. The Amazon Cognito user pool is specified in the following format:
+`envName-solutionName-userpool`
+where, `envName` and `solutionName` denote the values specified in your settings file.
+3. Choose the user pool for your environment and note the following values:
+      + **User Pool ID**: Copy the value for **Pool ID**. 
+      + **Domain Prefix**: Navigate to **App Integration domain Name** for your user pool and copy the value of the **Prefix** domain.
+4. Log in to Microsoft ADFS domain controller and add the Amazon Cognito user pool-related information.
+      <ol type="a">
+      <li>Open the Microsoft ADFS Management application.</li>
+      <li> Navigate to <b>Relying Party Trusts</b>.</li>
+      <li> To add trust, choose the appropriate relying party.</li>
+      <li> Open the <b>Identifiers</b> tab. </li>
+      <li> Enter the URN of the Amazon Cognito User Pool and choose <b>Add</b>.</li>
+      </ol>
+
+5. Replace the `userPoolId` with the value of the user pool ID you obtained earlier. The URN has the following format: 
+     `urn:amazon:cognito:sp:userPoolId`
+6. Open the **Endpoints** tab and add the SP URL that receives the SAML assertion from the IdP. The SP is the consumer of the Amazon Cognito SAML assertion. 
+7. Replace `userPoolDomain` with the value of the `Prefix` domain. 
+8. Replace `region` with the region in which you deployed the solution. The URL is in the following format: 
+
+     `https://<userPoolDomain>.auth.<region>.amazoncognito.com/saml2/idpresponse`
+
+You should now be able to log in to Service Workbench using Microsoft Active Directory credentials.

docs/docs/configuration_guide/auth0.md

@@ -0,0 +1,111 @@
+---
+id: auth0
+title: Configuring Service Workbench using Auth0
+sidebar_label: Configuring Service Workbench using Auth0
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+You can configure Service Workbench using Auth0 by first creating an application in Auth0. Next, configure SAML and download the SAML template. Finally, configure the Service Workbench environment.
+
+## Configuring Auth0
+
+Auth0 is another IdP, which used for adding authentication and authorization to your applications. Service Workbench on AWS can be configured to authenticate users through Auth0 and SAML2. For more information about using Auth0, see [Test SAML SSO with Auth0 as Service Provider and Identity Provider](https://auth0.com/docs/protocols/saml-protocol/configure-auth0-as-service-and-identity-provider). 
+
+### Prerequisites
+
+You must have an existing account with [Auth0](https://auth0.com/). 
+
+### Creating an application using Auth0
+
+To create an application:
+
+1. Log in to your [Auth0](https://auth0.com/) account and navigate to the **Applications** page. 
+2. If an application does not already exist, choose **Create Application**.
+
+<img src={useBaseUrl('img/deployment/post_deployment/auth01.png')} /> 
+
+
+**Figure 1: Applications webpage of Auth0.com**
+
+3. Select the application type as **Single Page Web Applications** and choose **Create**.
+
+<img src={useBaseUrl('img/deployment/post_deployment/auth02.png')} /> 
+
+
+**Figure 2: Application types**
+
+## Configuring SAML2
+
+SAML is an XML-based open standard for transferring identity data between two parties: an identity provider (IdP) and a service provider (SP). For more information about SAML authentication, see [How does SAML Authentication Work?](https://auth0.com/blog/how-saml-authentication-works/#How-does-SAML-Authentication-Work-)
+
+To configure SAML2: 
+
+1. Navigate to the **Addons** tab and enable **SAML2 WEB APP**.
+
+<img src={useBaseUrl('img/deployment/post_deployment/auth03.png')} /> 
+
+**Figure 3: Addons tab for Single Page Web Applications**
+
+2. In the **Application Callback URL** field, enter the following URL. Replace `STAGE_NAME` and `SOLUTION_NAME` with the values from the Service Workbench settings file and `REGION` with the appropriate region.
+
+`https://STAGE_NAME-SOLUTION_NAME.auth.REGION.amazoncognito.com/saml2/idpresponse`
+
+<img src={useBaseUrl('img/deployment/post_deployment/auth04.png')} /> 
+
+**Figure 4: Application callback URL page and settings**
+
+3. Enter the JSON code into the settings block and  replace `<USER_POOL_ID>` with the Service Workbench Amazon Cognito user pool ID value found in the Amazon Cognito console. 
+
+4. Enter same values for the `<STAGE_NAME>`, `<SOLUTION_NAME>`, and `<REGION>` as in the previous step. 
+5. After entering JSON with the appropriate values, scroll to the bottom and choose **Save**.
+
+```
+{
+"audience": "urn:amazon:cognito:sp:USER_POOL_ID",
+"Mappings": {
+"Email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+"name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
+"given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
+"family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
+},
+"logout": {
+"callback": "https://STAGE_NAME-SOLUTION_NAME.auth.REGION.amazoncognito.com/saml2/logout"
+},
+"nameIdentifierFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
+}
+```
+For more information about IdP workflow, see [Service Workbench and IdP workflow](/configuration_guide/workflow).
+
+## Downloading SAML2 template
+
+To download SAML metadata:
+
+1. Choose **SAML2 Web App** again, and go to the **Usage** tab. 
+2. Choose **Download** to download the SAML metadata XML file locally.
+
+<img src={useBaseUrl('img/deployment/post_deployment/auth05.png')} /> 
+
+**Figure 5: Usage tab of the SAML2 web application**
+
+3. Rename and place the downloaded file in the repository at the following location:
+
+`main/solution/post-demployment/config/saml-metadata/auth0_com-metadata.xml`
+
+## Configuring Service Workbench environment
+
+Add the following items to the `$STAGE.yml` settings file for the environment (replace `DOMAIN` with your Auth0 domain).
+
+```
+fedIdpIds: '["Domain"]'
+fedIdpNames: '["Auth0"]'
+fedIdpDisplayNames: '["Auth0"]'
+fedIdpMetadatas: '["s3://${self:custom.settings.deploymentBucketName}/saml-metadata/auth0_com-metadata.xml"]'
+```
+Finally, redeploy the system using the `scripts/environment-deploy.sh STAGE_NAME` command.
+The reference documentation can be found [here](https://aws.amazon.com/premiumsupport/knowledge-center/auth0-saml-cognito-user-pool/).
+
+## References:
+
++ [Integrating Third-Party SAML Identity Providers](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-integrating-3rd-party-saml-providers.html)
++ [Adding SAML IdPs to a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-saml-idp.html)

docs/docs/configuration_guide/overview.md

@@ -0,0 +1,18 @@
+---
+id: overview
+title: Identity Provider overview
+sidebar_label: Identity Provider overview
+---
+
+An identity provider (IdP) is a service that stores, manages digital identities and verifies the identities of users. The IdP can be used in place of internal authentication mechanism of Service Workbench. The IdP authenticates the identity of a user, allowing Service Workbench to assign permissions to that user.
+
+In an IdP workflow, user login is performed by an external identify provider. Examples of these include Amazon SSO, other SAML-2.0 identity providers such as Microsoft Active Directory, or social connections. After your identity is verified by the IdP, Service Workbench assigns you the rights to access the resources for which you are authorized. Some examples of IdPs are Auth0, Microsoft Active Directory, Microsoft Active Directory Federation Services (ADFS), and so on. For more information about IdPs, see [Identity Providers for external entities](https://docs.microsoft.com/en-us/azure/active-directory/external-identities/identity-providers).
+
+## Prerequisites for configuring an IdP
+
+- Create a SAML 2.0-compliant metadata file using IdP. Place the metadata file here:
+ `main/solution/post-deployment/config/saml-metadata`
+- Enter the following values in your `main/config/settings/<stage.yml>`:
+ `fedIdpIds`, `fedIdpNames`, `fedIdpDisplayNames`, `fedIdpMetadatas`
+  Examples for these are available in `main/config/settings/example.yml`
+- Deploy Service Workbench

docs/docs/configuration_guide/workflow.md

@@ -0,0 +1,23 @@
+---
+id: workflow
+title: Service Workbench and IdP workflow
+sidebar_label: Service Workbench and IdP workflow
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+### Service Workbench and IdP workflow
+
+While using Service Workbench, you are redirected to the configured IdP login page. Next, the IdP can authenticate using any backend authentication connection, such as an LDAP directory, or a database. The IdP data is then provided by Amazon Cognito user pool. Once you are authenticated, the IdP returns a Security Assertion Markup Language (SAML) metadata file to Service Workbench indicating that you have been successfully authenticated. It then provides user details (such as, name, email etc.) as shown below.
+
+<img src={useBaseUrl('img/deployment/post_deployment/idp_workflow.png')} />
+
+**Figure: IdP workflow using Service Workbench**
+
+## Advantages of configuring Service Workbench using IdP
+
+When Service Workbench is configured using an IdP, the login process is streamlined by allowing authentication federation and single sign-on (SSO) compatibility. Therefore, you can use an existing identity (and password) to log in. It also reduces the need to create custom logins and tracks user activity. Using IdP, a single login provides all data at one go.
+You can access Service Workbench from a variety of devices, locations, and time zones. An IdP manages those details efficiently.
+
+
+

docs/docs/deployment/deployment_stages.md

@@ -8,7 +8,7 @@ sidebar_label: Deployment Stages
 
 The Service Workbench deployment is categorized into the following stages:
 
-1. [Pre Deployment](deployment/pre_deployment/predeployment)
+1. [Pre Deployment](/deployment/pre_deployment/pre_deployment/)
 
 2. [Deploying Service Workbench](/deployment/deployment/index)
 

docs/docs/deployment/post_deployment/aws_accounts.md

@@ -52,14 +52,15 @@ To create the account, perform the following actions:
 1. In the Service Workbench console, navigate to '**Accounts → AWS Accounts**' and click **Create AWS Account**.
     *  In **Role ARN**, fill in the **Master Role ARN** copied from the ‘Configure Master Account’ step described above.
     * The email address that you specify here must be unique within the Organization.
-    * The **External ID** by default is the string **workbench**.  See  [IAM](/development/aws_services#IAM) for information on how to configure this to another value.
+    * The **External ID** by default is the string **workbench**.  See  [IAM](/deployment/reference/aws_services#IAM) for information on how to configure this to another value.
 2. After a minute, the following information displays in the **AWS Accounts** tab:
     *  *‘Trying to create accountID: xxx’*
     * A workflow in progress in **Workflows → Provision Account** (see [Workflows](http://swb-documentation.s3-website-us-east-1.amazonaws.com/user_guide/sidebar/admin/workflows/introduction) 
-     _**Note**: If instead you see an error message such as, ‘Stop Internal State Account ID not found’, check that there is an AWS Organization in the console of your **Master** account, if deploying Service Workbench in the **Master** account.  If you are deploying in a **Member** account, check and ensure that you  followed the steps described in [Prepare the Master Account](/deployment/post_deployment/prepare_master_account)._
+
+     _**Note**: If instead you see an error message such as, ‘Stop Internal State Account ID not found’, check that there is an AWS Organization in the console of your **Master** account, if deploying Service Workbench in the **Master** account.  If you are deploying in a **Member** account, check and ensure that you  followed the steps described in [Prepare the Master Account](/deployment/reference/prepare_master_account)._
     * Optionally, in the AWS console, you can inspect the following resources deployed by this script:
         * In AWS CloudFormation, a stack **prep-master** will be running.  It creates the **Master** role and its output is the **Master Role ARN**.
-        * In the AWS Organization, in the **Master** account (see [IAM](/development/aws_services#Organizations)), the new account will display. 
+        * In the AWS Organization, in the **Master** account (see [IAM](/deployment/reference/aws_services#Organizations), the new account will display. 
         * In IAM, the new **Master** role will be created
 3. Once the account is created it will be listed in **AWS Accounts**, see **Figure 2**.