External Widgets
Authentication
PURPOSE
PROS Smart CPQ with Performance Quoting supports integration of customer applications in quote widgets.
The external application must be secured and must use the same identity provider used for PROS Smart CPQ to support Single Sign on.
The aim of this documentation is to explain how this can be done and support authentication protocols with some examples.
AUTHENTICATION SCHEME
PROS Smart CPQ supports SAML and Oauth2 (authorization grant) authentication protocols. The External widget Application should also support one of these to enable SSO when using the external widget feature.
External Widget SSO using SAML
Let's consider using SalesForce as SAML Identity provider. Here is the corresponding SSO flow.
- User logs in to Salesforce (Identity provider) with their credentials.
- Access CPQ from Salesforce → SSO using SAML protocol and Salesforce connected app.
- Open the external Widget from CPQ → SSO using SAML protocol with a Salesforce connected app.
External Widget SSO using Oauth2
Let's consider using Entra ID as OAuth2 provider. Here is the corresponding SSO flow:
- User logs in to Microsoft AD with their credentials.
- Access CPQ (From MS CRM or from Application Portal for example) → SSO using Oauth2 protocol.
- Open the external Canvas from CPQ → SSO using Oauth2 protocol.
EXTERNAL APPLICATION REQUIREMENTS
The customer application must meet the following requirements to work and authenticate correctly using a Quote external widget.
Authorize external application to be embedded
The external application should allow CPQ to embed its content. This can be done by settings on these headers:
Content security policy example:
- Content-Security-Policy: frame-ancestors https://quote.YOUR_REALM_URL.proscloud.com
- Frame-Options example:
- X-Frame-Options: ALLOW-FROM https://quote.YOUR_REALM_URL.proscloud.com Some navigators may support only one of these headers.
YOUR_REALM_URL has to be replaced by your realm (us1, eu1 ...).
Support authentication protocol
The external application must support one of these authentication protocols:
- SAML authentication. The external application must behave as a service provider
- Oauth2 with authorization grant. The external application must behave as an oauth2 client
In both cases, the identity provider must be the same for CPQ and your external application to enable SSO.
Support silent authentication
The external Application should support a silent authentication. This means that the user should not be prompted to provide his username or his domain for example.
All necessary parameters should be provided in the URL that is used to open the external widget. CPQ could provide following attributes to the external widget as query parameters if necessary:
- The authenticated user Id (ex: [email protected])
- The PROS tenant Id
- The PROS environment Id (ex: dev, test, prod,...)
Integration Examples
Warning:
Please consider that following examples do not guarantee a maximum security level for your external applications. These are ONLY examples. They illustrate how Single Sign On can be set between your identity provider and your custom application when using CPQ external Widget feature.
We consider that customer external application already supports OAuth2 or SAML authentication.
OAuth2 using Entra ID
Register your application with your Entra ID tenant
First, register your application with your Entra ID tenant. This will give you an Application ID for your application, as well as enable it to receive tokens.
- Sign in to the Entra ID Portal.
- Choose your Entra ID tenant by selecting your account in the top right corner of the page, followed by selecting the Switch Directory navigation and then selecting the appropriate tenant.
- Skip this step if you only have one Entra ID tenant under your account, or if you've already selected the appropriate Entra ID tenant.
- The selected Entra ID subscription must be the same used with CPQ.
- In the Entra ID portal, search for and select Entra ID.
- In the Entra ID left menu, select App Registrations, and then select New registration.
- Follow the prompts and create a new application (Web application).
- Name is the application name and describes your application to end users
- Under Supported account types, select Accounts in any organizational directory
- Provide the Redirect URI. This is the base URL of your app where users can sign in. Entra ID uses it to return token responses. Enter a value specific to your application
- Once you've completed registration, Entra ID will assign your application a unique client identifier (the Application ID). You will need this value later.
- To find your application in the Entra ID portal, select App registrations, and then select View all applications.
Then configure permissions and a secret for your application.
- Check application redirect URL
- Create a client secret for your application
- Add necessary permissions to your application in the Entra ID
See Entra ID documentation for more information.
Authentication flow using Oauth2 authorization grant and OpenId
The sign-in flow contains the following steps to redirect user to the external application.
Send the sign-in request
There are many ways to send the authentication request. The example below is using openId to get user information directly. See Entra ID doc for more information.
When your web application needs to authenticate the user, it must direct the user to the /authorize endpoint. For our openId example:
- The request must include the scope openid in the scope parameter
- The response_type parameter must include id_token
- The request must include the nonce parameter
So a sample request would look like this:
GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize? client_id={clientId}
&response_type=id_token &redirect_uri={https://Your application URL} &response_mode=form_post
&scope=openid &state=12345
&nonce=7362CAEA-9CA5-4B34-9BA3-52D7C303EBA8
Here are supported request parameters that you can use to configure your authentication request:
| PARAMETER | CONDITION | DESCRIPTION |
|---|---|---|
| tenant | Required | You can use the tenant value in the path of the request to control who can sign in to the application. The allowed values are common, organizations, consumers, and tenant identifiers. |
| client_id | Required | The Application (client) ID that the Entra ID portal – App registrations experience assigned to your app. |
| response_type | Required | Must include id_token for OpenID Connect sign-in. It might also include other response_type values, such as code. |
| redirect_uri | Recommended | The redirect URI of your app, where authentication responses can be sent and received by your app. It must exactly match one of the redirect URIs you registered in the portal, except that it must be URL encoded. If not present, the endpoint will pick one registered redirect_uri at random to which it will send the user back. |
| scope | Required | A space-separated list of scopes. For OpenID Connect, it must include the scope openid, which translates to the "Sign you in" permission in the consent UI. You might also include other scopes in this request for requesting consent. |
| nonce` | Required | A value included in the request, generated by the app, that will be included in the resulting id_token value as a claim. The app can verify this value to mitigate token replay attacks. The value typically is a randomized, unique string that can be used to identify the origin of the request |
| response_mode | Recommended | Specifies the method that should be used to send the resulting authorization code back to your app. Can be form_post or fragment. For web applications, we recommend using response_mode=form_post, to ensure the most secure transfer of tokens to your application. |
| state | Recommended | A value included in the request that also will be returned in the token response. It can be a string of any content you want. A randomly generated unique value typically is used to prevent cross-site request forgery attacks. The state also is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view the user was on. |
| prompt | Optional | Indicates the type of user interaction that is required. The only valid values at this time are login, none, and consent. The prompt=login claim forces the user to enter their credentials on that request, which negates single sign-on. The prompt=none claim is the opposite. This claim ensures that the user isn't presented with any interactive prompt at. If the request can't be completed silently via single sign-on, the Microsoft identity platform endpoint returns an error. The prompt=consent claim triggers the OAuth consent dialog after the user signs in. The dialog asks the user to grant permissions to the app. |
| login_hint | Optional | You can use this parameter to pre-fill the username and email address field of the sign-in page for the user, if you know the username ahead of time. Often, apps use this parameter during reauthentication, after already extracting the username from an earlier sign-in by using the preferred_username claim. |
| domain_hint | Optional | The realm of the user in a federated directory. This skips the email-based discovery process that the user goes through on the sign-in page, for a slightly more streamlined user experience. For tenants that are federated through an on-premises directory like AD FS, this often results in a seamless sign-in because of the existing login session. |
Handle silent authentication
To avoid prompting the user during authentication process you can:
- Use login_hint parameter to pre-fill username
- Use domain_hint to escape domain discovery based on user email
- Use prompt parameter with value none (prompt=none) to ensure user will not be prompted
- The AD admin can give consent on behalf of users to access the Oauth2 application
Successful response
After the user authenticates the Microsoft identity platform endpoint returns a response to your app at the indicated redirect URI by using the method specified in the response_mode parameter.
A successful response when you use response_mode=form_post looks like this:
POST /myapp/ HTTP/1.1 Host: localhost
Content-Type: application/x-www-form-urlencoded
| PARAMETER | DESCRIPTION |
|---|---|
| id_token | The ID Token that the app requested. You can used the id_token parameter to verify the user's identity and begin a session with the user. |
| state | If a state parameter is included in the request, the same value should appear in the response. The app should verify that the state values in the request and response are identical. |
SAML using SalesForce as IDP
SFDC Configuration (IDP)
Get SAML Service Provider (SP) metadata
When a Connected App is being created, some SAML Service Provider Settings fields are required from your SAML external application:
- Entity Id
- ACS URL
- Single Logout URL
- The service provider certificate
You can find these information in your SAML service provider metadata XML.
Enable SalesForce as an identity provider
If not done yet, you need to enable Salesforce as an Identity Provider.
From Setup, enter Identity Provider in the Quick Find box, select Identity Provider, and click Enable Identity Provider.
After you enable Salesforce as an Identity Provider, you can create connected apps to provide access to your external application.
Create a connected App for your client application
Connected Apps can be installed in All Editions.
Follow the Salesforce documentation on how to create a connected app for PROS Home using the following information.
Basic Information
This section will specify basic information about your app, including the app name, logo, and contact information.
- Enter the connected app’s name. This name is displayed in the App Manager and on its App Launcher tile
- Enter the API name used when referring to your app from a program
Web App Settings
This section controls your app’s web settings.
- Select Enable SAML.
- Enter the following data that you can obtain from your external application SAML xml file : Service provider (SP)
- Enter manually Start URL
- Enter manually Entity ID
- Enter manually ACS URL : Assertion URL of your SP
- Enable Single Logout = check
- Enter manually Single Logout URL
- Select Single Logout Binding = HTTP POST
- Select Subject type = User ID
- Select Name ID Format = urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
- Issuer = keep it by default
- Select proper IdP Certificate to use.
- Select Verify Request Signatures. Browse your system for your SP certificate
- Copy the value extracted from SP xml metadata file to a new .crt file adding "BEGIN
CERTIFICATE-----" and "-----END CERTIFICATE". Then you can upload .crt file
- Copy the value extracted from SP xml metadata file to a new .crt file adding "BEGIN
- Optionally, you can choose Encrypt SAML Response. Browse your system for your SP certificate and upload it.
- Select the method you want to use for Block Encryption Algorithm: AES128, AES256 and TRIPLE DES
- Save the new Connected App.
The Connected App will be created and displayed, now click on Manage button to add Custom Attributes and set who can access this app.
Add Custom Attributes
You can add some additional Custom Attributes to send user information to your external application.
Use the New button under the Custom Attributes section
- Scroll to Custom Attributes and click New.
- Set the Attribute key to one specified in the table below.
- Click Insert Field.
- Click $User, $Profile or $UserRole... to add a custom attribute
- Click Insert.
Use profiles and/or permission sets to control who can access this app.
Access permissions
Follow Salesforce documentation Profile or Permission Sets to control who can access this app.
External application configuration (SP)
You external application will need the metadata information of your connected Application (IDP).
It can be download from your Connected App under SAML Login Information using the Download MetaData button.
Then your service provider configuration will depend on how it's implemented on your external application.
Widget Integration
External UI can be displayed in widgets directly in the quote. Authentication has to be managed in the external application (see Authentication).
The external URL has to be stored in the quote (at quote level or at line level) and then this URL is launched depending on the context:
- On OPEN: when the widget is loaded, the URL is opened (URL defined at quote level)
- On REFRESH: when the user clicks on the refresh button, the URL is opened (URL defined at quote level)
- On ROW SELECTED: when the user selects a row in a grid, the URL is opened (URL defined at line level)
Some tokens can be sent dynamically in the URL if they are needed in the external widget. These tokens will be replaced automatically at runtime:
- $USER_ID: current user ID
- $TENANT_ID: current tenant ID
- $ENVIRONMENT_ID: current environment ID
Example of URL stored in the quote
https://URL.com/oauth2-client/secure/aad?login_hint=$USER_ID&tenant=$TENANT_ID&env=$ENVIRONMENT_ID&productId='ABC'