Authentication with the XDR Python SDK
Client Credentials with the Python SDK ⫘
The Python SDK authenticates with your Secureworks® Taegis™ account with client credentials when you install it. This requires a password and MFA token, unless your organization has registered your organization with SSO authentication. If SSO is enabled, you will be presented with a device code authentication link.
Note
To generate and set tokens as needed in these examples, see Generate a Token below.
Example Usage ⫘
from taegis_sdk_python import GraphQLService
from pprint import pprint as pp
service = GraphQLService(environment="US1")
results = service.clients.mutation.create_client(name="my_awesome_app", roles=None)
print(f"CLIENT_ID: {results.client.client_id}")
print(f"CLIENT_SECRET: {results.client_secret}")
pp(results)
Note
Change your environment as appropriate.
Partner Credentials ⫘
If you need to make tenant specific client credentials, add tenant_id to your service constructor.
from taegis_sdk_python import GraphQLService
from pprint import pprint as pp
service = GraphQLService(environment="US1", tenant_id="<tenant_id>")
results = service.clients.mutation.create_client(name="my_awesome_app", roles=None)
print(f"CLIENT_ID: {results.client.client_id}")
print(f"CLIENT_SECRET: {results.client_secret}")
pp(results)
Or if you need to make multiple tenant credentials at the same time:
from taegis_sdk_python import GraphQLService
from pprint import pprint as pp
service = GraphQLService()
# service context let's you change out values per call!
with service(environment="US1", tenant_id="<tenant_id>"):
results = service.clients.mutation.create_client(name="my_awesome_tenant_app", roles=None)
with service(environment="US1", tenant_id="<another_tenant_id>"):
results2 = service.clients.mutation.create_client(name="my_awesome_another_tenant_app", roles=None)
print(f"CLIENT_ID: {results.client.client_id}")
print(f"CLIENT_SECRET: {results.client_secret}")
pp(results)
Privileged Credentials ⫘
from taegis_sdk_python import GraphQLService
from pprint import pprint as pp
service = GraphQLService(environment="US1")
results = service.clients.mutation.create_client(name="my_awesome_app", roles=['ba0fdcbd-e87d-4bdd-ae7d-ca6118b25068'])
print(f"CLIENT_ID: {results.client.client_id}")
print(f"CLIENT_SECRET: {results.client_secret}")
pp(results)
Generate a Token ⫘
You can place the CLIENT_ID and CLIENT_SECRET in environment variables for authentication. You don’t need to pre-provide authentication for user interactive scripts. The Python SDK checks for a valid token when you call an API, and requests credentials at runtime if not found.
Python Script Example ⫘
from taegis_sdk_python import GraphQLService
service = GraphQLService()
print(service.access_token)
Command Line Example ⫘
export CLIENT_ID="you_client_id"
export CLIENT_SECRET="your_client_secret"
python script.py
More on Using Tokens with the XDR Python SDK ⫘
The authentication flow for the XDR Python SDK is Cached Token→Authenticate via OAuth→Authenticate via SSO or Username/Password/MFA. Tokens are cached in the ~/.taegis_sdk_python/config file.
OAuth ⫘
OAuth tokens from CLIENT_ID and CLIENT_SECRET are used by default.
To generate a CLIENT_ID and CLIENT_SECRET:
from taegis_sdk_python.services import GraphQLService
from pprint import pprint as pp
service = GraphQLService(environment="US1")
result = service.clients.mutation.create_client(name="my_awesome_app", roles=None)
print(f"CLIENT_ID: {result.client.client_id}")
print(f"CLIENT_SECRET: {result.client_secret}")
pp(result)
Important
Store your CLIENT_ID and CLIENT_SECRET results in an encrypted vault.
Replace <client_id> and <client_secret> in the following example with your values:
CLIENT_ID=<client_id> CLIENT_SECRET=<client_secret> python script.py
Customize Environment Variables ⫘
You can use write_to_config to set custom environment variables for your environment. This is useful if you are automating and you have to access different environments from the same script:
from taegis_sdk_python import GraphQLService
from taegis_sdk_python.config import write_to_config
# write_to_config(environment, default_reference, custom_reference)
write_to_config("US1", "CLIENT_ID", "US1_CLIENT_ID")
write_to_config("US1", "CLIENT_SECRET", "US1_CLIENT_SECRET")
service = GraphQLService()
US1_CLIENT_ID=<client_id> US1_CLIENT_SECRET=<client_secret> python script.py
Username ⫘
If you don't provide OAuth tokens in the environment, you will be prompted for a username. If your organization has enabled single sign-on, then you will prompted with a link. Otherwise, you will be asked for a password and MFA token.
Clearing Authorization Tokens ⫘
If you need to manually clear the authentication tokens, use:
from taegis_sdk_python.config import write_to_config
write_to_config("US1", "access_token", "")
Search Client Credentials ⫘
from taegis_sdk_python import GraphQLService
service = GraphQLService()
search_results = service.clients.query.clients(client_ids=["<CLIENT_ID>"])
print(search_results)
Search for Named Credentials ⫘
You can use % for wildcard matching.
from taegis_sdk_python import GraphQLService
service = GraphQLService()
results = service.clients.query.clients(name="%docs-test-client%")
print(results)
Search for Administrator Credentials ⫘
from taegis_sdk_python import GraphQLService
service = GraphQLService()
results = service.clients.query.clients(role_ids=["c373d68a-fdca-476f-5b48-92ed5804dc53"])
print(results)
Reset a Client Secret ⫘
If you need to reset a client secret, but want to retain the same client id, you can use the rotateClientSecret mutation to generate a new client secret. The ID input can either be the UUID or the client_id.
from taegis_sdk_python import GraphQLService
service = GraphQLService()
update_results = service.clients.mutation.rotate_client_secret('c373d68a-fdca-476f-5b48-92ed5804dc53')
print(update_results)
from taegis_sdk_python import GraphQLService
service = GraphQLService()
update_results = service.clients.mutation.rotate_client_secret('b42USvw1jm5fk3Y2VqoAWSyG4CF47Ek5')
print(update_results)
Delete a Client ⫘
When you are finished with client credentials, you can use the deleteClient mutation to revoke credentials. The ID input can either be the UUID or the client_id.
from taegis_sdk_python import GraphQLService
service = GraphQLService()
delete_results = service.clients.mutation.delete_client('c373d68a-fdca-476f-5b48-92ed5804dc53')
print(delete_results)
from taegis_sdk_python import GraphQLService
service = GraphQLService()
delete_results = service.clients.mutation.delete_client('b42USvw1jm5fk3Y2VqoAWSyG4CF47Ek5')
print(delete_results)