Moventus
Clarity Hosting
Cognito User Portal
Date: 04/30/2020
Version: 1.6

Contents

1. Contents
2. Document Revision History
3. Purpose
4. Approach
5. Design
5.1 Use Cases
5.2 Architecture Diagram
5.3 Sequence Diagrams
5.3.1 Login
5.3.2 Federated Account Merge
5.3.3 Federated Login
5.3.4 Logout
5.4 Model Diagrams
5.4.1 Clarity PPM Cognito Service – Callback.jsp
5.4.2 Clarity PPM Cognito Service – Logout.jsp
5.4.3 Cognito User Sync Job
6. Deployment
6.1 Component Description
6.2 Clarity PPM Cognito Service
6.3 Cognito User Sync Job
6.4 Cognito-PreSignUp
7. Configuration
7.1 Cognito
7.1.1 DNS Setup
7.1.2 SES Setup
7.1.3 Cognito - User Pool Setup
7.2 Clarity PPM Cognito Service
7.3 Cognito User Sync Job
8. Appendix
8.1 FAQ
8.2 Helpful Links
8.3 Monitoring Recommendations
8.4 Error Codes

Document Revision History

Purpose

Amazon Cognito is a simple to use identity service, which will be used for Moventus – Clarity Hosting in order to secure and centralize authentication and user management. By doing this, we enhance the overall experience from an operational and customer perspective:

• Supporting multiple authentication methods: SAML, Form Based Authentication, Open ID
• We protect the Clarity PPM application with an authentication service
• By allowing all authentication requests to be processed by OAUTH we standardize the process and ease of use
• Automatically expose functionality like MFA, Password Resets, among other functionality

While maintaining a standard, regulated process:

• Using a certified platform, that aligns with the use of AWS
• GDPR and Geolocated compliance
• Effectively provide a similar portal to the Broadcom provided OD Portal

Approach

The intention of the following document is to provide the necessary steps and implications in order to properly deliver and maintain an effective SSO and Authentication architecture. Each step will be properly outline and explain in further detail through the following sections.
As a minimum the solution is intended to provide the following, through a stable IDaaS Architecture:

Design

The following components will be incorporated as part of the overall design and intended to work in conjunction to provide a stable authentication and user management platform.

Architecture Diagram

Sequence Diagrams

Login

Federated Account Merge

When using federated providers, Cognito requires the identities to be merged, otherwise multiple accounts will be created and not kept in sync accordingly. The sequence below illustrates first time access.

Federated Login

Logout

Model Diagrams

Clarity PPM Cognito Service – Callback.jsp

Notes:

• All errors are logged to Clarity's app-system.log file
• All errors except missing token will be redirected to callback.jsp and display an error message.

All error messages are configured on the cognito.properties file

• All properties from the cognito.properties file will be formatted as italic

Exceptions thrown:

• When response code is other than 200, the error page will be displayed and the message for property: cognito.validation.invalidCode
  
• If response does not contain an id_token or access token, the error page will be displayed and the message for property:
  cognito.validation.tokenIsNotPresent|

  User Info Request

  A request will be performed to obtain the user information through Cognito. For this request to occur the following properties will be used for the request:

  • cognito.userinfo.url
    
    
    
• Request
  

  Method	GET
  URL	<cognito.userinfo.url>
  Basic Authentication	<access_token>
  Response	JSON Attribute
  email_verified
  email
  username

  
  Exceptions thrown:
  
• When response code is other than 200, the error page will be displayed and the message for property: cognito.validation.invalidToken
  
• When response does not contain: email_verified, email or username:
  
  cognito.userinfo.http_error_message
  
• When email_verified is not equal to true:
  Cognito.userinfo.http_error_message|

  JWT JSON Signature Validation

  It validates the JWT token, to ensure it:

  • Has a valid RSA signature by comparing against the file downloaded to path: cognito.jwks.filePath
    
  • The following values are extracted from the id_token:
    
    • cognito:username
      
    • email
      
    • cognito:groups
      
      
      Exceptions thrown:
      
• When the values for username or email do not match with the response from UserInfo:
  
  cognito.validation.tokenDataDifferences
  
• When the JWT Token validation is invalid or unable to download the key for validation:
  cognito.validation.invalitJWTToken|

  Group Validation

  Once all validations are passed, the id_token must have the proper groups assigned. Each environment will store a group on the properties file and be validated against the value on property: cognito.userInfo.allowed_group Exceptions thrown:

• When the user is does not have any of the allowed groups:
  
  cognito.validation.userIsNotMemberOfGroup
  
• When the JWT Token validation is invalid or unable to download the key for validation:
  cognito.validation.invalitJWTToken|

  WebSession Request

  The Clarity PPM WebSession class is invoked by passing the email provided on the id_token

