Configuring
Clarity
to Support SAML 2.0

ccppmop1581
Clarity
15.8.1 and higher releases allow 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.
Clarity
supports SAML by using a virtual object and REST APIs that allow SAML metadata to be uploaded as a file into
Clarity
. After the file is successfully uploaded, a REST API call to that same virtual object will provide the SAML metadata from
Clarity
that can be used by the IDP to complete its connection to
Clarity
.
Clarity
also has additional REST API endpoints that allow you to modify and examine the metadata configured in
Clarity
.
2
Pre-Requisite: Enable Feature Toggle
Login to the Application server and enable the SAML feature by running the following command:
admin toggle-feature POSTUPGRADE_ON_PREMISE_SAML_FEATURE_F20836 1
Ensure that you restart the application services after enabling the feature toggle.
You need to perform two key actions to enable
Clarity
to Support SAML 2.0:
Import SAMLMetadata by using REST APIs
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
by using the samlMetadata REST API.
Clarity
provides three REST APIs to help you configure SAML for on-premise customers.
  • samlMetadata - Import SAML metadata into
    Clarity
  • samlConfigs - View the configured metadata from the IDP metadata you uploaded.
  • certs - Examine and remove signing certificates that were added as part of the IDP metadata upload
Let’s review how we can use each of these APIs.
Using the samlMetadata REST API
The samlMetadata REST API supports the POST and GET methods. You can ask your IDP provider or security administrator to give you SAML metadata and import it into
Clarity
by using this API. The API is also used to retrieve
Clarity
Service Provider (SP) metadata. The endpoint is backed by a virtual object.
Lets review the examples given below:
POST
: http://<hostname>:<port>/ppm/rest/v1/virtual/samlMetadata
Clarity
The body for this call must consist of a multipart/form-data XML file containing the metadata of the IDP. The response will contain the ID of the SAML configuration successfully uploaded.
Sample Response
{ "code": null, "_self": "/rest/v1/virtual/samlMetadata", "id": 5007000 }
GET
: http://<hostname>:<port>/ppm/rest/v1/virtual/samlMetadata/<id>
You can use the ID from the response of the POST method to get SP metadata from
Clarity
. The body of the response will be an XML file containing the SP metadata. You can share this with your security administrator or IDP provider if you are using Federated SSO.
Sample Response
<?xml version="1.0" encoding="UTF-8"?> <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" validUntil="2020-05-31T21:55:30Z" cacheDuration="PT604800S" entityID="http://<hostname>/niku/nu#action:union.samlMetadata" ID="CLARITY_161912a9-3038-4293-b5ee-c7e5adb4d1a3"> <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://<hostname>/niku/nu#action:homeActionId" index="1" /> <md:AttributeConsumingService index="1"> <md:ServiceName xml:lang="en">68878c58d4a9484bb61c916a5b2117bf</md:ServiceName> <md:ServiceDescription xml:lang="en">4cf8b05d-7c8c-4c55-b8a8-6160b04ccd4e</md:ServiceDescription> <md:RequestedAttribute Name="Login" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="Login" isRequired="true" /> </md:AttributeConsumingService> </md:SPSSODescriptor> </md:EntityDescriptor>
Using the samlConfigs REST API
The samlConfigs REST API allows you to see the configured metadata from the IDP metadata you uploaded. This endpoint is backed by an object that uses the CMN_SEC_SAML_CONFIGS table to store the data. The endpoint supports the GET and DELETE methods to examine and remove the metadata. The API requires the ID of the SAML metadata that was added by using the samlMetadata POST call.
Let’s review the examples given below:
GET
: http://<hostname>:<port>/ppm/rest/v1/samlConfigs/id
Sample Response
{ "code": "68878c58d4a9484bb61c916a5b2117bf", "_links": { "requestedAuthnContext": "/rest/v1/lookups/AUTHN_CONTEXTS/lookupValues", "signingAlgorithm": "/rest/v1/lookups/SIG_ALGORITHMS/lookupValues", "ssoServiceBinding": "/rest/v1/lookups/SERVICE_BINDINGS/lookupValues", "nameIDFormats": "/rest/v1/lookups/NAME_ID_FORMATS/lookupValues", "spCertificateID": "/rest/v1/lookups/CMN_SEC_CERTIFICATES/lookupValues", "assertionConsumerBinding": "/rest/v1/lookups/ASSERTION_BINDINGS/lookupValues", "idpSingleLogoutServiceBinding": "/rest/v1/lookups/SERVICE_BINDINGS/lookupValues", "x509Certificate": "/rest/v1/lookups/CMN_SEC_CERTIFICATES/lookupValues" }, "technicalContactEmail": null, "idpSingleLogoutResponseURL": null, "entityID": "http:///<hostname>/niku/nu#action:union.samlMetadata", "assertionConsumerBinding": { "displayValue": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST", "_type": "lookup", "id": "HTTP-POST" }, "idpSingleLogoutServiceBinding": { "displayValue": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect", "_type": "lookup", "id": "HTTP-Redirect" }, "_internalId": 5007000, "assertionConsumerURL": "http://<hostname>/niku/nu#action:homeActionId", "signIncomingAssertions": null, "idpSingleLogoutURL": null, "spCertificateID": null, "_self": "/rest/v1/samlConfigs/5007000", "x509Certificate": { "displayValue": "1736ed50-b78c-447a-87a6-b99f6d183124", "_type": "lookup", "id": "5007000" }, "organizationName": null, "signSpAuthnRequest": null, "supportContactEmail": null, "encryptSpNameID": null, "emailDomains": null, "active": true, "organizationURL": null, "encryptIDPAssertions": null, "idpEntityID": "http://www.okta.com/exk1oz6rd3nMZuc1o357", "supportContactName": null, "privateKey": null, "requestedAuthnContext": { "values": [ { "displayValue": "urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified", "id": "authncontextunspecified" } ], "_type": "lookup" }, "isDefault": false, "createdDate": "2020-05-29T14:54:07", "organizationDisplayName": null, "isJITEnabled": false, "signingAlgorithm": null, "ssoServiceBinding": { "displayValue": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect", "_type": "lookup", "id": "HTTP-Redirect" }, "technicalContactName": null, "nameIDFormats": { "values": [ { "displayValue": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", "id": "emailAddress" } ], "_type": "lookup" }, "name": "4cf8b05d-7c8c-4c55-b8a8-6160b04ccd4e", "signspMetadata": null, "signSpLogoutRequest": null, "organizationLanguage": null, "encryptIDPNameID": null, "signIncomingMessages": null, "ssoServiceURL": "https://dev-388382.okta.com/app/broadcomdev388382_ssotestingapp_1/exk1oz6rd3nMZuc1o357/sso/saml", "uniqueIDPrefix": "CLARITY_" }
DELETE
: http://<hostname>:<port>/ppm/rest/v1/samlConfigs/id
There is no response body. A 200 status code indicates the delete was successful. You need to use the DELETE method only if you want to delete an IDP you configured previously.
Using the Certs API
The certs REST API allows you to examine and remove signing certificates that were added as part of the IDP metadata upload. This endpoint supports POST, PUT, GET, DELETE methods to allow the full complement of REST API methods. Multiple certs may be added, however, only one is used with the associated samlConfig. All the certificates are stored in the CMN_SEC_CERTS table.
When a samlConfig is deleted it is recommended that its associated cert also be deleted by using the DELETE method on the certs endpoint.
Clarity
will not delete certs when samlConfigs are deleted.
GET
: http://<hostname>:<port>/ppm/rest/v1/certs shows you all the certificates in the system.
Response { "_internalId": 5007000, "lastUpdatedDate": "2020-05-29T14:54:07", "code": "225bed25b3cb475b8ee21e386aa9dfcf", "createdDate": "2020-05-29T14:54:07", "name": "1736ed50-b78c-447a-87a6-b99f6d183124", "active": true, "certificateText": "MIIDpDCCAoygAwIBAgIGAWxzUfPjMA0GCSqGSIb3DQEBCwUAMIGSMQswCQYDVQQGEwJVUzETMBEG\nA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU\nMBIGA1UECwwLU1NPUHJvdmlkZXIxEzARBgNVBAMMCmRldi0zODgzODIxHDAaBgkqhkiG9w0BCQEW\nDWluZm9Ab2t0YS5jb20wHhcNMTkwODA4MjIxOTQ2WhcNMjkwODA4MjIyMDQ2WjCBkjELMAkGA1UE\nBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNV\nBAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRMwEQYDVQQDDApkZXYtMzg4MzgyMRwwGgYJ\nKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA\nm6kwTtIWitWvgGrBmSAJrKcVq+FUKOuPycnGmVfAw4OVV99ca4Qj8xOSEiY5ut0UMtPI/BXb+enZ\ngXib2O96OH2VPW41PcqToqyIo+bBXPLDdVita2f54xZhk+/tQClrQvqfqzakp9CdZr5HFJ3bXMYF\nrQHXOATPAGy0IcmM7jSEeXUIpJ4yHTRQOE+fkDZ2+z/mWA25W7xU8aExNrVAM8MozOuYQinHGB3o\nifGbsMMWXc0TXbNi/D8kmCEtE16PBscs8Vq5thLWPC4wbEhDPQ6Do4HCkqapsUuIL3VS4tyDS/Zq\n6Zbu7YzM571zUQfvS0J1YH63QvX86U9RWMJPQQIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQAzbfvC\nBvuD6zxgSFpxf3UbAmZoQpvMW2cS4JloYaiToD9qoGCjzAEgCdnVJkf3yC3fRmhQ4brQ62hFKEi7\nO2rn2lx4Nj22VlLr5ojJmq6BANzfbkif2tk/f5JeKkLtCDNQsQ/VubYwXZCcdZ0PHvUdSoR4t4NJ\npDkXYRSIR7PHhgdlchs5JCcpDott2ARwH1y58tJRoUesFzwUA10i58NPa3cw8UMPKBJMKpLeCQ3K\n/6iUoVkgltOQdTWIGbqT91IYgZgHYX0FAhpqmLm8IAlHqYtVET/XNoOHMvg8IAfCSUuVg6hDJJEu\nfTU0RNwkAcwBeFmUEGM527j7IQ3Q7Yqz", "_self": "/rest/v1/certs/5007000", "startDate": null, "expirationDate": null }
DELETE
: http://<hostname>:<port>/ppm/rest/v1/certs/id will delete a specific cert from the system. There is no response body. A status code 200 indicates the DELETE worked.
Configuring
Clarity
to Support SAML 2.0
You need to perform the following actions to configure
Clarity
to support SAML 2.0.
  • Enable SAML authentication on the System Options page
  • Ensure usernames match for
    Clarity
    and IDP
  • Update Settings in the CSA.
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.
Update Settings in the
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
    .
  6. Save your changes.
  7. Restart
    Clarity
    services.
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 by using the DELETE method.
    • Import SAML metadata by using the samlMetadata REST API
    • Ensure you don't truncate the database tables.
IDP Configuration Examples
Let's review a couple of examples of how you can configure IDPs to work with
Clarity
.
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.