Clarity
SaaS Authentication in the Google Cloud Platform

ccppmop1591
2
Introduction
Federated SSO integration creates a trusted relationship between
Clarity
SaaS and your organization's identity management solution. This relationship delivers the following benefits:
  • Seamless integration between networks and environments: All users can move easily between your organization's intranet and
    Clarity
    SaaS.
  • Simplified password management: No need to manage user passwords separately from
    Clarity
    SaaS, because your existing user management system handles password management.
  • Broadcom Supported: A dedicated Broadcom support organization is available to provide technical support as needed.
Customers can be assured the Identity management tool will authenticate users for access to
Clarity
only after being authorized by the IdP solution. To provide this functionality,
Clarity
SaaS supports federated single sign-on using SAML 2.0. This integration creates a trusted relationship between Broadcom’s SaaS infrastructure and your organization's existing enterprise user management system, simplifying end-user password management.
Clarity
SaaS currently supports IdP initiated SAML version 2.0 with HTTP-POST Binding. SP initiated SSO can be enabled. However, the customer needs to understand and accept the following limitations:
  • A user's favorite links (for projects or timesheets etc.,) saved in the browser, can be used if the user double clicks the link.
  • In this scenario, Broadcom does not generate a SAML assertion from its servers The user is simply redirected to the IdP URL.
The recommended solution is to use IdP initiated SSO with Broadcom’s
Clarity
SaaS.
Organizations that intend to leverage federated SSO with
Clarity
SaaS must implement the client-side (IdP) requirements and tools to support SAML federated SSO, such as; CA Single Sign-On, Active Directory Federation Services (ADFS), or other vendors.
Federated SSO Implementation
Requirements to enable Federated SSO with
Clarity
SaaS
In order to enable Federated SSO, the following requirements should be met:
  1. Customers must implement an Identity Management (IdP) solution for user management.
  2. The customer’s IdP solution must support SAML 2.0.
  3. Customers must create IdP artifacts passing the required information to
    Clarity
    SaaS.
  4. Federated SSO will be enabled for all
    Clarity
    SaaS environments.
  5. All
    Clarity
    usernames must be defined in a valid email format.
The following flow defines the activities that need to be done to set up Federated SSO in
Clarity
SaaS:
Requirements.png
Information Needed to Enable Federated SSO in
Clarity
SaaS
To enable the federated SSO service in GCP, customers start the process by creating a Broadcom Support ticket requesting Federated SSO to be setup. The Support ticket should include the following information:
Information Needed
Summary
Clarity
environment information
Provide the
Clarity
URLs for all environments (e.g., Test, Dev, and Prod).
Your SSO Solution Tenant Admin:
  • Name
  • Email Address
  • Phone
