Generating Audit Logs Using Oracle Identity Cloud Service Audit Event REST APIs

Before You Begin

Purpose

In this tutorial, you learn how to make REST API calls to Oracle Identity Cloud Service using the cURL utility, typically to generate Audit Event logs.

Time to Complete

15 minutes

Background

Oracle Identity Cloud Service generates audit data in response to all administrator and end user operations such as User Login, Application Access, Password Reset, User Profile Update, CRUD operations on Users, Group, Applications, and so on. Audit events enable organization administrators to review actions performed by members of organizations using details provided by the Audit logs such as who performed the action, when was it performed, and what action was performed.

Using this data, customers can generate comprehensive reports for administrators or end user activities, capture historical user activity for future analysis, and generate powerful statistics and analytics by ingesting data in analytics tools.

What Do You Need?

• Access to Oracle Identity Cloud Service with the Identity Domain Administrator or Audit Administrator roles.
• Familiarity with the REST architecture style
• A Linux machine with cURL utility available.

  Tip: This tutorial can be executed on other Operating Systems with bash terminal (such as Red Hat, Ubuntu, or OSX), or in Windows (using a bash emulator such as git bash). The commands on different operating systems may present small variations.

Register a Client Application

In this task, you register an application in Oracle Identity Cloud Service. This step is mandatory for performing REST API requests to Identity Cloud Service. In an application, you can:

• Determine what REST API requests the application will be authorized to perform.
• Obtain credentials (client_id and client_secret) that the application can use to obtain an access token programmatically.
• Obtain the application access token via User Interface (UI) to perform REST API calls for testing purposes.

1. In the Oracle Identity Cloud Service console, expand the Navigation Drawer, click Applications, and then Add.
2. Click Confidential Application.

   Tip: The UI provides information about each type of application supported by Oracle Identity Cloud Service.

3. Enter the Application Details as follows and click Next.

   Attribute	Value
   Name	Client Application
   Description	This client will manage Oracle Identity Cloud Service externally using REST APIs.

4. In the Client page, click Configure this application as a client now.
5. Select Client Credentials and JWT Assertion as Allowed Grant Types.

   Tip: The Allowed Grant Types determine how the application access token can be obtained. The grant types are compliant with the OAuth 2.0 standard.

6. On the Client page, scroll down to the Grant the client access to Identity Cloud Service Admin APIs. section, and click Add.
7. In the Add App Role dialog box, select either Identity Domain Administrator or Audit Administrator, and then click Add.
8. Click Next.
9. On the following panes, click Next until you reach the last page, and then click Finish.
10. Copy the Client ID and the Client Secret to a text file, return to the UI, and then click Close.

    Tip: The Client ID and Client Secret are equivalent to service credentials that your client application can use for obtaining access tokens programmatically in Oracle Identity Cloud Service.

11. Click Activate, and then click Activate Application.

    A confirmation message appears.

Get an Access Token

In this task, you obtain an Access Token. This Access Token is required for performing REST API calls in Oracle Identity Cloud Service. The Access Token provides a session (with scope and expiration), that your client application can use to perform tasks in Oracle Identity Cloud Service via REST APIs. For obtaining the token, you will use the client credentials (client_id and client_secret) obtained during the application registration.

1. In a text editor, prepare the cURL command as follows:

   curl -k -X POST -H "Authorization: Basic <base64Encoded client_id:client_secret>" -d "grant_type=client_credentials&scope=urn:opc:idm:__myscopes__" "https://MYTENTANT.identity.oraclecloud.com/oauth2/v1/token"
   

   Replace:

   • <base64Encoded client_id:client_secret>: with the encoded Client Application's client id and client secret.
   • https://MYTENTANT.identity.oraclecloud.com: with Oracle Identity Cloud Service URL.

Note: Use any online base64 encoder to encode the client id and client secret values. Doing so changes the format of the values.

For example, if the client id and client secret values are 123456789abcdefghij:abcde-12345-zyxvu-98765-qwerty, when encoded, it changes the format to MTIzNDU2Nzg5YWJjZGVmZ2hpajphYmNkZS0xMjM0NS16eXh2dS05ODc2NS1xd2VydHk=

2. Verify the cURL command after replacing the actual values and copy its content.
3. At a command prompt, enter the cURL command.
4. Copy the output into a text editor. Using the JSON plugin, you can view the output in the JSON format.

   {
     "access_token":<Your access token value is displayed here>,
     "token_type":"Bearer",
     "expires_in":3600
   }
   

   The output:

   • Contains the Access Token request output in JSON format. The return contains the attributes access_token, token_type, and expires_in.
   • The access_token identifies your client access in Oracle Identity Cloud Service and will be used for subsequent Audit REST API calls. This token is encoded following the JSON Web Token (JWT) standard.

   Tip: To check the JWT token, you can copy the access_token and verify its value using any online JSON Web Token (JWT) debugger.

   • The token_type identifies the Access Token as a Bearer token type. In future requests, you will use this token type to identify your token in the Authorization header of your request.
   • The expires_in identifies the validity period of the Access Token.

Execute Oracle Identity Cloud Service REST Audit API Endpoint

In this task, you execute the Audit REST API call to Oracle Identity Cloud Service. The objective is to show you how the REST Audit API calls are typically executed in Oracle Identity Cloud Service.

