Anchor
_Hlk38994778 _Hlk38994778

Anchor
_Toc39234181 _Toc39234181

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

Anchor
_Toc36654170 _Toc36654170

Anchor
_Toc39234182 _Toc39234182

Document Revision History

Anchor
_Toc39234183 _Toc39234183

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

Anchor
_Toc39234184 _Toc39234184

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:

Anchor
_Toc39234185 _Toc39234185

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.

Anchor
_Toc39234187 _Toc39234187

Architecture Diagram

Image Added

Anchor
_Toc39234188 _Toc39234188

Sequence Diagrams

Anchor
_Toc39234189 _Toc39234189

Login

Image Added

Anchor
_Toc39234190 _Toc39234190

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.
Image Added

Anchor
_Toc39234191 _Toc39234191

Federated Login

Image Added

Anchor
_Toc39234192 _Toc39234192

Logout

Image Added

Anchor
_Toc39234193 _Toc39234193

Model Diagrams

Anchor
_Toc39234194 _Toc39234194

Clarity PPM Cognito Service – Callback.jsp

Image Added
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|

    Anchor
    _Toc39234195 _Toc39234195

    Clarity PPM Cognito Service – Logout.jsp

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

Anchor
_Toc39234196 _Toc39234196

Cognito User Sync Job

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

Anchor
_Toc39234197 _Toc39234197

Deployment

Anchor
_Toc39234198 _Toc39234198

Component Description

Anchor
_Toc39234199 _Toc39234199

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

Image Added

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

Anchor
_Toc39234200 _Toc39234200

Cognito User Sync Job

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

Anchor
_Toc39234201 _Toc39234201

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

Anchor
_Toc39234202 _Toc39234202

Configuration

Anchor
_Toc39234203 _Toc39234203

Cognito

Anchor
_Toc39234204 _Toc39234204

DNS SetupPending overall AWS Architecture

Anchor
_Toc39234205 _Toc39234205

SES SetupPending overall AWS Architecture

Anchor
_Toc39234206 _Toc39234206

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 Image Added
  Case Insensitivity	Must be checked Image Added
  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

Image Added

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:

Image Added

• 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

Image Added

TagsPending overall AWS architecture

Devices

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

Image Added

App clients

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

Image Added

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.

Anchor
_Toc39234207 _Toc39234207

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.
Image Added

Anchor
_Toc39234208 _Toc39234208

Cognito User Sync Job

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

Anchor
_Toc39234209 _Toc39234209

Appendix

Anchor
_Toc39234210 _Toc39234210

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.

Anchor
_Toc39234211 _Toc39234211

Helpful Links

Anchor
_Toc39234212 _Toc39234212

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?

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

Anchor
_Toc39234213 _Toc39234213

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.