Enable federation with Bio-key PortalGuard and Amazon AppStream 2.0

In this blog, we will walk through the steps to configure BIO-key PortalGuard for federated logins to Amazon AppStream 2.0.

If you are not using PortalGuard, you can review the documentation for setting up SAML in the AppStream 2.0 Administration Guide. The AppStream 2.0 integration with SAML 2.0 documentation contains links to help you configure AWS Single Sign-On (SSO) and third-party SAML 2.0 identity provider solutions that work with AppStream 2.0.

Solution overview

In order to federate logins with AWS, we will be using the SAML 2.0 standard and IdP-initiated sign-on. The process works as follows:

1. Users of the AppStream 2.0 application will navigate to a link that will take the user to your PortalGuard IdP to complete an IdP-initiated sign-on.
2. PortalGuard will verify the user’s credentials and authorization.
3. Once the user is authenticated, PortalGuard will issue a SAML token to the user.
4. The user’s browser is then automatically forwarded to the AWS sign-In SAML endpoint to complete sign-on.
5. Upon successful validation of the SAML token, the user is granted an AWS IAM role token, which will authorize the user for AppStream 2.0. The user’s browser is then forwarded to the AppStream 2.0 service to begin the session.

Solution architecture

Figure 1: Overview of federated login process

Walkthrough

In this blog, we will walk through the steps to configure AWS Identity and Access Management (IAM) and PortalGuard IdP. The steps are as follows:

1. Create an identity provider in AWS IAM
2. Configure an AWS IAM role for AppStream 2.0
3. Embed an inline policy for the IAM role
4. Configure the relying party in PortalGuard IdP
5. Test the configuration
6. Optional steps

Prerequisites

In order to establish the federated trust between your PortalGuard implementation and Amazon AppStream 2.0, we will need the following components:

• An existing BIO-key PortalGuard identity provider.
• Setup Amazon AppStream 2.0 or a pre-existing stack and fleet.

Step 1: Create an identity provider in AWS IAM

First, we will create an identity provider in AWS IAM. This will allow your AWS account to establish trust with your PortalGuard IdP.

1. To download the XML metadata file for your PortalGuard IdP, navigate to https://<PortalGuardDomain>/SSO/metadata.ashx. If you have an earlier version of PortalGuard, you must rename the downloaded file to have an .xml extension.
2. Navigate to the IAM console.
3. Select Identity providers in the navigation pane.
4. Choose Add provider.
5. On the Add an Identity provider page, set the Provider type to SAML.
6. In the Provider name text box, enter PortalGuard.
7. Select Choose file and select your XML file that you downloaded in the first step.
8. Choose Add provider.

Step 2: Configure the AWS IAM role for AppStream 2.0

Next, we will create an AWS IAM role that will authorize SAML 2.0 authentications to use your AppStream 2.0 resources.

1. Navigate to the IAM console.
2. Select Roles in the navigation pane.
3. Select SAML 2.0 federation as the trusted entity type.
4. Select PortalGuard from the SAML provider drop-down list.
5. Do not select either of the two SAML 2.0 access methods (Allow programmatic access only or Allow programmatic and Amazon Web Services Management Console access).
6. For Attribute, select SAML:sub_type.
7. For Value, enter persistent.
8. Choose Next: Permissions.
9. On the Add tags (optional) screen, choose Next: Review.
10. For Role name, enter PortalGuard-AppStream-Productivity.
11. Choose Create role.

Step 3: Embed an inline policy for the IAM role

Now we need to modify the role to include the necessary permissions to allow your users access to the AppStream 2.0 stack you created.

1. Select the PortalGuard-AppStream-Productivity role in the list of roles.
2. On the Summary page for the new IAM role, choose Add inline policy.
3. Select the JSON tab at the top of the form, and then paste in the following JSON policy text.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "appstream:Stream",
            "Resource": "arn:aws:appstream:REGION-CODE:ACCOUNT-ID:stack/STACK-NAME",
            "Condition": {
                "StringEquals": {
                    "appstream:userId": "${saml:sub}"
                }
            }
        }
    ]
}

4. Update the policy with the following changes:
   2. Replace REGION-CODE with the Region code where your AppStream 2.0 stack is deployed.
   3. Replace ACCOUNT-ID with your account ID.
   4. Replace STACK-NAME with the name of your AppStream 2.0 stack.
5. Choose Review policy.
6. In the Name field, enter PortalGuard-AppStream-Productivity.
7. Choose Create policy.

Step 4: Configure the relying party in PortalGuard

Now that we have completed the AWS configuration, we can complete the configuration of the PortalGuard identity provider. These steps will create a new relying party within your PortalGuard configuration, in order to facilitate the federated single sign-on logins.

1. Download the AWS SAML metadata from https://signin.thinkwithwp.com/static/saml-metadata.xml.
2. Open the PortalGuard Identity Provider Configuration Editor tool for your PortalGuard IdP.
3. On the SAML Websites tab, choose Create to create a new Relying Party. When prompted, select the SAML XML metadata file that you downloaded in step 1 of this section.
4. On the General tab of the Relying Party configuration, enter a Name and Description for the relying party.
5. In the Identifiers field, choose Add. Enter a unique identifier. Identifiers should be URL-friendly strings (e.g. no spaces) since they will appear in IdP-initiated sign-on URLs that you create later.
6. Make sure that Binding is set to POST
7. In the Assertion Consumer URL text box enter https://signin.thinkwithwp.com/saml
8. Clear Use ACS from SAMLRequest?
9. For State, select Enabled.
   
