Subscribe to events from ForgeRock

Standard

ForgeRock supports sending events to Eventarc for delivery to interested subscribers.

ForgeRock offers an end-to-end, AI-driven platform purpose-built for all identities and for any environment—on-prem, multicloud, or hybrid. A single, unified platform offers access management, identity management, user-managed access, directory services, and an identity gateway. Learn more about using ForgeRock.

To subscribe to events from ForgeRock, complete the following steps:

Before you begin

Ensure that you have enabled the Eventarc and Eventarc Publishing APIs:
Console
Enable the APIs
gcloud
```
gcloud services enable \
  eventarc.googleapis.com \
  eventarcpublishing.googleapis.com
```
If you are enabling a customer-managed encryption key (CMEK) for a channel, enable the Cloud Key Management Service API.
Console
Enable the API
gcloud
```
gcloud services enable cloudkms.googleapis.com
```

Create a channel for ForgeRock events

To subscribe to events from ForgeRock, you must create a channel:

gcloud eventarc channels create CHANNEL_NAME \
    --location LOCATION

Replace the following:

CHANNEL_NAME: a name for the channel
LOCATION: a supported Eventarc region

Note: For this Pre-GA feature, only us-central1 is supported as a location. You cannot create a channel in any other location.

You can optionally use a --crypto-key flag to specify a fully qualified Cloud KMS key name in the format projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME.

For more information, see Use customer-managed encryption keys.

Confirm that the channel is active

After creating a channel, you can retrieve the channel properties and confirm that it is active:

Console

In the Google Cloud console, go to the Eventarc > Channels page.

Go to Eventarc
From the list of channels, click a channel to view its details.

The channel status should be Active.

gcloud

gcloud eventarc channels describe CHANNEL_NAME \
  --location LOCATION

Replace LOCATION with a supported Eventarc region.

The output is similar to the following:

createTime: '2022-04-26T20:46:06.113533183Z'
name: projects/PROJECT_NAME/locations/LOCATION/channels/CHANNEL_NAME
pubsubTopic: projects/PROJECT_NAME/topics/eventarc-channel-LOCATION-CHANNEL_NAME-465
state: ACTIVE
uid: 86391a0b-a264-4172-a3b5-a893179f1d1a
updateTime: '2022-04-26T20:46:10.106938915Z'

Deploy an event receiver

To test the configuration, deploy an event receiver—in this case, a Workflows workflow that logs received events—and create an Eventarc trigger that routes events from ForgeRock to the event receiver. You must use a service account that has been granted the appropriate roles to access your Google Cloud project resources.

Enable the Workflows and Workflow Executions APIs:

Console

Enable the APIs

gcloud

gcloud services enable \
    workflows.googleapis.com \
    workflowexecutions.googleapis.com

Create a service account and grant it the roles/logging.logWriter and roles/workflows.invoker roles:
Console
1. In the Google Cloud console, go to the Service Accounts page.
  
  Go to Service Accounts
2. Select your project.
3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name. Optionally, add a description.
4. Click Create and continue.
5. In the Select a role list, select Logging > Logs Writer.
6. Click Add another role and select Workflows > Workflows Invoker.
7. Click Continue.
8. To finish creating the service account, click Done.
gcloud
```
gcloud iam service-accounts create MY_SERVICE_ACCOUNT
gcloud projects add-iam-policy-binding PROJECT_ID \
    --role="roles/workflows.invoker" \
    --member="serviceAccount:MY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"
gcloud projects add-iam-policy-binding PROJECT_ID \
    --role="roles/logging.logWriter" \
    --member="serviceAccount:MY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"
```
Replace MY_SERVICE_ACCOUNT with a name for your service account.
For more information about how to control access to Workflows resources, see Use IAM to control access.
Create and deploy a workflow that logs a received event:
Console
1. In the Google Cloud console, go to the Workflows page.
  
  Go to Workflows
2. Click Create.
3. Name your workflow logEventsWorkflow.
4. Choose a supported Workflows region; for example, us-central1.
5. Select the Service account you previously created.
6. Click Next.
7. In the workflow editor, enter the following definition for your workflow:
```
main:
  params: [event]
  steps:
  - logStep:
      call: sys.log
      args:
        data: ${event}
```
8. Click Deploy.
gcloud
1. Open a terminal or Cloud Shell.
2. In your home directory, create a new file called logEventsWorkflow.yaml.
3. Copy and paste the following into the new file and save it:
```
main:
  params: [event]
  steps:
  - logStep:
      call: sys.log
      args:
        data: ${event}
```
4. Deploy the workflow:
```
gcloud workflows deploy logEventsWorkflow \
    --source=logEventsWorkflow.yaml \
    --location LOCATION
```
  Replace LOCATION with a supported Workflows region; for example, us-central1.

