Update README authentication section

README.md

@@ -8,9 +8,72 @@ Check one of the examples in the [examples](examples/) folder.
 
 # Authentication
 
-Currently, only the _token flow_ is supported. The Terraform provider will first try to find a token in the `STACKIT_SERVICE_ACCOUNT_TOKEN` env var. If not present, it will check the credentials file located in the path defined by the `STACKIT_CREDENTIALS_PATH` env var, if specified, or in `$HOME/.stackit/credentials.json` as a fallback. If the token is found, all the requests are authenticated using that token.
-
-## Acceptance Tests
+To authenticate, you will need a [service account](https://docs.stackit.cloud/stackit/en/service-accounts-134415819.html). Create it in the STACKIT Portal an assign it the necessary permissions, e.g. `project.owner`. There are multiple ways to authenticate:
+
+- Key flow (recommended)
+- Token flow
+
+When setting up authentication, the provider will always try to use the key flow first and search for credentials in several locations, following a specific order:
+
+1. Explicit configuration, e.g. by seting the fiel `stackit_service_account_key_path` in the provider block (see example below)
+2. Environment variable, e.g. by setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH`
+3. Credentials file
+
+   The SDK will check the credentials file located in the path defined by the `STACKIT_CREDENTIALS_PATH` env var, if specified,
+   or in `$HOME/.stackit/credentials.json` as a fallback.
+   The credentials should be set using the same name as the environmnet variables. Example:
+
+   ```json
+   {
+     "STACKIT_SERVICE_ACCOUNT_TOKEN": "foo_token",
+     "STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json",
+     "STACKIT_PRIVATE_KEY_PATH": "path/to/private_key.pem"
+   }
+   ```
+
+## Key flow
+
+To use the key flow, you need to have a service account key and an RSA key-pair.
+To configure it, follow this steps:
+
+    The following instructions assume that you have created a service account and assigned it the necessary permissions, e.g. project.owner.
+
+1. In the Portal, go to `Service Account -> Service Account Keys` and create a key.
+   - You can create your own RSA key-pair or have the Portal generate one for you.
+2. Save the content of the service account key and the corresponding private key by copying them or saving them in a file. The expected format of the service account key is the following:
+   ```json
+   {
+     "id": "uuid",
+     "publicKey": "public key",
+     "createdAt": "2023-08-24T14:15:22Z",
+     "validUntil": "2023-08-24T14:15:22Z",
+     "keyType": "USER_MANAGED",
+     "keyOrigin": "USER_PROVIDED",
+     "keyAlgorithm": "RSA_2048",
+     "active": true,
+     "credentials": {
+       "kid": "string",
+       "iss": "my-sa@sa.stackit.cloud",
+       "sub": "uuid",
+       "aud": "string",
+       (optional) "privateKey": "private key when generated by the SA service"
+     }
+   }
+   ```
+3. Configure the service account key and private key for authentication in the SDK:
+   - setting the fiels in the provider block: `service_account_key` or `service_account_key_path`, `private_key` or `private_key_path`
+   - setting environment variables: `STACKIT_SERVICE_ACCOUNT_KEY_PATH` and `STACKIT_PRIVATE_KEY_PATH`
+   - setting them in the credentials file (see above)
+
+## Token flow
+
+Using this flow is less secure since the token is long-lived. You can provide the token in several ways:
+
+1. Setting the field `service_account_token` in the provider
+2. Setting the environment variable `STACKIT_SERVICE_ACCOUNT_TOKEN`
+3. Setting it in the credentials file (see above)
+
+# Acceptance Tests
 
 Terraform acceptance tests are run using the command `make test-acceptance-tf`. For all services,
 
@@ -27,18 +90,18 @@ Additionally, for the Resource Manager service,
 
 **WARNING:** Acceptance tests will create real resources, which may incur in costs.
 
-## Migration
+# Migration
 
 For guidance on how to migrate to using this provider, please see our [Migration Guide](./MIGRATION.md).
 
-## Reporting Issues
+# Reporting Issues
 
 If you encounter any issues or have suggestions for improvements, please open an issue in the repository.
 
-## Contribute
+# Contribute
 
 Your contribution is welcome! For more details on how to contribute, refer to our [Contribution Guide](./CONTRIBUTION.md).
 
-## License
+# License
 
 Apache 2.0