Appendix B: Federated Template – Okta - Data Lake Solution

Appendix B: Federated Template – Okta

For customers who want to use Okta as a Security Assertion Markup Language 2.0 (SAML 2.0) identity provider (IdP), the resources provisioned by the data-lake-deploy.template can be modified to integrate with Okta. After you deploy the data-lake-deploy.template, use the following procedures to integrate the solution with Okta.

Configure the Okta Account

While the data lake stack launches, you can navigate to the Okta website to configure an Okta account with an Okta application.

Create an account or sign into an existing one

Note

If you already have an Okta account, sign in and and navigate to the Dashboard page. Skip to Create an application.

  1. Navigate to the Okta website and choose Sign Up Today.

  2. In the Free Trial window, enter your contact information and choose Get Started.

    Okta sends a confirmation email to the address you provide.

  3. Use the login information from the confirmation email to sign into your account. You will be prompted to change your password.

Create an application

  1. Select Dashboard to go to the admin dashboard.

  2. On the admin dashboard, under Shortcuts, select Add Applications.

  3. Select Create New App.

  4. In the Create a New Application Integration dialog:

    1. For Platform, select Web.

    2. For Sign on method, select SAML 2.0.

    3. Select Create.

Configure SAML integration for your Okta application

  1. On the Create SAML Integration page, under General Settings, enter a name for your application and choose Next.

  2. Under SAML Settings, do the following:

    1. For Single sign on URL, enter:

      https://<cognito_domain_prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse

      Note

      You can find the Domain prefix in the Amazon Cognito console on the Domain name tab of the management page for your user pool.

    2. For Audience URI (SP Entity ID), enter:

      urn:amazon:cognito:sp:<cognito_user_pool_id>

      Note

      You can find the ID in the Amazon Cognito console on the General settings tab of the management page for your user pool.

  3. Leave Default RelayState blank.

  4. Under Attribute Statements, add the following information:

    • Verify that Name format is set to Unspecified

    • Select Add Another

    • Copy the values from the table below into the corresponding fields:

    Name Value
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname user.lastName
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name user.firstName
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress user.email
  5. Under Group Attribute Statements, add the following information:

    • Verify that the Name format is set to Unspecified

    • Select Add Another

    • Copy the values from the table below to the corresponding fields

    • For Filter, select the drop-down arrow and choose the filter identified in the table and enter the value in the field:

    Name Filter Value
    http://schemas.xmlsoap.org/claims/Group Matches regex .*
    http://schemas.microsoft.com/ws/2008/06/identity/claims/role Equals admin
  6. Select Next.

  7. Under section 3, Help Okta Support, select whether you are a customer or partner.

  8. Select Finish.

Configure users and groups

Note

If you already have users and groups, skip to Assign users to your Okta application.

  1. Under Directory select People.

  2. Select Add Person. In the window, enter the applicable information to add the person.

  3. Under Directory select Groups.

  4. Create the groups and assign users to the groups.

    Members of the admin group will receive administrator access to the solution when they sign in to the console.

Assign users to your Okta application

  1. Under Assignments, Assign select Assign to People.

  2. Next to the user you want to assign, select Assign.

  3. Optional: For User Name, enter a user name, or leave as the user's email address.

  4. Select Save and Go Back.

    Your user is assigned.

  5. Select Done.

Complete Amazon Cognito Federation