Create an Eventarc trigger to route events from ForgeRock to the target workflow:

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-workflow=logEventsWorkflow  \
    --event-filters=type=forgerock.v1.event \
    --channel=CHANNEL_NAME \
    --service-account="MY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"

Replace TRIGGER with the ID of the trigger or a fully qualified identifier. For example, my-event-channel-trigger.

For more information, see Publish and route custom events.

Create a service account for publishing events

Create a service account for the publishing of events and grant it the roles/eventarc.publisher role.

Console

In the Google Cloud console, go to the Create service account page.

Go to Create service account
Select your project.
In the Service account name field, enter a name. For example, forgerock-sa. The Google Cloud console fills in the Service account ID field based on this name. Optionally, add a description. For example, ForgeRock service account.
Click Create and continue.
In the Select a role list, select Eventarc > Publisher.
Click Continue.
To finish creating the service account, click Done.

gcloud

  gcloud iam service-accounts create PUBLISHING_SERVICE_ACCOUNT
  gcloud projects add-iam-policy-binding PROJECT_ID \
    --role="roles/eventarc.publisher" \
    --member="serviceAccount:PUBLISHING_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"

Replace PUBLISHING_SERVICE_ACCOUNT with a name for your service account. For example, forgerock-sa.

Create and download a service account key

Create and download a service account key that can be used to authenticate as your service account. This key is required when configuring an audit event handler for ForgeRock. For more information, see Create and manage service account keys.

Console

In the Google Cloud console, go to the Service Accounts page.

Go to Service Accounts
Select your project.
Find the row of the ForgeRock service account that you previously created and that you want to create a key for. In that row, click and then select Manage keys.
On the Keys page, click Add key > Create new key.
For the Key type, select JSON.
Click Create.

gcloud

gcloud iam service-accounts keys create SERVICE_ACCOUNT_KEY \
    --iam-account PUBLISHING_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com

Replace the following:

SERVICE_ACCOUNT_KEY: the path to an output file for the private key; for example, ~/forgerock-sa-key.json.
PUBLISHING_SERVICE_ACCOUNT: the ForgeRock service account name you created previously.

The service account key is downloaded to your machine. After you download the key file, you cannot download it again. You will need to copy the contents of this file in the following step.

Make sure to store the key file securely because it can be used to authenticate as your service account. You can move and rename this file.

Configure the audit event handler

A ForgeRock audit event handler manages audit events, sends audit output to a defined location, and controls the output format. You can use the audit event handler to confirm that events triggered through ForgeRock are being routed by Eventarc to the workflow that logs the received events.

Log into ForgeRock's Identity Management (IDM) console. For details about logging in, refer to Downloading and starting the server.
Select Configure System Preferences and then click the Audit tab.
In the Event Handlers list, select EventarcAuditEventHandler.
Click Add Event Handler.
In the Add Audit Event Handler dialog, complete the following:
1. Give your audit event handler a unique Name.
2. In the Audit Events list, select the items that will generate events. (For testing purposes, select them all.)
3. Confirm that the Enabled toggle is on.
4. In the jsonCredentials field, paste the contents of the service account key that you copied previously.
5. Specify the remaining fields appropriately. For the Event type field, type forgerock.v1.event.
6. Click Submit.
7. Click Save.

Test the routing of events

You can now test the entire configuration by accessing ForgeRock to trigger an event, and ensuring that the event from ForgeRock is routed to the workflow event receiver which logs the received event.

Log into ForgeRock's Identity Management (IDM) console.
Select Configure > System Preferences and then click the Audit tab.

This triggers the access audit event.

To verify that a workflow execution was triggered by the received event, list the last five executions:

gcloud workflows executions list ${MY_WORKFLOW} --limit=5

The output should be similar to the following, listing a NAME and STATE equal to SUCCEEDED for each workflow execution.

NAME: projects/1051295516635/locations/us-central1/workflows/logEventsWorkflow/executions/674b5783-deec-4d1b-be1d-b067f7b32971
STATE: SUCCEEDED
START_TIME: 2022-07-13T22:01:06.314980819Z
END_TIME: 2022-07-13T22:01:06.637825944Z

Every time a workflow executes a single run of the logic contained in a workflow's definition, it automatically triggers at least two execution logs: one at the start of an execution and one at the end. To view the logs do the following:
1. In the Google Cloud console, go to the Workflows page:
  
  Go to Workflows
2. To access a workflow's Details page, click the workflow's name.
3. To view the execution details, in the Executions tab, click a specific Execution ID.

What's next

Learn more about third-party events and custom events.
Learn more about Eventarc