Configuring
Clarity
to Support SAML 2.0

ccppmop1591
Clarity
allows on-premise customers to use the credentials issued by an IdP - that supports SAML 2.0 - and log into
Clarity
.
Some key advantages of using SAML-based SSO login are:
  • Seamless integration between networks and environments: All users can move easily between your organization's intranet and
    Clarity
    .
  • Simplified password management: No need to manage user passwords separately from
    Clarity
    , because your existing user management system handles password management.
Some of the key areas covered in this topic are:
2
Setting Up SAML Metadata in
Clarity
Every Identity Provider that supports SAML 2.0 provides a way to share the SAML metadata with other applications. Please ask the security administrator in your organization to provide you the SAML metadata for your IdP. You can then import the SAML metadata file into
Clarity
.
Clarity
allows you to perform the following activities.
Let’s review how we can perform each of these activities.
Import SAML Metadata into
Clarity
Once you receive the SAML metadata file from your administrator, you can import it into
Clarity
by using the Authentication and Keys option on the Administration page. You can choose to either upload the SAML metadata or manually populate the various attributes needed to successfully establish a connection with your IdP.
Clarity
Import SAML Metadata by using an XML File
You can use the Import Identity Provider Metadata button to import the SAML metadata into
Clarity
.
Follow these steps
:
  1. Log into
    Clarity
    .
  2. In the main menu, click
    Administration
    .
  3. Click
    Authentication & Keys
    and select
    SAML CONFIGURATIONS
    .
  4. Click the
    Import Identity Provider Metadata
    button to import the SAML metadata.
  5. Enter the Configuration Identifier, Configuration Name, and upload the SAML metadata file. Click
    Done
    to upload the file. The SAML configuration is now ready. The certificate associated with your SAML metadata is now available in the
    CERTIFICATES
    tab.
  6. Use the column picker to add various attributes such as Assertion Consumer URL, Authentication Context, Entity ID, and IdP Entity ID to the grid. These are mandatory attributes and are populated based on the SAML metadata imported by you.
  7. Use to column picker to add optional attributes such as Organization Name and Support Contact Email.
