Usage Rules

Edit online

Usage Rules are an optional feature to limit the scope of the connection. If Usage Rules are disabled all users will use the connection. The most common use cases are testing and user routing if you utilize more than one connection.

Note:

Please review the testing section later in this document for information on how usage rules can assist with testing a new connection.

  1. Select Enable Usage Rules option to create specific rules to restrict which users will utilize this SSO connection.
  2. Set rules based on specific Users or entire Email Domains (e.g., “verifydemo.com”). Currently there is a limit of 12 total usage rules.
  3. Usage rules are prioritized, individual email matches take precedence over email domain matches.

    Usage rules

Persona Mapping

For more information, see persona .

Select Enable Persona Mapping option to configure user's persona in the application based on their SSO attributes.

  • Define the incoming persona attribute from the IDP that indicates the persona (e.g., role, department, job title).
  • Choose Default Persona from dropdown to set default persona for users who do not have specific attributes .
  • Select Next button.

    Persona Mapping

Note:

If you are using either Microsoft ADFS or Azure AD/Entra ID and intending to make use of their standard attributes, please refer to the following table to identify the Standard attribute names to be used with the Persona attribute field above. Use of the Azure SAML or ADFS SAML attribute names will result in an error:

Standard attribute name Azure SAML assertion attribute name ADFS SAML assertion attribute name
groupIds http://schemas.microsoft.com
/ws/2008/06/identity/claims/role 		http://schemas.xmlsoap.org/claims/Group
department department department
job_title job_title job_title

Finalizing the Configuration

  1. Ensure all settings are correct and complete.
  2. Select Confirm button to finalize the setup. You will receive a confirmation that the connection has been saved.

    Persona Mapping Confirmation

Managing SSO Connections

  1. To modify an existing SSO connection, open the connection from the SSO connections table and selectDots icon in the upper right and then select Edit

    Edit Rules Mapping

  2. You can disable any connection from the management interface to stop its usage without deleting it.

You can disable any connection from the management interface to stop its usage without deleting it.

Post Configuration Tasks

Those who have existing Legacy connections should disable them within 30 days after new connections have been set up to authenticate all users and are fully tested and operational.

Legacy connections will remain enabled for up to 30 days after all users have been configured to use non-Legacy connections, after which they may be administratively disabled. Legacy connections can be identified by the Connection Type 'LEGACY' on the Domain Management page as shown below.

Legacy

Troubleshooting Common Issues

  • Ensure you have provided correct Client ID, Secret, and metadata settings.
  • Ensure the attributes being passed from the IDP match the expected values in Apptio.
  • Verify that role names from the IDP match those configured in the application.
  • The following errors may result from xml metadata not being encoded as UTF-8.
  • Invalid request : Failed to import metadata. The metadata input has a syntax error.
  • invalid character
    Note: it is common for metadata saved using a browser file operation to be encoded with UTF-8 BOM which is not compatible and would need to be converted to UTF-8 before uploading into Domain Management.