10. In the Relying Party configuration window, select the Identity Claims
11. Choose Create to add a claim. Enter the following:
    1. For Name, enter Name
    2. Select Send As NameID?
    3. For Schema Type, enter urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
    4. For Value Type, select String Field.
    5. In the Direct Field tab, for the Field Name enter userPrincipalName. If userPrincipalName is not a field in your identity store, you can select something else, such as email address.For additional information on valid claim configurations, review setting up SAML in the AppStream 2.0 Administration Guide.
12. Choose Save.
    
13. In the Relying Party configuration window, choose Create to add another claim. Enter the following:
    1. For Name, enter RoleSessionName
    2. For Schema Type, enter https://thinkwithwp.com/SAML/Attributes/RoleSessionName
    3. For Value Type, select String Field.
    4. In the Direct Field tab, for the Field Name enter sAMAccountName.
    5. For the Value Index enter 0.
14. Choose Save.
    
15. In the Relying Party configuration window, choose Create to add the final claim. Enter the following:
    1. For Name, enter
    2. For Schema Type, enter https://thinkwithwp.com/SAML/Attributes/Role
    3. For Value Type, select Formatted String.
    4. For Converted Case, select (No Change).
    5. In the Formatted tab, for the Composite Value Format enter your AWS IAM role ARN for access to AppStream 2.0 and AWS IAM SAML IdP ARN for your PortalGuard IdP separated by a comma. For example, arn:aws:iam:123412341234:role/AppStreamRole,arn:aws:iam:123412341234:saml-provider/PortalGuard
16. Choose Save.
    
17. Select the IdP-Initiated tab.
18. For the Display Text, enter the name you wish for your users to see for the AppStream 2.0 selection in the PortalGuard interface.
19. For the Help Text, enter the mouseover text you wish for your users to see for the AppStream 2.0 selection in the PortalGuard interface.
    
20. Select the Response tab of the Relying Party configuration.
21. Create a Default RelayState The string is formatted as https://appstream2.REGION-CODE.thinkwithwp.com/saml?stack=STACK-NAME&accountId=ACCOUNT-ID
    2. Replace REGION-CODE with the Region code where your AppStream 2.0 stack is deployed.
    3. Replace STACK-NAME with your case specific stack name.
    4. Replace ACCOUNT-ID with your account ID.
22. You can also optionally specify an application on your AppStream 2.0 image that will automatically launch, instead of presenting the user with the application catalog. See Setting Up SAML in the AppStream 2.0 Administration Guide for more details.
23. Once you have configured your Default RelayState, verify the rest of the settings on the Response tab match the screenshot following.
    
24. Save the Relying Party configuration by selecting Save.
25. Select Apply To Identity Provider and follow the prompts to update the configuration of your identity provider.

Step 5: Test the configuration

1. Log in to your PortalGuard IdP as a test user that has access to the AppStream 2.0 application.
2. Select the AppStream 2.0 application.
   
3. You will be taken to the AppStream 2.0 application catalog.
4. Review the AppStream 2.0 General Troubleshooting documentation to address authentication failures.

Step 6: Optional components

Create IdP-initiated sign-on URLs

You can create a link to your AppStream 2.0 stack that authenticates with your PortalGuard IdP. You can put this link in your Wiki, LMS, web portal, or other website. To create this link, use the format https://portalguardidp.mydomain.com/sso/go.ashx?id=<relying party identifier>. For the relying party identifier, use the identifier that you specified for the relying party within Step 4: Configure the relying party in PortalGuard – step 5.

Configure additional AppStream 2.0 use cases

Customers may have more than one AppStream 2.0 stack that they want to make available to their users through SAML 2.0 authentication. You can use application entitlements to control access to specific applications within your AppStream 2.0 stacks. If you have more than one stack with attribute-based application entitlements, you can permit access to multiple stacks from a single relay state URL. For more information, review SAML 2.0 multi-stack application catalog in the AppStream 2.0 Administration Guide.

Require multi-factor authentication

You can require multi-factor authentication (MFA) for access to AppStream 2.0 by selecting Require Multi-Factor Authentication for site access? in the Authorization tab of the Relying Party configuration in PortalGuard.

Restrict access to AppStream 2.0 to specific users or groups

You can restrict access to AppStream 2.0 to specific users or groups by populating the Authorized Users list in the Authorization tab of the Relying Party configuration in PortalGuard. Note that when the Authorized Users list is empty, all authenticated users will be able to access the AppStream 2.0 resources.

Conclusion

In this blog, we walked through configuring federated SAML 2.0 authentication for access to AppStream 2.0 streaming sessions with a PortalGuard identity provider. This included configuration of AWS resources, as well as a new relying party within the PortalGuard configuration.

For more information on configuring AppStream 2.0 refer to the Amazon AppStream 2.0 Administration Guide. This guide includes the setting up SAML documentation which describes all of the prerequisites and steps to configure SAML integration with AppStream 2.0. For more blog posts on AppStream 2.0, see the Amazon AppStream 2.0 blog category.