crowdstrike.falcon.auth module – Manage authentication

Note

This module is part of the crowdstrike.falcon collection (version 4.7.0).

To install it, use: ansible-galaxy collection install crowdstrike.falcon. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: crowdstrike.falcon.auth.

New in crowdstrike.falcon 4.0.0

Synopsis

  • Manage token authentication with CrowdStrike Falcon API.

  • Utilizing access tokens can enhance efficiency when making multiple API calls helping to circumvent rate-limiting constraints.

  • The module will not report changes.

  • Refer to the Falcon documentation for detailed information on OAuth2 authentication with CrowdStrike Falcon.

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 3.6

  • crowdstrike-falconpy >= 1.3.0

Parameters

Parameter

Comments

access_token

string

The OAuth2 access token to be revoked.

Required if action=revoke.

action

string

Define the action to be performed.

When action=generate, this module returns authentication credentials, which include the OAuth2 access token and cloud region.

When action=revoke, this module revokes the OAuth2 token specified in the access_token parameter.

Choices:

  • "generate" ← (default)

  • "revoke"

client_id

aliases: falcon_client_id

string

The CrowdStrike API client ID to use.

See the Falcon documentation for more information about API clients.

The FALCON_CLIENT_ID environment variable can also be used.

client_secret

aliases: falcon_client_secret

string

The CrowdStrike API secret that corresponds to the client ID.

See the Falcon documentation for more information about API clients.

The FALCON_CLIENT_SECRET environment variable can also be used.

cloud

string

The CrowdStrike cloud region to use.

All clouds are automatically discovered if not specified, except for the us-gov-1 cloud.

The FALCON_CLOUD environment variable can also be used.

Choices:

  • "us-1" ← (default)

  • "us-2"

  • "us-gov-1"

  • "eu-1"

ext_headers

dictionary

Extended headers that are prepended to the default headers dictionary.

member_cid

string

The CrowdStrike member CID for MSSP authentication.

See the Falcon documentation for more information about API clients.

The FALCON_MEMBER_CID environment variable can also be used.

user_agent

string

Custom User-Agent string to use for requests to the API.

The user agent string is prepended to the default user agent string (crowdstrike-ansible/<version>).

See RFC 7231 for more information.

The FALCON_USER_AGENT environment variable can also be used.

Examples

- name: Generate Authentication Credentials (access token and cloud region)
  crowdstrike.falcon.auth:

- name: Generate Authentication Credentials with specific member CID
  crowdstrike.falcon.auth:
    member_cid: "{{ member_cid_var }}"

- name: Revoke an OAuth2 token
  crowdstrike.falcon.auth:
    action: revoke
    access_token: "{{ access_token_var }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

auth

dictionary

The authentication credentials (OAuth2 access token and cloud region).

Returned: success

access_token

string

The generated OAuth2 access token.

Returned when action is set to generate.

Returned: success

cloud

string

The CrowdStrike cloud region to use. This may differ from the module’s cloud argument due to the autodiscovery process.

Returned when action is set to generate.

Returned: success

Authors

  • Carlos Matos (@carlosmmatos)