SSO Connections

Edit online

This document describes the workflows for adding new SSO Connections to Access Administration. Please review the SSO Configuration Overview if you have not already done so to confirm that you have done the necessary preparation for setting up your SSO Connection. Once that is complete, proceed to Adding a New SAML SSO Connection or Adding a New OIDC SSO Connection below. See Viewing and Editing SSO Connections for instructions on modifying, enabling or disabling existing SSO Connections.

Note: You must have the SSO Admin Role to add and edit SSO Connections.

Adding a New SAML SSO Connection

This section uses the values provided by the IdP team for your SAML application as described in SAML Preparation. Note that attribute names are case-sensitive.

  1. In the left navigation panel, click Domain Management and select your Domain.
  2. Select Add SSO button under SSO Connections section.
  3. Enter the Connection Name in the Connection Name field.
  4. Select SAML for the Connection Type.
  5. Fill in the rest of the fields according to the definitions in the following table.
  6. Click Next until you get to the Confirm screen, review your selections and click Confirm. The Auto-Provisioning, Usage Rules, and Persona Mapping screens are documented separately.
Note: At this point, the SSO Connection has been created, but not enabled. Prior to enabling your connection, proceed to Testing an SSO Connection and then consider adding a Usage Rule to limit the SSO Connection usage to a small group of test users before making it available to all users in your Domain.
Name Description
Name Attribute Required. Specify the name of the attribute coming from the SAML Identity Provider (IDP) that will provide the full name of the user.
Email Attribute Required. Specify the name of the attribute coming from the SAML Identity Provider (IDP) that will provide the email address of the user. This will be used for both the Username and email address of the user. To use a different value for the Username, specify the Username attribute.
Username Attribute Optional. If you would like to use a different attribute for the username instead of your email, you can enter it here. The attribute must supply a username in email format (user@yourdomain.com). If this field is left blank, your email attribute will be used as your Username.
Username Suffix Optional. For use with the Username Attribute in cases where the value is not in an email format. This suffix will be added to the end of the username. For example, if the value passed in to the Username Attribute is User1234 and the Username suffix is @mydomain.com, the username will be set to User1234@mydomain.com.
Group Attribute Optional. This list of groups in which the user is a member. This can be left blank unless the documentation for the Apptio service you are using instructs you to configure it or you want to use Allowed groups.
Allowed groups Optional. If specified, checks the values passed into the Group Attribute to see if they match one or more of the Allowed groups. If not, the User login is denied and their existing Frontdoor user (if any) is disabled.
Upload Metadata Required. Upload the SAML metadata file provided by your IdP team. This file is required to provide the configuration settings necessary to establish the SSO connection. The metadata file must be UTF-8 encoded and it must contain a valid signing certificate.
Always Show Login Prompt If checked, the login prompt will appear every time an user starts a new Apptio session, even if they have an active IdP session.
Initiation Type Select one of the following:
  • Service Provider - Allow login initiated from Frontdoor or your Apptio service.
  • Identity Provider - Allow login initiated from a tile in your organization's IdP.
  • Both

NOTE: SP-Initiated flows are recommended whenever possible. IDP-Initiated flows are not recommended because they are potentially less secure than SP-initiated. Make sure you understand the risks before enabling IdP-Initiated SSO.

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 Equivalent attribute names to be used in the above fields. Where more than one Equivalent attribute name is shown choose one of them to use. Use of the Azure SAML or ADFS SAML attribute names will result in an error

Equivalent attribute name Azure SAML assertion attribute name ADFS SAML assertion attribute name
preferred_username subjectNameID subjectNameID
name, displayName http://schemas.microsoft.com
/identity/claims/displayname 		Not applicable
email,
emailAddress 		http://schemas.xmlsoap.org
/ws/2005/05/identity/claims/
emailaddress 		http://schemas.xmlsoap.org
/ws/2005/05/identity/
claims/emailaddress
groupIds http://schemas.microsoft.com
/ws/2008/06/identity/claims/role 		http://schemas.xmlsoap.org
/claims/Group

Adding a new OIDC Connection

This section uses the values provided by the IdP team for your OIDC application as described in OIDC Preparation. Note that claim names are case-sensitive.

  1. In the left navigation panel, click Domain Management and select your Domain.
  2. Select Add SSO button under SSO Connections section.
  3. Enter the Connection name in the Connection Name field.
  4. Select OIDC for the Connection Type .
  5. Fill in the rest of the fields according to the definitions in the following table.
  6. Click Next until you get to the Confirm screen, review your selections and click Confirm. The Auto-Provisioning, Usage Rules, and Persona Mapping screens are documented separately.
Note: At this point, the SSO Connection has been created, but not enabled. Prior to enabling your connection, proceed to Testing an SSO Connection and then consider adding a Usage Rule to limit the SSO Connection usage to a small group of test users before making it available to all users in your Domain.
Name Description
Name Attribute Required. Specify the name of the claim coming from the OIDC Identity Provider (IDP) that will provide the full name of the user. This defaults to name which is a standard OIDC claim.
Email Attribute Required. Specify the name of the cl coming from the OIDC Identity Provider (IDP) that will provide the email address of the user. This will be used for both the Username and email address of the user. To use a different value for the Username, specify the Username attribute. This defaults to email which is a standard OIDC claim.
Well-known Endpoint Required. The Well-known Endpoint URI (also known as the Discovery endpoint) for your OIDC application.
Client ID Required. The Client ID for your OIDC application.
Client Secret Required. The Client Secret for your OIDC application.
Username Attribute Optional. If you would like to use a different claim for the username instead of your email, you can enter it here. The claim must supply a username in email format (user@yourdomain.com). If this field is left blank, your email claim will be used for your Username.
Username Suffix Optional. For use with the Username Attribute in cases where the value is not in an email format. This suffix will be added to the end of the username. For example, if the value passed in to the Username Attribute is User1234 and the Username suffix is @mydomain.com, the username will be set to User1234@mydomain.com.
Group Attribute Optional. This can be left blank unless the documentation for the Apptio service you are using instructs you to configure it.
Secret Expiration Optional. Select the date that the Client Secret will expire. This will enable Access Administration to show a warning when the Client Secret is about to expire.
PKCE Support If checked, enable PKCE on this connection.

NOTE: If checked, the Well-known configuration document must include the JWKS URI.

Always Show Login Prompt If checked, the login prompt will appear every time an user starts a new Apptio session, even if they have an active IdP session.

Viewing and Editing SSO Connections

In the left navigation panel, click Domain Management and select your Domain. The SSO Connections table shows all of the existing SSO Connections on your Domain. Select the SSO Connection you would like to view or edit. This will open a summary view of your SSO Connection. Click on the ellipsis (3 vertical dots) menu and select from the following menu items:
  • Edit Connection - Click to Edit the connection. This will open Connection Details page. Click Next to access the Auto-provisioning, Usage, Persona and Confirm pages. Changes are not saved until you click the Confirm button on the Confirm page.
  • Test SSO Connection - This executes a test login. See Test Connection and Attribute Mappings for more information.
  • Copy Test URL - This copies the URL used in Test SSO Connection so that it can be sent to a non-SSO Admin users that does not have access to Domain Management.
  • Delete - This deletes the SSO Connection. Note that deletion is final and cannot be undone.

Enable or disable the connection using the Enabled toggle in the SSO Connections table or in the Enabled toggle in Connection Details.