It is important that you always get and exchange the user token, even if the user already has an active session. This ensures that the proper token exchange occurs. A token will be valid for five minutes or until it is exchanged. The token exchange is a one-time only REST call. After the exchange, the token expires and any subsequent calls using this token return HTTP 404.

Note: Ping Identity periodically deprecates obsolete TLS protocols and cipher suites. To stay compatible with these changes, you should ensure that your platform stays within its support life cycle. For example, a Java application should use a Java version that is currently supported by the Java vendor.
  1. Get the user's token.
    After PingOne SSO for SaaS Apps authenticate the user, they will return to one of these URLs:
    • For SP-initiated SSO, the appurl value specified during the HTTP redirect.
    • For IdP-initiated or SP-initiated SSO, the Default Application URL value you assigned on the Create connections page (for SP-initiated SSO the appurl value takes precedence, if specified).

    The user's token is passed as a tokenid POST parameter in the HTTP request.

    Note: POST is the default parameter type, but you can change the token to a query parameter, depending on your binding configuration.
    For example: https://www.mysaas.com/testapp?tokenid=158affc71d6bc65fe2a92ffac7760dce&agentid=0055f3da
  2. Make a REST call using the PingOne SSO for SaaS Apps REST API.
    The REST call identifies the token and specifies the return format for the user attributes.
    This will be an HTTP GET call structured like this: https://sso.connect.pingidentity.com/sso/TXS/2.0/<formatNumber>/<tokenid>

    Accepted formatNumber parameters are indicated by:

    • 1 (JSON format)
    • 2 (Properties format)
  3. Process the user attributes returned.
    PingOne SSO for SaaS Apps will return the following attributes, formatted according to your choice (JSON or Properties):
    pingone.subject
    The user name of the authenticated user. This is the subject for the target resource of the SSO transaction. It is important that you validate this. The user identified by pingone.subject must belong to the organization identified by pingone.idp.id.

    This value can be the same as the pingone.subject.from.idp value. However, it will be a different value if an attribute mapping transformation or a different attribute is used for the target resource.

    pingone.subject.from.idp
    The value used to authenticate against the IdP. For SAML transactions, this is the value in the Subject attribute of the assertion returned from the IdP.
    pingone.saas.id
    The cloud application to which the token is issued. This will be your SaaS ID.
    Tip:

    Make sure your application's SaaS ID value matches the pingone.saas.id value. This prevents tokens issued for other applications from accessing your application.

    pingone.idp.id, pingone.idpid
    The id of the PingOne SSO for SaaS Apps customer connection associated with the currently authenticating user.
    • If your application is using the REST API, this value is returned in JSON/XML, and has the format "pingone.idp.id" (note the two periods).
    • If your application is using SAML, this value is always returned in the attribute statement as "pingone.idpid" (note the single period). This value is always returned by PingOne, so you do not need to configure an attribute mapping.
    Tip:

    Identifying users with a combination of the pingone.idp.id and pingone.subject parameters prevents other identity providers (IdP) from using identifiers that resemble credentials from your intended IdP.

    pingone.authn.context
    The authentication context for which the user is authenticated by the identity bridge.
  4. Write the supporting code to implement the token exchange. You can use these samples as a basis:
    As a best practice, always have your client do an HTTP redirect after exchanging the token.
  5. Next, you will need to Testing your application using the built-in IdP.