Oracle Identity Cloud Service: Integrating with Splunk


Options



Before You Begin

Purpose

In this tutorial, you learn to integrate Oracle Identity Cloud Service REST APIs with Splunk for external monitoring.

Time to Complete

30 minutes

Introduction

Oracle Identity Cloud Service (IDCS) follows a REST API-first strategy, which means that 100% of the product (including administrative functionalities) are exposed via REST APIs. Because of this, you can basically perform any task programmatically.

In this tutorial, we take advantage of IDCS REST APIs for implementing a monitoring integration via Splunk.

Tip: Oracle offers native management solutions for Identity Cloud Service (Cloud Portal KPIs/Runtime Graphs, Identity Cloud Service reports, and Management Cloud) that do not require configuration. The integration between IDCS and Splunk can be useful for those that are already using this solution.

Architecture

In this tutorial, you integrate Identity Cloud Service and Splunk following the conceptual architecture below:

Diagram listing the components involved in the Splunk integration. For more details, check the text describing the scope right after the image.
Description of this image

In this integration:

  • Splunk regularly requests the Reports endpoint in Identity Cloud Service using the REST Modular Input.
  • Identity Cloud Service validates requests from Splunk (using OAuth 2.0) and retrieves report information in JSON, that's parsed by Splunk.
  • System Administrators can access Splunk to gather consolidated information.

What Do You Need?

  • Splunk Enterprise with the REST Modular Input installed
    • Tip: In this tutorial, we used Splunk v6.5 with REST Modular Input v1.4
  • Access to Identity Cloud Service as Identity Domain Administrator.

Register a Client Application in Identity Cloud Service

Create and activate an Application

In this task, you configure and activate the Splunk Monitoring application in Oracle Identity Cloud Service.
The application is a requirement for making REST API calls to Identity Cloud Service.

  1. In the Identity Cloud Service console, expand the Navigation Drawer , click Applications, and then click Add.

  2. Select Trusted Application or Confidential Application.

    Tip: The UI provides information about each type of application supported by Oracle Identity Cloud Service.
  3. Enter Splunk Monitoring as the Name, optionally provide an Application Icon and Description and then click Next.
    4. Creating Splunk Application in Identity Cloud Service UI
    Description of this image

    Click Configure this application as a client now.

  4. Enter the information as follow and then click Next.
    5. Application wizard - Values for the Authorization page
    Attribute Value(s)
    Allowed Grant Types Assertion
    Refresh Token
    Grant the client access to Identity Cloud Service Admin APIs Identity Domain Administrator
    Creating application - Authorization settings
    Description of this image
  5. Click Finish.
  6. Save the Client ID and the Client Secret, and then click Close.
    7. Application Added screen in Identity Cloud Service UI - Client ID and Secret
    Description of this image
    Tip: The Client ID and Client Secret are equivalent to a credential (ID and password) that your application uses to communicate with Oracle Identity Cloud Service.
  7. Click Activate, and then click Activate Application. Oracle Identity Cloud Service displays a confirmation message.

Get an Access Token

In this task, you get an Access Token for Splunk. The Access Token provides a session (with scope and expiration), that your Splunk can use to make REST API requests in Oracle Identity Cloud Service.