• If a session is successfully granted it will continue to next step
  
• Otherwise Clarity PPM will handle the errors accordingly|

  URL Redirect

  The user will be redirected in the following order:

  • To the state variable, as long as it matches a relative URL or contains the same hostname as the callback.jsp request
    
  • To the property: cognito.url.home|

    Clarity PPM Cognito Service – Logout.jsp

    
    Notes:
• All errors are logged to Clarity's app-system.log file

Cognito User Sync Job

Refer to Cognito Sync Job v2.docxAt some point we might want to merge both documents, pending feedback

Deployment

Component Description

Clarity PPM Cognito Service

The following steps are intended to be automated by the AWS Architecture, as per section: 7, only the cognito.properties will be modified on a per environment basis. Be aware all services must be stopped before performing this changes and started afterwards accordingly.
Clarity Configuration

1. Login to the corresponding environment compute instances and navigate to <Clarity Home>
2. Upload the file: rego-aws-cognito-commons-1.0.0.jar to <Clarity Home>/customlib
3. Upload the files: callback.jsp, logout.jsp to <Clarity Home>/webroot
4. Upload the file: cognito.properties to <Clarity Home>/config

Note: For additional details on the content of the file review section: 7.3

1. Navigate to <Clarity Home>/config and open the file properties.xml with a text editor.

Note: these changes can be done through CSA, but for automation purposes the file will be modified directly.

Web Filter Configuration

1. Navigate to <Clarity Home>/webroot/WEB-INF, and open the file web.xml with a text editor.
2. Modify the filter "com.niku.union.web.filter.ClarityContentFilter" to include the callback.jsp and logout.jsp file names separated by comma as shown in the image below

1. Navigate to webroot/cappm/WEB-INF/web.xml, look for filter: RestAuthenticationFilter
2. Modify the "filter-class", and set the value to:

com.rego.awscognito.commons.security.RegoAuthenticationFilter

Pre 15.8 Web Filter Configuration
Note: The following must only be applied on versions prior to 15.8 this is no longer required, as the login page on timeout is no longer displayed.

1. Navigate to tomcat-app-deploy/webapps/
2. Under this folder structure there are 2 web.xml files present:
   1. pm.war/WEB-INF/web.xml
   2. pm/WEB-INF/web.xml

1. Both files must be modified as follows:
   1. On the filters section add the following filter, as the first filter:

      <filter> <description>Rego SSO Redirect Filter</description> <display-name>Rego SSO Redirect Filter</display-name> <filter-name>RegoSSORedirectFilter</filter-name> <filter-class>com.rego.awscognito.commons.security.RegoSSORedirectFilter</filter-class> <init-param> <param-name>monitoredPaths</param-name> <param-value>/pm</param-value> </init-param> <init-param> <param-name>callbackURL</param-name> <param-value>/niku/callback.jsp</param-value> </init-param> <init-param> <param-name>stateURLParameter</param-name> <param-value>state</param-value> </init-param> <init-param> <param-name>pmLoginURL</param-name> <param-value>/pm/js/core/login/login.html</param-value> </init-param> </filter>

      
      
2. Add the filter mapping below, above the mapping for: httpHeaderSecurityFilter

Cognito User Sync Job

Refer to Cognito Sync Job v2.docxAt some point we might want to merge both documents, pending feedback

Cognito-PreSignUp

In order to avoid self-service, sign up based off Identity providers, the function below is intended to:

• Intercept a new Provider account
• Disable automatic account creation
• Identify an existing account
• Attempt and reply with an AWS Cognito Account merge

The function will generate a Cloudwatch log, the following messages can be parsed for monitoring:Pending overall AWS architecture

• GET_USER_ERROR
• MERGE_ERROR
• INVALID_PROVIDER

To deploy create a lambda function per user pool, named: <Organization Name>-SSO-Cognito-PreSignUp, and modify rows 2 and 3 to set:

• <Region ID>: The region on which the service is located
• <Pool ID>: The pool ID corresponding to the Organization

Configuration

Cognito

DNS SetupPending overall AWS Architecture

SES SetupPending overall AWS Architecture

Cognito - User Pool Setup

The sections below are intended to provide a detailed explanation and naming convention to setup a User Pool. User Pools will be distributed across the following regions, and are intended to be a 1 to 1 mapping of a Customer to User Pools
*Regions*Pending overall AWS Architecture

Naming Convention

• <Company Name>: the customer's legal entity name
• <AWS Region>: The AWS region where Cognito is hosted
• <Service>: Application being served through Cognito, by default it is "ClarityPPM"
• <Clarity URL>: The clarity hostname in format <protocol>://<hostname>:<port>/

User Pool Creation

• User Pool Name: <Company Name>

Users and groups