Manually Enter SAML Configurations
If you cannot generate the SAML metadata file from your IdP, or you wish to populate the SAML configurations manually, you will need the following details. You will need to get most of these details with the help of your Security Administrator. 
Clarity
Attribute
Description
Provider
X509 Certificate
The X509 certificate is a standard format for public-key encryption. Your security administration needs to provide you the certificate text so that you can update it in
Clarity
.
Security Administrator
Authentication Context
Authentication context allows IdPs to augment assertions with additional information relevant to the authentication of the user at the IdP.
urn:oasis:names:tc:SAML:2.0:ac:classes:password
Security Administrator
Assertion Consumer Binding
Bindings help you define the format in which data is transferred between Identity Providers and Service Providers.
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
Security Administrator
IdP Entity ID
The IdP Entity ID is a globally unique name for each application created in the Identity Provider.
http://www.okta.com/temp1eeddw
Security Administrator
Entity ID
The Entity ID is a unique endpoint for
Clarity
. You can append the ID you used while creating the SAML configuration to generate the entity ID.
http://ppmtemp.test.clarity.net:8080/niku/nu/sso/<ID>
Clarity
Administrator
Name ID Formats
The Name ID Formats define the name identifier formats supported by the IdP.
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Security Administrator
SSO Service Binding
The SSO Service Binding specifies the binding that exists between the SSO service at the IdP and
Clarity
.
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
Security Administrator
SSO Service URL
The SSO Service URL provides the URL for the SSO service of your IdP.
https://dev-sample.okta.com/app/dummyorg388382_org_1/exkedjmn434r35tALF357/sso/saml
Security Administrator
IdP Single Logout Service Binding
The IdP Single Logout Service Binding helps the IdP keep track of all the Service Providers (SP's) that were issued an authentication response when a user is using the IdP to log into multiple service providers including
Clarity
. When the user subsequently logs out from
Clarity
, the IdP knows which other service providers they are logged into and can send logout requests if needed.
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
Security Administrator
Assertion Consumer URL
The Assertion Consumer URL is the endpoint in
Clarity
to which the IdP provides an authentication response. It always needs to end with /niku/nu to ensure the SAML integration works successfully.
http://ppmtemp.test.clarity.net:8080/niku/nu
Clarity
Administrator
Follow these steps
  1. Log into
    Clarity
    .
  2. In the main menu, click Administration.
  3. Click
    Authentication & Keys
    and select
    CERTIFICATES
    .
  4. Click
    Add Row
    and enter the
    Name
    , the
    Certificate Text
    , and the
    ID
    . This information is typically provided by your security administrator.
  5. Click
    SAML CONFIGURATIONS
    and then click
    Add Row
    .
  6. Select the
    Column Panel
    to add the relevant attributes to the
    Clarity
    grid. You can now start adding the details provided by your security administrator.
The SAML CONFIGURATIONS page uses the
Clarity
common grid. To learn more about the
Clarity
Common Grid, see Common Components
Manage Security Certificates
You can use
Clarity
to manage the security certificates in your organization. When you import the SAML metadata file into
Clarity
, the security certificate is automatically available on the CERTIFICATES page. If your organization wants to encrypt the communication between
Clarity
and your IdP, you can add the relevant certificate to the CERTIFICATES page. You can also this page to maintain a list of certificates in your organization for other products.
Clarity
Follow these steps:
  1. Log into
    Clarity
    .
  2. In the main menu, click Administration.
  3. Click
    Authentication & Keys
    and select
    CERTIFICATES
    .
  4. Click
    Add Row
    and enter the
    Name
    , the
    Certificate Text
    , and the
    ID
    . This information is typically provided by your security administrator.
  5. Click
    Column Panel
    to add relevant attributes to the
    Clarity
    grid. You can add the Starts On and Expires On attributes to the grid to ensure administrators can review the validity of the certificate.
  6. If you have added a Service Provider certificate to encrypt the communication between
    Clarity
    and your IdP:
    1. Click
      SAML CONFIGURATIONS
      and use the
      Column Panel
      to add the following attributes:
      • Service Provider Certificate
      • Encrypt IDP Assertions
      • Private Key
    2. Double-click the
      Service Provider Certificate
      column to select the service provider certificate.
    3. Select the
      Encrypt IDP Assertions
      check box.
    4. Enter the private key.
The CERTIFICATES page uses the
Clarity
common grid. To learn more about the grid, see Common Components
Export the Service Provider Metadata
After you have uploaded your SAML metadata into
Clarity
, you need to provide the relevant
Clarity
metadata to your IdP so that they can authenticate users to access
Clarity
.
Follow these steps:
  1. Log into
    Clarity
    .
  2. In the main menu, click
    Administration
    .
  3. Click
    Authentication & Keys
    and select
    SAML CONFIGURATIONS
    .
  4. Right-click the configuration you want to export and select Export Service Provider Metadata.
  5. Save the file and share it with your security administrator.
Configure
Clarity
to Support Multiple IdPs
You can configure
Clarity
to support multiple IdPs. While most organizations use a single IdP, there are certain scenarios such as when you are migrating from one IdP to another where you may wish to support multiple IdPs.
Follow these steps:
  1. Create a SAML configuration for the second IdP in
    Clarity
    . For more information see Import SAML Metadata
  2. Update the Assertion Consumer URL to append "?sso_code=<ID>" at the end of the URL. Let's review an example. Ensure that you use the same ID that you used to set up the SAML Configuration in
    Clarity
    .
    http://ppmtemp.test.clarity.net:8080/niku/nu?sso_code=IDP2
    Clarity
  3. Export the
    Clarity
    metadata and use it to configure your IdP. To learn more about exporting
    Clarity
    metadata, see Export Service Provider Metadata.
    Consider an example where you have configured OKTA as your second IdP. When you configure OKTA, you will need to:
    • Update the Single sign on URL option to append "?sso_code=<ID>".
    • Clear the
      Use this for Recipient URL and Destination URL
      check box.
    • Remove the "?sso_code=<ID>" parameter from the Recipient URL and Destination URL. To learn more about configuring other IdPs, see SAML Configuration Examples.
Configuring
Clarity
to Support SAML 2.0
You need to perform the following actions to configure
Clarity
to support SAML 2.0.
Update Settings in
Clarity
System Administrator (CSA)
The final step for configuring
Clarity
to support SAML 2.0 is to enable Single Sign-On and set the Token Type in the
Clarity
System Administrator.
Follow these steps:
  1. Log into the
    Clarity
    System Administrator by using the following link. The following default login URL is for CSA on servers running Apache Tomcat: http://<hostname>:<port>/niku/app
  2. Select the relevant server.
  3. Navigate to the
    Application
    tab and select the
    Use Single Sign-On
    check box in the Application Instance: app section.
  4. Save your changes.
  5. Navigate to the
    Security
    tab and set the value of the token type field to
    Header
    .
    Clarity
  6. Save your changes.
  7. Restart
    Clarity
    services.
Enable SAML Authentication
You need to enable SAML Authentication in Classic PPM. Perform these steps:
  1. Log in to Classic PPM and select
    Administration
    ,
    System Options
    to open the System Options page.
  2. Select the
    Enable SAML Authentication
    option.
Clarity
Ensure Login Details Match for
Clarity
and IdP
You need to ensure that the login details in the IdP match the details associated with the USER NAME field of the resource in
Clarity
.
Clarity
  1. Log into Classic PPM with admin credentials.
  2. Select
    Administration
    ,
    Resources
    to open the Resources page.
  3. Select a resource to open it and ensure the value of
    USER NAME
    field matches the login details associated with your IdP.
Key Points to Remember
Here are few key points to remember while setting up
Clarity
to support SAML 2.0 authentication:
  • Clarity
    uses the CMN_SEC_CERTS and CMN_SEC_SAML_CONFIGS tables to store SAML details in the database.
  • If you have setup SAML 2.0 authentication on a development or test system and copy the production data to these systems, you need to:
    • Delete the SAML configuration that has been copied over.
    • Import SAML metadata again.
    • Ensure you don't truncate the database tables.
Reviewing IdP Configuration Examples
Let's review a couple of examples of how you can configure IdPs to work with
.
While Okta and Azure are used as examples,
Clarity
supports all identity providers that support SAML 2.0.
Configuring Okta to Issue Credentials for
Clarity
You can work with the Security administrator to create a SAML 2.0 application in Okta and configure it so that enterprise users can use their credentials to log into
Clarity
.
Perform the following steps:
  1. Log into the Okta administrator application.
  2. On the top menu, click
    Applications
    and then select
    Applications
    again.
    Clarity
  3. Click
    Add Application
    to create a new application.
  4. Select the
    SAML 2.0
    radio button to create a SAML 2.0 application.
    Clarity
  5. Specify the Application Name and upload the application logo.
    Clarity
  6. In the Configure SAML window, enter the following information:
    Clarity
    • Single Sign-On URL: It is the entry URL of the
      Clarity
      application. An example is https://test.broadcom.com/niku/nu
    • Select the
      Use this for Recipient URL and Destination URL
      checkbox.
    • In the Audience URI (SP Entity ID) field, enter the SP entity ID of your
      Clarity
      application. It's generally the Entry URL of your application pointing to action union.samlMetadata. An example is https://testppm.broadcom.com/niku/nu#action:union.samlMetadata.
    • In the Default RelayState field, enter the URL where you want the application to be redirected after a successful SAML assertion. An example is https://testppm.broadcom.com/pm, which redirects users to the New User Experience in
      Clarity
      .
    • Do not update the following fields:
      • Name ID Format
      • Application Username
      • Update Application Username on
    • Under Attribute Statements (Optional) section:
      •   In the Name field, select Login.
      •   In the Name format field, select Unspecified.
      • In the Value field, select user email.
  7. In the
    Are you a customer or partner screen,
    select the option that is relevant to your scenario and click
    Finish
    .
    Clarity
  8. Click
    View Setup Instructions
    , scroll to the bottom and copy the IdP metadata and save it as an XML file.
    Clarity
  9. Use the samlMetadata API to import the IdP metadata into
    Clarity
    .
    Clarity
You can review Configure SAML by Using Rest APIs and Configure
Clarity
to Support SAML 2.0 sections for detailed instructions.
Configuring Azure to Issue Credentials for
Clarity
You can work with the Security administrator to create a SAML 2.0 application in Azure and configure it enterprise users can use their credentials to log into
Clarity
.
  1. Login to Azure Portal and click
    Azure Active Directory
    .
    Clarity
  2. Select
    Enterprise Applications
    ,
    New Application
    , and select
    Non-gallery application
    .
  3. Enter the name of the application and click
    Add
    .
    Clarity
  4. Click
    Home
    ,
    Azure Active Directory
    , and
    Enterprise Applications
    and select the application you created.
    Clarity
  5. Click
    Single Sign-On
    and that click
    SAML
    .
    Clarity
  6. Under
    Basic SAML Configuration
    , click
    Edit
    to add the following values:
    Clarity
    1. Identifier (Entity ID): This is the Entity ID of
      Clarity
      SAML. An example is https://testppm.broadcom.net/niku/nu#action:union.samlMetadata
    2. Reply URL (ACS URL): This is the ACS URL or SP(
      Clarity
      ) URL. An example is https://testppm.broadcom.net/niku/nu
    3. Sign-on URL – Blank
    4. Relay State - Specify the URL where Azure should redirect after they login successfully.
    5. Logout URL – Blank
  7. Under User Attributes and Claims, the Unique User Identifier attribute cannot be edited. Remove the others and add a new Claim called "
    Login
    ."
    1. The source Attribute should be the same as the username in
      Clarity
      PPM. Set the source attribute to user.userprincipalname.
      Clarity
  8. Download the Federation Metadata XML from the link.
    Clarity
  9. Edit the Federation Metadata XML file and navigate to the bottom of the file. Add the following information to the file. <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>.
  10. Save your changes and close the file.
    Clarity
  11. Use the samlMetadata API to import the IdP metadata into
    Clarity
    .
You can review Configure SAML by Using Rest APIs and Configure
Clarity
to Support SAML 2.0 sections for detailed instructions.