1. In the text editor, prepare the cURL command as follows:

   curl -k -X GET -H "Authorization: Bearer ACCESS_TOKEN" "https://MYTENTANT.identity.oraclecloud.com/admin/v1/AuditEvents" 

2. Replace ACCESS_TOKEN with the access token you obtained in the previous task and https://MYTENTANT.identity.oraclecloud.com with your Oracle Identity Cloud Service URL.
3. Verify the cURL command after replacing the actual values and copy its content.
4. At a command prompt, enter the cURL command.

   Note: It is recommended to save this command, as it will be required to apply filters.

5. Copy the output into a text editor. Using the JSON plugin, you can view the output in the JSON format.

   Note: See sample command output at the end of section “Apply Filters to the Oracle Identity Cloud Service REST Audit API Endpoint”.

Apply Filters to the Oracle Identity Cloud Service REST Audit API Endpoint

In this task, you apply filters to the Audit REST API calls made to Oracle Identity Cloud Service. The objective is to show you how these filters are used to generate audit logs for Single Sign-On audit events.

1. In the text editor, copy the cURL command that was used to call the Oracle Identity Cloud Service REST Audit Endpoint in the previous section.
2. To generate the audit log for the Single Sign-On audit event category, modify the Oracle Identity Cloud Service URL to include the following filters:

   Name of Audit Event	Description	Modified Oracle Identity Cloud Service URL with Filter
   Successful User Logins	User logs in successfully	https://MYTENTANT.identity.oraclecloud.com/admin/v1/AuditEvents?filter=eventId%20eq%20%22sso.app.access.success%22
   Successful User Logins using Social IDP	User logs in successfully using Social IDP	https://MYTENTANT.identity.oraclecloud.com/admin/v1/AuditEvents?filter=eventId%20eq%20%22sso.session.create.success%22%20and%20ssoIdentityProviderType%20eq%20%22SOCIAL%22
   Successful User Logins with Selected Attributes	User logs in successfully using selected attributes	https://MYTENTANT.identity.oraclecloud.com/admin/v1/AuditEvents?filter=eventId%20eq%20%22sso.session.create.success%22%20and%20timestamp%20gt%20%222018-05-01T00:00:00.001Z%22%20and%20timestamp%20lt%20%222018-05-02T00:00:00.001Z%22&attributes=actorName,actorDisplayName,actorType,ssoIdentityProviderType,ssoIdentityProvider,clientIp,ssoMatchedSignOnPolicy,ssoMatchedSignOnRule,ssoCompletedFactors,ssoPlatform,ssoBrowser,timestamp,message%22
   Successful User Logins using Local IDP	User logs in successfully using Local IDP	https://MYTENTANT.identity.oraclecloud.com/admin/v1/AuditEvents?filter=eventId%20eq%20%22sso.session.create.success%22%20and%20ssoIdentityProviderType%20eq%20%22LOCAL%22&attributes=actorName,actorDisplayName,actorType,ssoIdentityProviderType,ssoIdentityProvider,clientIp,ssoMatchedSignOnPolicy,ssoMatchedSignOnRule,ssoCompletedFactors,ssoPlatform,ssoBrowser,timestamp,message%22
   Successful User Logins using External IDP (SAML)	User logs in successfully using External IDP (SAML)	https://MYTENTANT.identity.oraclecloud.com/admin/v1/AuditEvents?filter=eventId%20eq%20%22sso.session.create.success%22%20and%20ssoIdentityProviderType%20eq%20%22SAML%22&attributes=actorName,actorDisplayName,actorType,ssoIdentityProviderType,ssoIdentityProvider,clientIp,ssoMatchedSignOnPolicy,ssoMatchedSignOnRule,ssoCompletedFactors,ssoPlatform,ssoBrowser,timestamp,message%22

   For example, if you want to generate the audit log for Successful User Logins with Selected Attributes, in a text editor, prepare the cURL command as follows:

   curl -k -X GET -H "Authorization: Bearer ACCESS_TOKEN" https://MYTENTANT.identity.oraclecloud.com/admin/v1/AuditEvents?filter=eventId%20eq%20%22sso.session.create.success%22%20and%20timestamp%20gt%20%222018-07-01T00:00:00.001Z%22%20and%20timestamp%20lt%20%222018-09-02T00:00:00.001Z%22&attributes=actorName,actorDisplayName,actorType,ssoIdentityProviderType,ssoIdentityProvider,clientIp,ssoMatchedSignOnPolicy,ssoMatchedSignOnRule,ssoCompletedFactors,ssoPlatform,ssoBrowser,timestamp,message%22

   Note: Replace ACCESS_TOKEN and https://MYTENTANT.identity.oraclecloud.com with actual values.

3. Verify the cURL command and enter it at the command prompt.
4. Copy the output into a text editor. Using the JSON plugin, you can view the output in the JSON format.

   For example, if you have generated an output for Successful User Logins with Selected Attributes using the JSON plugin, you can view the logs as shown in the sample command output format.

   Tip: We reduced the sample command output and broke it into multiple lines to simplify the reading.

Want to Learn More?

To learn more about the REST Audit APIs, explore the following tutorials and documents:

• Using the Audit Event APIs: REST API for Oracle Identity Cloud Service
• A-Team Blog: Oracle Identity Cloud Service Audits
• A-Team Blog: Identity Cloud Service Audit Event Rest API