• One group per environment should be created following the syntax below:

  Group Name	Tier
  <Company Name>-<Service>-PROD	Production
  <Company Name>-<Service>-TEST	Test
  <Company Name>-<Service>-DEV	Development

  
  

  Attributes

• The following attribute setup must be provided, all customers are required to set the Clarity PPM usernames to match email addresses.

  Setting	Value
  Username Mapping	Option below must be checked
  Case Insensitivity	Must be checked
  Required Attributes	The following attribute(s) must be checked:

  • email|
    

    Policies

• The following policies must be set to provide:
  • A strong password requirement
  • Disable any type of self-service accounts
  • Properly handle first time passwords

MFA and verifications

• The following applies for customers using Cognito's login screen, and not an external IdP:
  • MFA can be Optional or Required
  • Password recovery and attribute verification must be set as follows:

• SMS Message Role NamePending overall AWS architecture

Advanced Security

• Advanced security must be set up for: Audit Only
• All monitoring and advanced security metrics will be audited via AWS Cloudwatch
• The following monitors will be configured for alerting:Pending overall AWS architecture
  • 
    

Message customizations

• SES Configuration:Pending overall AWS architecture

• Verification Messages

TagsPending overall AWS architecture

Devices

• This functionality will be disabled, as security is managed of Server to Cognito communication for OAUTH

App clients

• App client naming convention: <Company Name>-<Service>
• Refresh token and enabled flows

Triggers

• Pre-Sign-Up script must be set to the corresponding lambda function.

Refer to section 6.4

Analytics

• N/A

App client settings

• App client must be enabled for all identity providers on a given pool.
• Callback URL must be set to:

<Clarity URL>/niku/callback.jsp

• Sign out URL must be set to:

<Clarity URL>/niku/logout.jsp

Domain namePending overall AWS Architecture

UI CustomizationPending to define Moventus color scheme and identity

Resource servers

• N/A

Identity providers

• Only the following Identity providers are supported:
  • OpenID Connect
  • SAML
• Only one identity provider per user pool is supported and must be named: SSO
• All providers must enable: Enable IdP sign out flow

Attribute mapping

• A mapping is required for Email, the provider attribute will depend on the provider and must be provided by the customer.
• The Provider's NameID will be used as the identifier and must match Cognito's and Clarity PPM's username.

Clarity PPM Cognito Service

The properties below are intended to be standardized across all environments and only those related to user pool or customer preferences to be modified. Below a sample properties file and brief description of each property.

Cognito User Sync Job

Refer to Cognito Sync Job v2.docxAt some point we might want to merge both documents, pending feedback

Appendix

Technical FAQ

Q: Do we support Deeplinks?
A: Yes, callback.jsp supports relative or full URLs to be passed as an encoded query string, using variable STATE
Q: Are bookmarks supported?
A: Yes, but due to Clarity PPM limitations, if End User does not have a session open
Q: Do we support OWB/MSP?
A: Yes, but they need to use the Scheduler links inside of Clarity PPM, for the file to include a session ID
Q: What will happen when a session time out is triggered?
A: It will follow the Logout.jsp flow
Q: Do we support Clarity PPM Mobile?
A: Yes, they will need to select "Use SSO" and use the URL ending in callback.jsp
Q: What external providers do we support and what is required for SAML?
A: Most common ones are OpenID and SAML. In additional Cognito supports multiple, well known social services.
For SAML, we require the Metadata XML, and a valid mapping for NameID that will match Cognito's User Name.

Helpful Links

Customer Commonly Asked Questions

1. Our organization currently uses a job/process from Clarity PPM to the CA On-Demand Portal. How will this process work in the new environment?

Answer: Users are managed by using the Resources page in Clarity PPM or by XOG. Clarity PPM includes the new job to synchronize users from Clarity to AWS Cognito.

1. Our organization uses the On-Demand portal to process the AD file and process new non-licensed users and agency users that would bypass the portal. How will this be supported?

Answer: In the new service, Administrators can manage (create, update, and delete) licensed users directly within Clarity PPM. Administrators can work with Rego to configure licensed users to access Clarity PPM.

1. Our partners do not have a user account with our organization. Can they still work in Clarity PPM?

Answer: Yes, the AWS Cognito service will sync all user names, it doesn't have domain or email specific requirements.

1. We currently use the ODUM tool to provision users into Clarity PPM via the portal. How will we do this in the new environment?

Answer: Clarity PPM administrators can use the XOG utility to make bulk changes to users.

1. What data will AWS Cognito Store?

Answer: AWS Cognito will store:

• • User details:
    • User name
    • Email address
    • First name
    • Last name
    • Password (Encrypted)

Monitoring RecommendationsPending overall AWS Architecture

Error Codes

The below error codes are logged as per details below, appearance of any of these key words will indicate an issue has occurred.