Identify one account. This user will be granted access to Broadcom’s Okta, as an administrator, to manage the Okta user group. The user will be responsible for managing non-federated users in your federally authenticated environment. To learn more about creating an Okta tenant admin, see Creating an OKTA Tenant Admin.
Name of Identity Management Solution
This is the name of the IdP application used by your organization. The IdP application will issue a SAML request to
Clarity
SaaS. (e.g. ADFS, Okta, PingFederate, etc.).
Email domains your IdP is restricted to
If the user email address is not in these domains,
Clarity
authentication and access will be denied. (e.g., abccompany.com, xyzcompany.com)
Clarity
landing page (Default is Modern UX)
Upon successfully logging into
Clarity
, the user lands on the defined Modern UX or
Classic PPM
page. Broadcom recommends users land on a defined Modern UX page.
Do you want to restrict user authentication to Federated SSO only? (Yes/No)
If yes, Service Provider initiated authentication will be set up. If no, users will be able to login using Broadcom Okta credentials in addition to IdP or Service Provider initiated authentication.
SAML IdP Issuer ID
The IdP ID can be unique for each environment. This information is needed for all your
Clarity
SaaS environments (e.g. Dev, Test, Prod will have unique values for each environment).
SSO Service URL for your IdP
This is the IdP URL. This information is needed for all your
Clarity
environments (e.g. Dev, Test, Prod will have unique values for each environment).
Signer Certificate
This is the certificate used to sign the (SAML) assertions.
Logout URL
This is the URL the end user should see when they log out of
Clarity
.
Broadcom Setup
Okta Settings
Value
Description
SAML Binding
SAML2.0 HTTP-POST
Broadcom SaaS supported type of binding used to send SAML Assertion.
Skew time
2 Minutes
Default - 2 minutes
Target Page
Clarity
URL
URL configured for either
Clarity
or
Classic PPM
based on the information provided by the customer.
NameId
NameID should contain OKTA /
Clarity
username (Email format)
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[email protected]</saml2:NameID>
Is Assertion Encrypted?
No
Only signing of assertion is supported
Assertion Consumer Service
<Customer specific>
This information (Service Provider metadata) will be provided to the customer once we set up the IdP information received from the customer.
Session Timeout on OKTA
2 hrs
Software Used to Setup Federation
While Broadcom SaaS Portal Service uses SAML 2.0 standards to provide federated access, understanding the IdP used on the customer side will help Broadcom to better mitigate issues. There are scenarios where we need specific settings unique to the type of software or version number.
Once Broadcom completes the setup process, the following information will be shared with the customer to proceed with their IdP setup.
  • RelayState
    : Based on the customer supplied information provided, Broadcom will share instructions to setup relaystate. Broadcom will share relaystate information for each
    Clarity
    SaaS environment.
  • Federation Metadata File
    : Service Provider metadata information.
Customer Setup
Once Broadcom completes the SSO setup and provides the SSO setup information, customers need to complete the following activities:
Activities performed by your SSO Team
The customer's SSO team needs to create a new IdP Artifact for each
Clarity
environment. This artifact has the following SAML assertion requirements:
  • NameID should contain the
    Clarity
    username in the form of an email address.
  • The SAML Attributes are needed in the Assertion (These attributes will be used to provision and update user information in Broadcom Okta.)
    • firstName
    • lastName
    • Email
  • Encryption: Only the signing of assertion is supported.
  • Minimum Signature Algorithm when validating SAML Assertions: SHA-256
  • RelayState (or TargetURL)
    : This is needed to route the end-user to the
    Clarity
    environment.
Activities Performed by Your  Okta Tenant Admin
After the Broadcom team configures the tenant admin in Okta, an email will be sent to the tenant administrator by Okta. The Okta tenant admin needs to perform the following actions:
  1. Select the link in the email to register in Okta.
  2. Setup a new password for Okta.
  3. Set up multi-factor authentication.
Testing
Try to login to your current non-production environment by using the new SSO configuration.
Post Setup Activities
Setting up Federated SSO is a coordinated activity between Broadcom and your SSO team. We recommend the following approach:
  1. Setup an IdP artifact for each of your non-production environments. This should be tested first to ensure the deep linking is configured correctly between your IdP and Broadcom’s Okta.
  2. After a successful test, we recommend the following:
    • Create an IdP artifact for Production and have it ready for Production Go-Live.
    • Schedule a go-live weekend when Broadcom will enable SSO for the Production environment, and your team can enable the IdP artifact for all users.
