Authentication & Authorization with Google Workspace ==================================================== SWAT integrates seamlessly with Google Workspace, automating security processes. This document offers a granular look at SWAT's authentication and authorization design. Google Workspace Authentication Mechanisms ------------------------------------------ - **OAuth**: This protocol delegates access using tokens for authentication and authorization. OAuth requires user interaction to grant access to a particular application, in this instance, SWAT. - **Service Accounts**: Representing non-human users, these accounts authenticate via dedicated credentials. Service accounts are ideal for server-to-server interactions or acting on behalf of a user. Service accounts require domain-wide delegation to access Google Workspace APIs. Unlike OAuth, service account scopes are defined at the time of creation or based on the IAM role assigned. Therefore to use service accounts in SWAT, the user must create a service account with the appropriate scopes and download the JSON key file. - **API Keys**: These keys authenticate requests to Google Workspace APIs. For SWAT, both OAuth credentials and Service Account credentials are supported. The Credential Store (from `base.py`) ------------------------------------- At its core, the `CredStore` class in `base.py` provides a structured way to handle and store credentials. This is commonly referred to as the "credential store" in SWAT. 1. **Path**: It defaults to `DEFAULT_CRED_STORE_FILE`, pointing to a file where credentials are serialized. 2. **Store**: A dictionary where each key corresponds to a particular `Cred` object. A `Cred` object pairs a credential with an active session, if one exists. **Key Functionalities**: - **has_sessions**: A quick boolean check if any stored credentials have an active session. - **from_file**: Load an instance of `CredStore` from a serialized file. - **save**: Serialize the current `CredStore` instance to a file. - **add**: Insert a new `Cred` object into the store. - **remove**: Remove a `Cred` object using its key. - **get**: Retrieve a `Cred` object using its key and optionally validate its type. - **list_credentials**: List all stored credentials. - **list_sessions**: List all active sessions. Dataclasses for Credentials --------------------------- Two primary dataclasses define credentials: 1. **ServiceAccountCreds**: Represents credentials for Google Cloud Platform (GCP) service accounts. 2. **OAuthCreds**: Represents OAuth2.0 application credentials from GCP. Both classes derive from the `BaseCreds` class and possess: - **to_dict**: Convert the class instance to a dictionary. - **from_file**: A class method to instantiate the credential class from a file. The `Cred` class pairs these credentials with an active session if one exists. The `refreshed_session` method can refresh an expired session. Command Execution with `auth.py` -------------------------------- `auth.py` provides the executable logic, allowing the user to: - Initiate authentication using either OAuth or Service Account. - Fetch, store, or remove credentials in the `CredStore`. - Authenticates and authorizes to Google Workspace services with a `Cred` object. Google Workspace Scopes ----------------------- Google Workspace services, such as Gmail, Drive, or Calendar, require certain permissions or "scopes" to function. These scopes define what an application can and cannot do. In SWAT, each emulation specifies its required service and scopes. For example, sending an email via Gmail might require the `gmail.send` scope, while reading might necessitate the `gmail.readonly` scope. By default, all required scopes for out-of-the-box emulations are defined in `etc/config.yaml` and passed into the authN and authZ flows at time of execution. To add additional scopes, the user can add them to the `etc/config.yaml` file or or use the `scopes add` command which will add the scopes to the existing scopes from the loaded config file. Emulation Access to Credential Store ------------------------------------ Emulations have direct access to the `CredStore`. This is because the `SWAT` object from `base.py` is stored during initialization of both `BaseCommand` and `BaseEmulation` classes which are inherited by all commands and emulations, respectively. - It is recommended to add credentials and authorize prior to emulations so that valid session(s) are available. - Emulations can access the `CredStore` via `self.obj.cred_store.store[KEY]` where `.session` points to the authN and authZ session. - To build a service client, typically `self.service = build('SERVICE', 'vN', credentials=self.obj.cred_store.store[KEY].session)` is added to the initialization of the emulation class `Emulation(BaseEmulation)`. Multiple services can be added to the same emulation as long as multiple credentials and sessions are available in the `CredStore`. - Some OOTB emulations, will include a positional argument `session_key` which is used to select the session from the `CredStore` to use for the emulation. - These sessions offer authenticated access to specific Google Workspace services, defined in the emulation itself. For more information on how to authenticate or authorize with credentials in SWAT, please refer to our `Getting Started Guide `_ or `How-To Guide `_. Persistence of Credentials -------------------------- Credentials are stored in a serialized file, `swat/etc/.cred_store.pkl`, by default. Both credentials and valid sessions are stored in this file and are loaded at runtime. This allows for persistent authentication and authorization without the need to re-authenticate each time for every user or service account. This can be disabled by changed the `store_on_exit` value in the `etc/config.yaml` to `False`. Recommendations --------------- - It is recommended to use at least one OAuth credential with super administrative privileges in SWAT to ensure access to all Google Workspace services and emulations that are OOTB. This ensures not only OOTB emulations can be run but also commands such as `audit`. - For the default super admin OAuth credentials, it is recommended to authenticate, authorize and store the credentials and session in the credential store with the key name `default` as such ``auth session --store-key default --creds PATH_TO_CREDS``. - Some emulations require a "3rd-party" google workspace account, separate from the organization being targeted/tested. It is therefore recommended to setup a separate and external Google Workspace account for this purpose. - For the "3rd-party" Google Workspace account, it is recommended to use OAuth credentials as well and store them in the credential store with the key name `external` as such ``auth session --store-key external --creds PATH_TO_CREDS``. - It is recommended to have all Google Chrome profiles established and pre-authenticated for users where OAuth credentials are used. This will be useful when the OAuth consent screen appears and the user can select the appropriate profile to authenticate with. - It is recommended to keep the `store_on_exit` value in the `etc/config.yaml` to `True` to ensure credentials are stored and available for future use. - Most OOTB emulations require 1-2 users with OAuth creds to emulate either internal or external user activity. Conclusion ---------- The foundation of SWAT's integration with Google Workspace is its structured handling of authentication. By using dataclasses for structured credential representation and offering a dedicated credential store, SWAT ensures secure and efficient authentication and authorization flows.