Update README and template with more info on key flow

README.md

@@ -15,13 +15,13 @@ To authenticate, you will need a [service account](https://docs.stackit.cloud/st
 
 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)
+1. Explicit configuration, e.g. by seting the field `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:
+   The credentials should be set using the same name as the environment variables. Example:
 
    ```json
    {
@@ -38,32 +38,40 @@ 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"
-     }
-   }
-   ```
+1.  In the Portal, go to the `Service Accounts` tab, choose a `Service Account` and go to `Service Account Keys` to 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.
+
+    **Hint:** If you have generated the RSA key-pair using the Portal, you can save the private key in a PEM encoded file by downloading the service account key as a PEM file and using `openssl storeutl -keys <path/to/sa_key_pem_file> > private.key` to extract the private key from the service account key.
+
+The expected format of the service account key is a **json** with the following structure:
+
+```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)
+   - setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH` and `STACKIT_PRIVATE_KEY_PATH` in the credentials file (see above)
 
 ## Token flow
 

templates/index.md.tmpl

@@ -15,13 +15,13 @@ To authenticate, you will need a [service account](https://docs.stackit.cloud/st
 
 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)
+1. Explicit configuration, e.g. by seting the field `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:
+   The credentials should be set using the same name as the environment variables. Example:
 
    ```json
    {
@@ -38,32 +38,40 @@ 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"
-     }
-   }
-   ```
+1.  In the Portal, go to the `Service Accounts` tab, choose a `Service Account` and go to `Service Account Keys` to 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.
+
+    **Hint:** If you have generated the RSA key-pair using the Portal, you can save the private key in a PEM encoded file by downloading the service account key as a PEM file and using `openssl storeutl -keys <path/to/sa_key_pem_file> > private.key` to extract the private key from the service account key.
+
+The expected format of the service account key is a **json** with the following structure:
+
+```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)
+   - setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH` and `STACKIT_PRIVATE_KEY_PATH` in the credentials file (see above)
 
 ### Token flow