Broadcom’s Okta User Groups
Broadcom will create user groups in Okta, which map to a provisioned
Clarity
environment. A single user can be part of multiple user groups, allowing them to access multiple
Clarity
SaaS environments.
The Broadcom Okta user groups have the following nomenclature:
ClarityPPM.tenant_name.tenant_domain.Clarity_instance_type
Example: Consider a tenant named MyBank provisioned on the
Clarity
GCP infrastructure.
MyBank needs DEV and PROD
Clarity
instances. The provisioning process assigned MyBank the tenant domain "cppm4758". In this example, the provisioning process will create two user groups for MyBank:
ClarityPPM.MyBank.cppm4758.dev
ClarityPPM.MyBank.cppm4758.prod
These user groups correspond to the two
Clarity
environments provisioned for MyBank.
Clarity
administrators define users in each
Clarity
environment.
Users defined in the non-production environment will be added to the ClarityPPM.MyBank.cppm4758.dev group and users defined in the production environment will be added to the ClarityPPM.MyBank.cppm4758.prod group.
User Management
In order for a user to access
Clarity
in SaaS, their information needs to exist in multiple systems. Review the process defined below to learn more about creating users in the appropriate systems:
UserManagement.png
  1. User Creation In Your User Identity Management System
    In a system authenticated by a single user management system, the user needs to be created in your IdP. This system will be used to authenticate a user before allowing the user to access the
    Clarity
    application in SaaS. User creation in this system is done by your SSO team.
  2. User Creation in
    Clarity
    Your organization's
    Clarity
    administrator can create and manage users, directly within
    Clarity
    . When defining users in
    Clarity
    , the username must be in the form of an email address. If the user name is not defined as an email address, the user will not match Broadcom’s Okta user definition and access will be denied.
  3. User creation in Broadcom’s Okta
    Broadcom uses Okta as the system of record for all users accessing Broadcom products in the GCP SaaS infrastructure. Every user accessing
    Clarity
    must be a user in Broadcom’s Okta tenant. In addition, user groups within Okta determine the products and environments of those products a user can access. A user may be a member of one or more user groups depending on the products and instances they can access.
    Customers using a Federated SSO solution with
    Clarity
    do not need to additionally create users in Okta. Broadcom’s Okta “Just in time” (JIT) user creation automatically creates users (in Okta), when a SAML request is received. The JIT functionality will perform the following actions:
    • When a SAML request is received by Okta, JIT checks if the user exists in Okta.
    • If the user exists, the user is navigated directly to the defined target
      Clarity
      environment (and page).
    • If the user does not exist in Okta, the user is automatically created in Okta, added to the Okta user group, and the user is automatically navigated to the target
      Clarity
      environment.
  4. Non-Federated User Creation in Okta
    The SaaS User Sync job enables Clarity SaaS customers to synchronize
    Clarity
    users with Broadcom Okta and assign them to the appropriate Okta groups. Administrators should manually schedule this job to run regularly. In
    Clarity
    15.9.1 and future releases, customers do not need to log in to Okta as tenant admin to add users.
    The SaaS User Sync job reads all users from Clarity that have not been synced previously and then performs the following actions:
    • Check if the
      Clarity
      user exists in Okta.
    • If the username is not in the form of an email address, the user is skipped.
    • If the user exists and is in the appropriate Okta group, then the job will not make any changes.
    • If the user exists but is not in the appropriate Okta user group, the job will add the user to the appropriate Okta user group.
    • If the user does not exist in Okta, the job will create the user and add them to the appropriate Okta user group.
    If user status in
    Clarity
    is "inactive", then the job removes the user from the Okta user group, thus revoking their access to the Clarity PPM instance. The user will be marked as not having been synced in case they are reactivated at a future date.
    To learn more about the SaaS User sync job, see Clarity Jobs Reference.
    If you are using older releases of
    Clarity
    , or want to create users manually as an Okta tenant admin, follow the steps given below. To learn more about creating an Okta tenant admin, see Creating an OKTA Tenant Admin.
    1. From
      Clarity
      , create the non-federated user via the “Resources” section under Administration.
      UserManagement.png
      The username format must be a valid email address.
    2. Your Okta tenant administrator will log into Broadcom’s Okta administration site (http://avagoext.okta.com).
      UserManagement.png
      The tenant administrator should be the same user identified in “Information needed to enable Federated SSO in
      Clarity
      SaaS” and should use the same login credentials established when registering in Okta.
    3. Navigate to the Admin link on the top right of the page.
    4. Complete multi-factor authentication
    5. Navigate to “People” under the Directory menu.
      UserManagement.png
    6. Click on “Add Person”, to create the non-federated user.
    7. Populate the user information for non-federated users. Some key information you should remember is shared below:
      UserManagement.png
      • Users must have a valid email address and must be the same as the username in
        Clarity
        .
      • Ensure the “Send user activation email now” is checked.
  5. Save the user information. The new user will receive an email from Okta with instructions to register and set up multi-factor authentication.
  6. Navigate to
    Groups
    under the Directory menu and add the user to the respective group.
    UserManagement.png
If a non-federated user already exists in Broadcom’s Okta then your Okta tenant admin cannot add them to the Okta user group to grant them access to your
Clarity
SaaS environment. Broadcom’s Okta tenant will see the error message below. In such a situation, you need to open a support ticket with Broadcom requesting the existing non-federated user be added to your Okta user group.
UserManagement.png
Syncing Users Between
Clarity
and Okta
Using the JIT functionality, the system will automatically create users in Broadcom’s Okta based on the SAML request. Remember that users must be defined in
Clarity
to leverage JIT.
In Clarity 15.9.1 and higher releases, you can specify a secondary email address for a user in
Clarity
. This is intended only for
Clarity
SaaS customers who want to create test user accounts in
Clarity
. In previous releases of
Clarity
SaaS, if customers created a test user with an invalid email address then they did not get any Okta activation information. In
Clarity
15.9.1 and higher releases, you can create a test user in
Clarity
where the user name and primary email address are invalid and the secondary email will be a valid email. You can use the same secondary email address for all test accounts.
After you create the new user in
Clarity
, you can use the SaaS User Sync job to update the details in OKTA for non-federated users. Federated SSO users can leverage Broadcom’s Okta “Just in time” (JIT) user creation, which automatically creates the user (in Okta) after receiving a SAML request. The user’s primary and secondary email is now configured in OKTA. However, once
Clarity
creates a user in OKTA, it will not update any details in OKTA. You need to work with your OKTA Group administrator to update user details in OKTA.
Revoking User Access to
Clarity
In order to revoke user access from
Clarity
SaaS, remember the following points:
  1. Federated users authenticating to
    Clarity
    using your IdP should be managed in your IdP.
  2. User status in
    Clarity
    should be changed to “Inactive”.
  3. Your Okta tenant admin should remove the user from the Broadcom Okta user group.
    1.   Log into Okta as a tenant administrator and navigate to the Admin link.
    2.   Complete the multi-factor authentication.
    3.   Select
      People
      under the Directory menu.
    4.   Search for the resource whose access you want to revoke and click their name.
    5.   Navigate to the
      Groups
      tab and remove the relevant groups.
      Ensure you remove access to the Development group if you don't want resources to access the development environments.
Authorization Flows
In
Clarity
SaaS, once Federated SSO has been set up, end users access
Clarity
using one of the following methods:
IdP Initiated Flow (Accessing
Clarity
using Customer’s IdP)
The IdP initiated flow will be the typical method for all end-users to access
Clarity
.
  1. End users navigate to the organization's IdP solution URL.
  2. End users authenticate via the organization’s IdP.
  3. Depending on the IdP system in use, end users will typically see an application tile for each
    Clarity
    environment along with other application tiles for which they have access.
  4. If end users are presented with multiple tiles/links, they select which
    Clarity
    environment they want to access.
  5. If the IdP is configured to route end users directly to
    Clarity
    , they will land on the defined
    Clarity
    landing page.
SP Initiated Flow (Accessing
Clarity
using
Clarity
URL)
End-users can access
Clarity
directly from the
Clarity
URL. In this situation, the following will occur:
  1. End users navigate to the
    Clarity
    environment.
  2. If the user has a valid
    Clarity
    session, they will land on the defined
    Clarity
    page.
  3. If the user does not have a valid
    Clarity
    session, they are routed to the IdP authentication page.
  4. End users will authenticate using the organization’s IdP.
  5. Depending on the IdP system in use, end-users will either see an application tile for each
    Clarity
    environment, along with other application tiles for which they have access.
  6. If end users are presented with multiple tiles/links, they can select the
    Clarity
    environment they want to access.
  7. If the IdP is configured to route end users directly to
    Clarity
    , they will land on the defined
    Clarity
    landing page.
Non-Federated user access (Accessing
Clarity
using the new SSO URL)
In
Clarity
SaaS, once Federated SSO access is enabled, all
Clarity
environments are controlled by SSO. However, there may be a case where a customer wants to grant
Clarity
access to non-federated users (e.g., users not defined in the IdP), to their
Clarity
environment.
Perform the following steps:
  1. Your Okta Tenant Admin will create a user account for you. They can follow the steps listed in the Non-Federated User Creation in Okta section.
  2. After the user is created in Okta, your administrator can set the password or send you an activation link.
  3. Once you receive the link, you need to activate your account by performing the steps listed in the email.
  4. After the user is activated, you can logout, navigate to https://avagoext.okta.com/login/default, and set up multifactor authentication.
  5. Enter the proper username, in email address format, and password. If multi-factor authentication is enabled, the user must supply the additional authentication information as required.
    UserManagement.png
  6. After successful login, end-users will land in the defined
    Clarity
    landing page.
Accessing
Clarity
via XOG
The XML Open Gateway (XOG) is a
Clarity
web service interface typically used by partners and system administrators to import/export data or move configuration data from one environment to another. XOG uses XML and web services to perform these functions.
This flow is used when a user or integrated system interacts with
Clarity
SaaS using the XOG endpoint. When accessing this XOG endpoint, the user or integrated system must specify a defined
Clarity
username and password.
XOG will not support SSO. The XOG transaction is achieved by specifying the
Clarity
username and password for the user who has the authorization to perform the requested XOG. The user will be authenticated using
Clarity
authentication.
Creating an OKTA Tenant Admin
A
Clarity
user cannot be an Okta tenant admin because a
Clarity
user is added under the non-MFA(Multi-Factor Authentication) group and for Okta tenant admin it needs the MFA group.
As a part of the onboarding process, a customer will provide the email address of a user who would be the tenant administrator. Broadcom will provision a new account in Okta by appending -admin to the username. For example, if a customer provides [email protected], Broadcom will generate a new Okta account as [email protected] The email ID associated with this account will be [email protected] Broadcom will assign administrator privileges to the new user account.
The tenant administrator can perform the following steps after they receive an email from Okta:
  1. Open the email received from Broadcom.
    Tenant.png
  2. Click the
    Activate SSO Account
    link in the email. The tenant administrator can define their password and configure the password recovery options. After the account is created, they will land on the Broadcom home page.
    Tenant.png
  3. After activation, the tenant administrator should navigate to https://avagoext.okta.com/login/default and log in by using the account you just created.
  4. Click
    Setup
    to configure MFA. The tenant administrator can use the EMAIL option to set up MFA.
  5. They will receive the code on their registered email.
    Tenant.png
  6. The tenant administrator can log into Okta and click
    Admin
    .
    Tenant.png
  7. Review Non-Federated User Creation in Okta to see how tenant administrators can add non-federated users in Okta.
Customers should not add the tenant administrator account with “-admin” suffix to their IDP. If the tenant administrator accesses Broadcom OKTA using SSO, multi-factor authentication will be removed. However, the tenant administrator need's multi-factor authentication to be an Okta administrator. In our example, [email protected] should not be added to the customer's IDP.
Common Questions
  • What happens if a user is defined in the IdP system, but not defined in
    Clarity
    ?
    If the user logs into the IdP and navigates to
    Clarity
    , but the user does not exist in
    Clarity
    , they will be presented with the
    Clarity
    login page. In this situation,
    Clarity
    received a SAML request for a user it could not identify.
  • Can I provide non-federated users access only to the
    Clarity
    non-production environment?
    Yes, the tenant administrator can limit the non-federated user access to the non-production environment by only adding this user to the non-production Okta user group.
  • If we want to enable Federated SSO access to
    Clarity
    SaaS, then are we required to configure all of our
    Clarity
    environments with Federated SSO?
    Yes, Broadcom requires Federated SSO for all
    Clarity
    environments. You cannot set up Federated SSO for only one environment.