Integrate Third-Party Applications

A utility's online portal can require that authenticated web applications are available to their customers alongside Digital Self Service - Transactions to maintain a single, integrated experience for their customers. For example, a utility can link to a customer rewards program and website directly from Digital Self Service - Transactions, redirecting the customer without requiring them to log in again.

Refer to the information below to integrate your third-party application with Digital Self Service - Transactions.

Resource Requirements

The third-party application or partner resource must expose an endpoint that consumes a JWT assertion form parameter using a POST method. The resource uses the JWT assertion to request an access token from Oracle Cloud Infrastructure Identity and Access Management. Upon successful validation of the JWT assertion, an access token including the web user ID is sent to the resource. The resource uses the access token along with the JWT assertion to create a user session. At this point, a 302 redirect to the resource can be sent to the browser to provide the user with access to the resource.

A utility must ensure any third-party resources meet integration requirements. The third-party application or partner resource must expose an endpoint that consumes a JWT assertion form parameter using a POST method. The resource uses the JWT assertion to request an access token from Oracle Cloud Infrastructure Identity and Access Management. Upon successful validation of the JWT assertion, an access token including the web user ID is sent to the resource. The resource uses the access token along with the JWT assertion to create a user session. A 302 redirect to the resource can then be sent to the browser to provide the user with access to the resource.

Note: A GET method is a supported option as well. In this case, a jwt_assertion query parameter contains the JWT assertion. This option is considered less secure and prone to issues with very large JWT assertions. For these reasons Oracle Utilities recommends a POST method strategy instead.

Rules of redirection to specific partner resources are up to the implementation. For example, the partner can expose an endpoint that contains targetResource as one of query parameters, which specifies a page where the user is redirected after successful JWT assertion validation. In this scenario, it is up to the partner resource to verify the validity of the resource specified in the targetResource parameter.

Endpoint Specification

A Digital Self Service - Transactions resource sends the JWT assertion in the body of a POST method. The endpoint specification requirements are provided below for the recommended POST method.

  • Method: POST
  • Content-Type: application/x-www-form-urlencoded
  • Endpoint Path: The path can be any valid path, and this path information must be shared with Oracle Utilities.
  • Endpoint Form Parameters:
    • jwt_assertion: String containing the JWT assertion.
  • Endpoint Responses: The response must perform the required redirection, and aside from the redirection the responses are up to the utility to meet their requirements. Example responses include:
    • 302: Successful response with a location header pointing to partner resource site page.
    • 302: Error response with location header pointing to an error page on partner resource site page.

Contact the Oracle Utilities Delivery Team for methods in which to securely share this information.

Oracle Cloud Infrastructure Identity and Access Management Configuration

Oracle Cloud Infrastructure Identity and Access Management configuration for a third-party application or partner resource requires the creation of an application which supports JWT Assertion authorization.

  1. Navigate to the Oracle Cloud Infrastructure Identity and Access Management Admin Console and select the Applications menu.
  2. Add a new application and select Confidential Application from the list of applications.
  3. Enter the following information in the new application wizard, and then click Next:
    • Name: For example, enter Partner-Resource. You will need to provide this to your delivery team to complete the integration.
    • Application URL: Provide the URL for the third-party application or partner resource.
    • Enforce Grants as authorization: Ensure this option is cleared.
  4. On the next page, select the Configure this application as a client now option and complete the following fields:
    • Authorization: Within the Allowed Grant Types area, select JWT Assertion.
    • Redirection URL: Provide the URL to the main landing page of your third-party application or partner resource.
    • Token Issuance Policy: Select the Add app roles option, and then click Add to add each of the following roles:
      • Me
      • Signin
      • Verify Email
      • Forgot Password
      • Self Registration
      • Reset Password
      • User Administrator
  5. Click Next, and in the Web tier policy area, verify that Skip for later is selected.
  6. Click Finish, and make note of the Client ID and Client Secret that are generated. You will provide these to your Oracle Utilities Delivery Team to complete the integration.
  7. After the application has been created in Oracle Cloud Infrastructure Identity and Access Management, you activate the application. From the Admin Console, select Applications, select the check box for the application you created, and then from the Actions drop-down list select Activate.
  8. Navigate to Menu, then Settings, and then select Trusted Partner Certificates.
  9. Select the option to Import Certificate, and then select the Digital Self Service - Transactions certificate provided by Oracle Utilities.

Back to Top