Note: In communications between servers and no users -- like in the Splunk and IDCS integration --, the access token should ideally be obtained programmatically by Splunk using the OAuth client credentials flow. Since Splunk does not support this flow, you generate the access token via UI.
  1. In the Splunk Monitoring application page, click Generate Tokens.
    2. Splunk Monitoring Application Page. Mouse over Generate Tokens button.
    Description of this image
  2. Select Customized Scopes and Include Refresh Token and then click Download Token.
    3. Identity Cloud Service Generate Tokens window. Mouse over the Download Token button.
    Description of this image
  3. Save the tokens.tok file in a temporary folder.
    4. Tip: The tokens.tok file contains the access token that identifies your client access in Oracle Identity Cloud Service and will be used by Splunk to make REST API calls. This token is encoded following the JSON Web Token (JWT) standard.
  4. Open the tokens.tok file in a text editor.
  5. Copy the Select and copy the access token value -- app_access_token -- and the refresh token -- refresh_token -- values between the double quotes (").
    6. Text editor with the access token and refresh token highlighted.
    Description of this image

Configure the REST input in Splunk

In this task, you create a REST input for Oracle Identity Cloud Service reports API.

Create the REST Input

  1. On Splunk and click Add Data.
  2. Click Monitor.
  3. Click REST.
  4. Enter information as follows and then click Next > Done.
    5. Splunk - Values for the REST Input
    Attribute Value(s)
    Name IDCS Login
    Endpoint URL YOUR_IDCS_HOST/report/v1/Reports
    HTTP Method POST
    Request Payload { "schemas": ["urn:ietf:params:scim:schemas:oracle:idcs:Report"], "outputFormat": "json", "reports": [{ "name": "userLogin", "type": "count", "correlationId": "userLoginReport" }] }
    Authentication Type OAUTH 2
    OAUTH 2 Access Token YOUR_ACCESS_TOKEN
    OAUTH 2 Refresh Token YOUR_REFRESH_TOKEN
    OAUTH 2 Token Refresh URL YOUR_IDCS_HOST/oauth2/v1/token
    OAUTH 2 Client ID YOUR_APP_CLIENT_ID
    OAUTH 2 Client Secret YOUR_APP_SECRET
    HTTP Header Properties Content-Type=application/json
    Response Type json
    Index Error Responses selected
    Source type _json
    Creating REST API input form in Splunk UI
    Description of this image

Verify the integration

  1. In Splunk home, click Search & Reporting.
  2. Click Data Summary.
  3. Click Sources > IDCS Login.
    4. Splunk displays the Identity Cloud Service login metrics in JSON Format.
    Splunk UI displaying IDCS Login data in JSON format
    Description of this image

At this point, Splunk is capable of querying report data from Identity Cloud Service REST APIs. With this data, you can setup Splunk reports, dashboards, and instrumentations. In the next section, you have a brief introduction about how to configure a Splunk dashboard based on Identity Cloud Service data.

Optional: Configure Splunk reports and dashboards

In the previous section, you configured Splunk to query report data from Identity Cloud Service REST APIs. With this data, you can setup Splunk reports, dashboards, and instrumentations.

In this optional section, you have a brief introduction about how to configure a Splunk dashboard to present the Identity Cloud Service data.

Generating dashboards and reports in Splunk from REST/JSON requires manual configuration of few objects:

  • Field Aliases: Required by Splunk to get specific values from JSON arrays.
    • Tip: You use filter aliases because Splunk is not able to process JSON arrays (containing characters such as "{" and "}"). Trying to consume these fields without an alias generates the error "Field Name can not contain whitespace, double quotes, single quotes, curly braces or asterisks".
  • Data Sets: Sets a scope for data model reports based on search criteria.
  • Data Model: Enable users to easily create reports in the Pivot tool based on data sets, transformations, lookups, and evaluation rules.
Note: This tutorial is focused on Oracle Identity Cloud Service integrations. To learn more about Splunk data presentation and instrumentation, check its official documentation.

Create a Filter Alias

  1. In Splunk home, click Search & Reporting.
  2. Click Settings > Fields.
  3. On Field aliases, click Add new.
    4. Splunk UI. Add new button next to Field aliases row
    Description of this image
  4. Enter the following information and click Save.
    5. Splunk - Values for the Filter Alias
    Attribute Value(s)
    Source type _json
    Destination App search
    Name idcs_json
    Apply to sourcetype
    named _json
    Field aliases
    • reports{}.correlationId = correlationId
    • reports{}.name = name
    • reports{}.status = status
    • reports{}.totalResults = totalResults
    • reports{}.type = type
    Splunk UI. Add field aliases screen
    Description of this image
  5. In the _json : FIELDALIAS-idcs_json row, click Permissions.
    6. Splunk UI. Permissions next to aliases
    Description of this image
  6. Select All apps and click Save.

Create a Data Model and Data Set

  1. Click Settings > Data models.
  2. Click New Data Model. Enter a Title, ID, and Description of your preference, and then click Create.
  3. Click Add Dataset > Root Event.
  4. Enter IDCS Login as name and source="IDCS Login" as a constraint and click Preview.
    5. A sample of results should be displayed on the screen.
    Splunk UI. Add Event Dataset screen with previous results under the form.
    Description of this image
  5. Click Save.
  6. Click Add Field > Auto-Extracted.
  7. Click Add by Name. Enter correlationId as field.
  8. Click Add by Name. Enter totalResults as field.

    9. The data model will display the new fields:

    Splunk UI. Data model with new fields available.
    Description of this image

Create a Report and a Dashboard

  1. Click Pivot.
  2. Click IDCS Login.
  3. Click Single Value.
    4. Splunk UI. Single Value button.
    Description of this image
  4. Under Value, select:
    5. Splunk - Values for Single Value Dashboard
    Attribute Value(s)
    field totalResults
    value Latest
    Caption Successful Logins (last count)
    Splunk UI. Single Value options.
    Description of this image
  5. Click Add Sparkline > time.
    6. Splunk UI. Adding a sparkline.
    Description of this image
    Splunk will display a report with successful and login counts and trend:
    Splunk UI. Preview for the single value report.
    Description of this image
  6. Optionally, save the report to an existing or new dashboard panel or as a report.

Optional: What's Next?

Now that you know how to gather Identity Cloud Service data in Splunk, you can expand your queries for a better monitoring experience.

Splunk UI. Expanded Dashboard with more reports from Identity Cloud Service.
Description of this image

You can expand the integration in the following areas:

  • Expand Splunk data models, datasets, and lookups to parse more information retrieved by IDCS.
  • Work on Splunk datasets to perform nested searches on JSON. You can do it using Splunk's spath.
  • Expand the REST input to query more reports in Identity Cloud Service. The Identity Cloud Service Postman collections provide few samples for making requests for additional reports.
  • Customize Splunk to use client_credentials authentication in OAuth, which is the ideal OAuth authorization flow for Server to Server communication.

Want to Learn More?

To learn more about how to integrate Oracle Identity Cloud Service with Java Client and Resource Server applications, try the tutorials:

To learn more about the Identity Cloud Service REST APIs, explore the following tutorials and documents:

Credits

  • Developer(s): Frederico Hakamine