After the data lake stack launches and the Okta application is created, you must complete the Amazon Cognito federation configuration.

  1. On the Cognito console, under General settings, Attributes, scroll down to the custom attributes section, select Add another attribute, and add the following custom attribute:

    Type Name Min Length Max Length Mutable
    string groups 1 2048 checked
  2. Select Save changes.

  3. Under General settings, App Clients, locate the data-lake-ui app client and select Show Details.

  4. Select the Set attribute read and write permissions link to access the Attributes section.

  5. Verify that the following readable and writable attributes are checked as listed in the table below (if any of them are not checked, be sure to select them; if other attributes are checked, be sure to uncheck them). Checking these attributes allows the app client to access them.

    Readable Attributes Writable Attributes
    • email

    • family name

    • name

    • custom:display name

    • custom:role

    • custom:accesskey

    • email

    • family name

    • name

    • custom:display name

    • custom:role

    • custom:accesskey

  6. Select Save app client changes.

  7. Under Okta, Sign On, copy the link location of Identity Provider metadata.

  8. Under Federation, Identity providers, set the metadata document using the link copied in the previous step.

  9. Under Federation, Attribute mapping, select the SAML tab and then select Add SAML attribute.

  10. Create the following mappings for the Okta identity provider:

    SAML attribute User pool Attribute
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname Name
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/displayname custom:display_name
    http://schemas.microsoft.com/ws/2008/06/identity/claims/role custom:role
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname Family Name
    http://schemas.xmlsoap.org/claims/Group custom:groups
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress Email
  11. Select Save changes.

  12. Under App integration, App client settings , update App client data-lake-ui settings to use your new identity provider:

    • For Enable Identity Providers, select Okta.

    • For CallBack URL, navigate to the AWS CloudFormation console, open the stack Outputs tab and copy the URL defined in the value of the ConsoleUrl key.

    • For Sign out URL(s): enter

      https://<your_domain>-admin.okta.com/login/admin/signout

    • For Allowed OAuth Flows, select Implicit grant.

    • For Allowed OAuth Scopes, select email, openid, and profile.

  13. Verify your configuration is set up appropriately.

  14. Select Save changes.

  15. Under Federation, Identity providers, select the SAML button.

  16. In the Active SAML Providers section, select Show signing certificate.

  17. Copy the certificate containing the public key. This key will be used by the identity provider to verify the signed logout request to a .cer file (for example, datalake.cer) on your Okta server. Make sure to include the beginning and end tags on the certificate.

    The result should look like this:

    -----BEGIN CERTIFICATE----- (Insert the signing certificate information here) -----END CERTIFICATE-----

Enable Sign Out Flow

Enabling the sign out flow sends a signed logout request to Okta when logout is called. Okta will process the signed logout request and log your user out of the Amazon Cognito session.

Note

Okta expects a signed logout request so you must configure the signing certificate provided by Amazon Cognito with your Okta application.

Complete the following procedure to configure the endpoint for consuming logout responses from your Okta application:

  1. On the Okta website, select Applications to go to the active applications dashboard.

  2. Select the data lake application you created in Configure the Okta Account.

  3. Select the General tab, scroll down to SAML Settings and choose Edit.

  4. Under General Settings, select Next.

  5. Under SAML Settings, select Show Advanced Settings and configure the logout parameters:

    1. Check the Enable Single Logout option to display additional fields.

    2. For Single Logout URL enter

      https://<cognito_domain>.auth.<region>.amazoncognito.com/saml2/logout

    3. For SP Issuer field, enter Cognito.

    4. For Signature Certificate, browse for the certificate file you copied (for example, datalake.cer) and select Upload Certificate.

  6. Select Next and then Finish.

Update the Data Lake Console Configuration File in Amazon S3

After configuring all the Amazon Cognito and Okta parameters, you are ready to return to the data lake console (in your Amazon S3 bucket) and update its configuration in order to activate login federation.

  1. In the AWS Management Console, navigate to Amazon S3.

  2. Select the data lake bucket (datalake-<region>-<account_id>).

  3. Navigate to the lib file folder.

  4. Download the app-variables.js configuration file.

  5. Open the configuration file and update the parameters.

    var FEDERATED_LOGIN = true; var LOGIN_URL = “https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/login?response_type=token&client_id=<yourClientId>&redirect_uri=<ConsoleUrl>”; var LOGOUT_URL = “https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/ logout?response_type=token&client_id=<yourClientId>&redirect_uri=<ConsoleUrl>&logout_uri=<ConsoleUrl>”;

    Find your specific parameters in your Amazon Cognito console:

    • To find <yourDomainPrefix> and <region> look under App integration, Domain name.

    • To find <yourClientId> look under General settings, App clients. Use the App client id attributed to the data-lake-ui App client.

    • To find <ConsoleUrl> look in the AWS CloudFormation console. Open the stack Outputs tab and copy the URL defined in the ConsoleUrl paramenter.

  6. Upload the modified file back to Amazon S3.

  7. Use the following link to access your data lake console:

    https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/login?response_type=token&client_id=<yourClientId>&redirect_uri=<ConsoleUrl>