.. This file is automatically generated. Do not edit this file directly.

Google Cloud IoT Core Device Federated Authentication Python Samples
===============================================================================

.. image:: https://gstatic.com/cloudssh/images/open-btn.png
   :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/python-iot&page=editor&open_in_editor=iot/api-client/accesstoken_example/README.rst


This directory contains samples for Google Cloud IoT Core Device Federated Authentication. Devices authenticated to Cloud IoT Core can use the `Token Service <https://cloud.google.com/iot/alpha/docs/reference/cloudiottoken/rest>`_ federated authentication to request `OAuth 2.0 access tokens <https://developers.google.com/identity/protocols/oauth2>`_ in exchange for their `Cloud IoT Core JWTs <https://cloud.google.com/iot/docs/how-tos/credentials/jwts>`_. The OAuth 2.0 credentials can be used to call different `Google Cloud APIs <https://developers.google.com/identity/protocols/oauth2/scopes>`_ with fine-grained permissions and access control using `Workload Identity Federation <https://cloud.google.com/iam/docs/workload-identity-federation>`_. For more information, see `documentation <https://cloud.google.com/iot/alpha/docs/how-tos/federated_auth>`_.




.. _Google Cloud IoT Core Device Federated Authentication: https://cloud.google.com/iot/alpha/docs/how-tos/federated_auth





Setup
-------------------------------------------------------------------------------


Authentication
++++++++++++++

This sample requires you to have authentication setup. Refer to the
`Authentication Getting Started Guide`_ for instructions on setting up
credentials for applications.

.. _Authentication Getting Started Guide:
    https://cloud.google.com/docs/authentication/getting-started

Install Dependencies
++++++++++++++++++++

#. Clone python-iot and change directory to the sample directory you want to use.

    .. code-block:: bash

        $ git clone https://github.com/googleapis/python-iot.git

#. Install `pip`_ and `virtualenv`_ if you do not already have them. You may want to refer to the `Python Development Environment Setup Guide`_ for Google Cloud Platform for instructions.

   .. _Python Development Environment Setup Guide:
       https://cloud.google.com/python/setup

#. Create a virtualenv. Samples are compatible with Python 3.6+.

    .. code-block:: bash

        $ virtualenv env
        $ source env/bin/activate

#. Install the dependencies needed to run the samples.

    .. code-block:: bash

        $ pip install -r requirements.txt

.. _pip: https://pip.pypa.io/
.. _virtualenv: https://virtualenv.pypa.io/

Samples
-------------------------------------------------------------------------------

accesstoken
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. image:: https://gstatic.com/cloudssh/images/open-btn.png
   :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/python-iot&page=editor&open_in_editor=iot/api-client/accesstoken_example/accesstoken.py,iot/api-client/accesstoken_example/README.rst




To run this sample:

.. code-block:: bash

    $ python accesstoken.py

    usage: accesstoken.py [-h] [--algorithm {RS256,ES256}]
                          [--private_key_file PRIVATE_KEY_FILE]
                          [--cloud_region CLOUD_REGION] [--device_id DEVICE_ID]
                          [--scope SCOPE] [--project_id PROJECT_ID]
                          [--registry_id REGISTRY_ID] [--topic_id TOPIC_ID]
                          [--bucket_name BUCKET_NAME] [--data_path DATA_PATH]
                          [--service_account_email SERVICE_ACCOUNT_EMAIL]
                          [--device_access_token DEVICE_ACCESS_TOKEN]
                          [--command_to_be_sent_to_device COMMAND_TO_BE_SENT_TO_DEVICE]
                          {generate-access-token,publish-pubsub-message,send-command-to-iot-device,download-cloud-storage-file,exchange-device-token-for-service-account-token}
                          ...

    This sample app demonstrates the capabilites of Google Cloud IoT Core device federated authentication feature.
    Devices authenticated to Cloud IoT Core can use the [Token Service](https://cloud.google.com/iot/alpha/docs/reference/cloudiottoken/rest) federated authentication to request [OAuth 2.0 access tokens](https://developers.google.com/identity/protocols/oauth2) in exchange for their [Cloud IoT Core JWTs](https://cloud.google.com/iot/docs/how-tos/credentials/jwts).
    The OAuth 2.0 credentials can be used to call different [Google Cloud APIs](https://developers.google.com/identity/protocols/oauth2/scopes) with fine-grained permissions and access control using [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation).
    For more information, see https://cloud.google.com/iot/alpha/docs/how-tos/federated_auth

    Usage example:

        python accesstoken.py \
          --project_id=my-project-id \
          --cloud_region=us-central1 \
          --registry_id=my-registry-id \
          --device_id=my-device-id \
          --private_key_file=./resources/rsa_private.pem \
          --scope=https://www.googleapis.com/auth/cloud-platform \
          --algorithm=RS256 \
          generate-access-token

    positional arguments:
      {generate-access-token,publish-pubsub-message,send-command-to-iot-device,download-cloud-storage-file,exchange-device-token-for-service-account-token}
        generate-access-token
                            Generates OAuth 2.0 Google Access Token.
        publish-pubsub-message
                            Publishes a message to Cloud Pub/Sub topic.
        send-command-to-iot-device
                            Sends a command to an IoT device.
        download-cloud-storage-file
                            Downloads a file from Cloud Storage bucket.
        exchange-device-token-for-service-account-token
                            Exchanges device access token to service account
                            access token.

    optional arguments:
      -h, --help            show this help message and exit
      --algorithm {RS256,ES256}
                            Encryption algorithm used to generate the device JWT.
      --private_key_file PRIVATE_KEY_FILE
                            Path to private key file.
      --cloud_region CLOUD_REGION
                            GCP cloud region.
      --device_id DEVICE_ID
                            Device ID.
      --scope SCOPE         Scope for OAuth 2.0 access token. Space delimited
                            strings. See the full list of scopes at: https://devel
                            opers.google.com/identity/protocols/oauth2/scopes
      --project_id PROJECT_ID
                            GCP cloud project name.
      --registry_id REGISTRY_ID
                            Registry ID.
      --topic_id TOPIC_ID   Cloud Pub/Sub topic ID.
      --bucket_name BUCKET_NAME
                            Cloud Storage bucket name.
      --data_path DATA_PATH
                            Path to file to be uploaded.
      --service_account_email SERVICE_ACCOUNT_EMAIL
                            Service account email to exchange device access token
                            to service account token.
      --device_access_token DEVICE_ACCESS_TOKEN
                            Device access token to exchange for service account
                            access token.
      --command_to_be_sent_to_device COMMAND_TO_BE_SENT_TO_DEVICE
                            Command to be sent to the IoT device.





.. _Google Cloud SDK: https://cloud.google.com/sdk/