From 5836955e42362b8a1e73025cb46b3c300b7e4b65 Mon Sep 17 00:00:00 2001 From: vicentepinto98 Date: Mon, 9 Oct 2023 14:52:36 +0100 Subject: [PATCH] Update README and template with more info on key flow --- README.md | 61 ++++++++++++++++++++++++----------------- templates/index.md.tmpl | 61 ++++++++++++++++++++++++----------------- 2 files changed, 72 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index f1a9498a..7968fc29 100644 --- a/README.md +++ b/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,43 @@ 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, to save the private key in a PEM encoded file follow these steps: + + - Download the service account key as a PEM file + - Extract the private key from the service account key using this command: `openssl storeutl -keys > private.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 diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl index 29eb8f35..9f4c9171 100644 --- a/templates/index.md.tmpl +++ b/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,43 @@ 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, to save the private key in a PEM encoded file follow these steps: + + - Download the service account key as a PEM file + - Extract the private key from the service account key using this command: `openssl storeutl -keys > private.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