Authentication

In this module, we'll explore how to obtain and use Bearer tokens on REST API endpoints that require authentication.

For the sample REST server, we're going to be using... CRIBL! That's right, Cribl itself has an API you can use to interact with your data, environment, users, and more.

To get started, you'll need to obtain a Bearer token from inside the Cribl portal. Note that the method for obtaining API authentication will vary from system to system.

Create an API token in Cribl

There are two stages to getting a usable API token:

1. First, you'll create an API credential, which will give you a Client ID and a Client Secret
2. Next, you use those two items to generate an API Bearer Token.

To get an API Client ID and Client Secret:

In the Cribl portal, click the Products menu at the top, then Organization. Under the Organization options on the left-hand toolbar, click API Credentials.

1. Click Add Credential in the upper-right corner.
2. Give the new credential a name (letters, numbers, and hyphens only)
3. Save it

No, really, that's it. You don't need to set any other options like Organizattion permissions, workspace permissions, etc. At least not for this example. It's important to note that, depending on which data you're trying to get at within Cribl, you might need those higher-level permissions. But for today, we're just keeping things simple.

Now we're going to get an API bearer token. I'm going to walk you through it manually at the command line first but, to be perfectly honest, you probably will be doing this as part of a scripted action in real life, so I'm going to offer a little bit of automation after the manual process.

Getting an API bearer token - the hard way

1. First, you'll want to copy both the ClientID and the Client Secret from the API Credentials screen
2. Next, you'll want to execute the following command in your terminal / command prompt window:

curl --request POST \
--url https://login.cribl.cloud/oauth/token \
--header "Content-Type: application/x-www-form-urlencoded" \
--data 'grant_type=client_credentials&client_id=<clientId>&client_secret=<clientSecret>&audience=https%3A%2F%2Fapi.cribl.cloud' | jq

3. In the curl command above, replace <clientId> and <client_secret> with your ACTUAL client ID and client secret.

note

REALLY IMPORTANT NOTE: Lots of folks get stuck at this point because they're actually using a different environment than regular production Cribl cloud. To be 100% certain you have the right command, look at the "Add Credential" button on the API Credentials page. Do you see that little question-mark just to the left? Click it. In that pop-up box you'll get the correct format for the curl command for both the API bearer token AND making API requests.

The response will look something like this:

{
  "access_token": "eyJhb..NO..I'M..NOT..ACTUALLY..GIVING..YOU..MY..BEARER..TOKEN..GET..YOUR..OWN..qOWg",
  "scope": "user:read:workergroups user:update:workergroups user:read:connections user:update:connections user:update:workspaces user:read:workspaces",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Using the Cribl API - the hard way

Now that you have a bearer token, you can use it in an API command. To do that, we need one more piece of information - our Cribl URL (sometimes called your "tenant" URL).

To get that, click the Products menu at the top left corner. Then select Workspace, and then Access on the left-hand navigation bar. Find the Cribl.Cloud URL. That's your tenant ID that you'll need to use for the next command.

Now that we have that, let's see if we can get some information:

curl -X 'GET' \
  '<Your Cribl.Cloud URL>/api/v1/health' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your bearer token>' | jq

(Somewhat) Obviously you'll neex to replace <Your Cribl.Cloud URL> and <your bearer token> with the real thing. But what you should see as a result is:

{
  "status": "healthy",
  "startTime": 1780060352654,
  "role": "primary"
}

Getting an API bearer token and running a curl API request - the easy (at least easIER) way:

Make sure you have the following before you start:

• the API Client ID - noted as <your client id> in the script
• the API Client Secret - noted as <your client secret>
• the correct URL to get a bearer token - noted as <bearer token URL>
  • Found when you click the question-mark icon next to "Add Credential"
• your Cribl.cloud URL - noted as <cribl.cloud URL>
  • Found under Products -> Workspace -> Access

If you have all that, then the following script should work for you:

export clientid=<your client id>
export clientsecret=<your client secret>
token=$(curl --request POST \
--url <bearer token URL> \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "grant_type=client_credentials&client_id=${clientid}&client_secret=${clientsecret}&audience=https%3A%2F%2Fapi.cribl-staging.cloud" \
| jq -r '.access_token')
curl -X 'GET' \
  '<Your Cribl.Cloud URL>/api/v1/health' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ${token}' | jq

As long as you replced all the proper items, that script should give you the API output.

Configure Cribl Stream to Collect from an Authenticated Endpoint

But of course, we're not here to find out how to do things at the command line. We want to know how to make it happen within a Cribl REST collector.

important

If necessary, navigate back to the REST Collector Source page. From the top nav of your Cribl Stream Sandbox, select Manage > Data > Sources, then select Collectors > REST from the Data Sources page's tiles. Click Add Collector to open the REST > Add Collector modal, which provides the following options and fields.

1. In the Collector ID field, enter secure_collection.
2. Copy the following URL to the Collect URL field:

     '<Your Cribl.Cloud URL>/api/v1/health'

note

Once again, it's important that you have the single-quotes (not backtiks) around the URL

3. Expand the Authentication section accordion.
4. Among the resulting Authentication option buttons, select Oath. This exposes several new fields.
5. Configure the Authentication parameters with the following settings:

Parameter	Value
Login URL	'https://login.cribl.cloud/oauth/token'
Client Secret parameter	'<your client secret>'
Token Attribute	access_token
Authorize Expression	`Bearer ${token}`

In addition, add 3 items in the Extra authentication parameters section:

Name	Value
grant_type	client_credentials
client_id	'<your client secret>'
audience	'<bearer token URL>'

Because it's easy to get lost in quotes and backtiks, here's an example:

grant_type, client_credentials
client_id: 'abc123567890'
audience: 'https://login.cribl.cloud/oauth/token'

6. At the bottom left, click ► Save & Run. In the Run configuration modal, click Run again.

The Preview modal should display a single event containing 5 items in an array.

One look at the Authentication drop-down tells you there are far more options than just OAuth. And each option has it's own configuration quirks and nuances. While we fully intend to explore every authentication option and variation in future this is enough for now for you to have a working knowledge of this aspect of Cribl REST collectors.

If you're impatient and want to deepen your knowledge RIGHT NOW, you can check out:

• Cribl Univeristy: https://university.cribl.io/rest-api-data-collection/
• Cribl Documentation: https://docs.cribl.io/stream/collectors-rest/
• Cribl-as-Code documentation: https://docs.cribl.io/cribl-as-code/api-auth/
• Cribl Knowledgebase: https://knowledge.cribl.io/api-81/using-the-cribl-api-1711

This is also a good place to point out the helpful teal-colored star-in-a-hexagon you see at the bottm right corner of every screen. That's Cribl Copilot, and you can ask VERY specific questions there, and it will help you configure what you need by drawing on the combined knowledge of Cribl docs, the Cribl Knowledgebase, and just a dash of Goat-magic!

Conclusion

When you configure a REST Collector's Authentication settings, as in this module, Cribl Stream automatically adds the value of the Authorize Expression to the Authentication header for all subsequent calls (e.g., Discover and Collect).

Now you know how to automatically obtain a Bearer token from an endpoint, and use it during data discovery and collection!

In the next module, you'll explore how to apply Event Breaking to data in a JSON array.