4 Accessing the GraphQL APIs Using Account-Scoped Tokens

Third-party partner applications and users can access the set of GraphQL APIs that support a utility environment. The integration from a third-party partner application to a utility's GraphQL API environment requires a connection between the application and the utility's Oracle Identity and Access Management instance through OAuth2 and OpenId Connect. A user can obtain an account-scoped access token that allows retrieving user data from the GraphQL APIs for a particular account.

Note:

This topic discusses a GraphQL API integration scenario between Oracle Utilities, a third-party partner, and a utility. A utility can also choose to complete the integration requirements of a third-party partner directly without involvement with a third-party partner, and in this scenario a utility would complete all third-party partner integration requirements listed below.

Retrieving Account-Scoped Access Tokens

Access to GraphQL API data and queries requires access tokens to confirm authentication. GraphQL API users are required to retrieve and extract an authorization code, and use this value along with other identifying information to receive an account-scoped access token.

Requirements to Supply to Oracle Utilities

The third-party partner is required to provide Oracle Utilities with redirect URIs, which are the URLs where the authorization codes are sent to the third-party application. A redirect URI is required for each utility a third-party partner integrates with, and each environment or tier for that utility, which commonly consists of a stage environment and production environment. This means at least two redirect URIs are commonly required for each utility that a third-party partner integrates with.

Along with redirect URIs, third-party partners must provide an explanation of the type of access required. For example, a third-party may request read style access for utility customer billing data. These requests are used to determine the required scopes to grant to the third-party partner.

Requirements Supplied to a Third-Party Partner

The following information is provided by Oracle Utilities to third party partners for each applicable utility client.

  • OpenId Connect Discovery Endpoints: Endpoints are provided for each environment a utility has, which commonly includes a stage environment and a production environment. The endpoints are of the format https://idcs-[instance_id].oraclecloud.com/.well-known/openid-configuration.
  • Client Credentials: Each set is applicable to a given utility and the relevant environments:
    • client_id
    • client_secret
  • Scopes: A list of scopes is provided by Oracle Utilities based on the level of access requests. Be aware that if scopes are missing this can result in errors when using the GraphQL APIs. This results in errors that list information such as 
    Required scopes 'scope_name' not present in authorization context
    . If this occurs, contact Oracle Utilities to review scope definitions and confirm the required scopes are included in the application redirects.

Configuring the Authorization Flow to Obtain Account-Scoped Access Tokens

A third-party partner must configure their application as part of the authorization flow to obtain the required account-scoped access tokens. The authorization flow is described below, and clarifies the steps in the flow that require third-party partner configuration support.

  1. A user clicks a link in the third-party web application, requesting access to protected resources.

  2. The application redirects the browser to the Oracle Identity and Access Management authorization endpoint with a user login request.

    The third-party partner must configure this application redirect. The request URL contains query parameters that indicate the scope of access being requested and is in the following format:

    GET https://idcs-[instance_id].oraclecloud.com/oauth2/v1/authorize?client_id=[client_id]&response_type=code&redirect_uri=[redirect_uri]&scope=[scopes]&state=[random_string]
    Where:
    • [instance_id] can be retrieved from one of the OpenId Connect Discovery Endpoints provided by Oracle Utilities.
    • [client_id] is provided by Oracle Utilities.
    • [redirect_uri] is the redirect URI that is provided by the third-party partner to Oracle Utilities.
    • [scopes] is the full list of scopes to include in the request, and these scope names are provided by Oracle Utilities. In addition to the scopes provided by Oracle Utilities, it is required to include the scope openid in the list of scopes.
    • [random_string] is a randomized string provided by the third-party partner.
    • An example request is provided below:
      https://idcs-45fa2455571f40e087f43f850d8f1337.identity.oraclecloud.com/oauth2/v1/authorize?response_type=code&client_id=Opower_SSO_util_stage_testpartner_APPID&scope=openid+opower_consumer_util_testpartner_stageperm.func.coreEntities.utilityIds.read&redirect_uri=https://testpartner.com/auth/redirect&state=fd7f976d-24bc-4ae4-8c9b-891814df170e
  3. If the user is not already logged in, Oracle Identity and Access Management challenges the user to authenticate, and verifies the user's credentials.

  4. If the login is successful, Oracle Identity and Access Management redirects the user's browser back to the application with an authorization code. An example of this response is provided below:

    https://testpartner.com/auth/redirect?code=891814df170e

  5. The third-party partner application must be configured to extract the authorization code and makes a request to an identity domain to exchange the authorization code for an access token.

    curl -i -u [client_id]:[client_secret]
-H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8'
--request POST https://idcs-[instance_id].oraclecloud.com/oauth2/v1/token
-d 'grant_type=authorization_code&code=[authorization_code]'
    Where:
    • client_id and client_secret are provided by Oracle Utilities, and this operation performs Base64 encoding on the values.
    • [instance_id] can be retrieved from one of the OpenId Connect Discovery Endpoints provided by Oracle Utilities.
    • [authorization_code] is the authorization code extracted from the response provided by Oracle Identity and Access Management.

    • An example request is provided below:

      curl -i -u 'Authorization: Basic a2ZmamRhbGtma2xkYXZrbGRha2xkYWexy2RhaXVmICBhZGlvZmogYWxkZmpsamUgbCBxb2U'
-H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8'
--request POST https://idcs-45fa2455571f40e087f43f850d8f1337.identity.oraclecloud.com/oauth2/v1/token
-d 'grant_type=authorization_code&code=891814df170e'
  6. Oracle Identity and Access Management validates the grant and user data associated with the third-party partner application request to the identity domain.

  7. An account-scoped access token, an identity token, and optionally a refresh token are returned. The account-scoped access token contains information about which data the application can request on behalf of the user. The application can use this token when requesting APIs on behalf of the user. These API calls can be determined and constructed through query introspection and testing as described in Building Queries and Exploring Data.

    The third-party partner application can further use the identity token to initiate the Single Logout flow with Oracle Identity and Access Management if required.

Constructing the Base URL

A GraphiQL Integrated Development Environment (IDE) provides access for you to explore the schema and run queries using account-scoped access tokens. You can access the IDE using the following URL structure:

  • Stage Environment: https://api-stage.us.opower.com/[utilityCode]/graphql

    This environment is intended for API call and feature testing.

  • Production Environment: https://api.us.opower.com/[utilityCode]/graphql

    This environment is intended to be used for updates or retrievals from your production system that directly supports your customers.

Where:

  • utilityCode is a three or four letter code for a utility. Contact Oracle Utilities if you are unsure of the utility code for the utility you are integrating with.

For example, a utility with the utility code of abc can access their GraphQL IDE at https://api.us.opower.com/abc/graphql. Additionally, a demonstration area accessible for all users uses the utility code of util and can be accessed at https://api.us.opower.com/util/graphql.