From df99dea53745aadda59a3a2e03446b1f44e505f5 Mon Sep 17 00:00:00 2001 From: Marcel Jacek Date: Fri, 12 Sep 2025 13:57:38 +0200 Subject: [PATCH 1/8] extend AuthenticationExample --- .../examples/AuthenticationExample.java | 111 +++++++++++++++--- 1 file changed, 96 insertions(+), 15 deletions(-) diff --git a/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java index 89d6f54..1578704 100644 --- a/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java +++ b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java @@ -5,23 +5,104 @@ import cloud.stackit.sdk.resourcemanager.model.ListOrganizationsResponse; class AuthenticationExample { - public static void main(String[] args) { - String SERVICE_ACCOUNT_KEY_PATH = "/path/to/your/sa/key.json"; - String SERVICE_ACCOUNT_MAIL = "name-1234@sa.stackit.cloud"; + public static void main(String[] args) { + /////////////////////////////////////////////////////// + // Option 1: setting the paths to service account key (and private key) as configuration + /////////////////////////////////////////////////////// + String SERVICE_ACCOUNT_KEY_PATH = "/path/to/sa_key.json"; + String PRIVATE_KEY_PATH = "/path/to/private_key.pem"; + String SERVICE_ACCOUNT_MAIL = "name-1234@sa.stackit.cloud"; - CoreConfiguration config = - new CoreConfiguration().serviceAccountKeyPath(SERVICE_ACCOUNT_KEY_PATH); + try { + ResourceManagerApi api = new ResourceManagerApi( + new CoreConfiguration() + .serviceAccountKeyPath(SERVICE_ACCOUNT_KEY_PATH) + // Optional: if private key not included in service account key + .privateKeyPath(PRIVATE_KEY_PATH) + ); - try { - ResourceManagerApi api = new ResourceManagerApi(config); + /* list all organizations */ + ListOrganizationsResponse response = + api.listOrganizations(null, SERVICE_ACCOUNT_MAIL, null, null, null); - /* list all organizations */ - ListOrganizationsResponse response = - api.listOrganizations(null, SERVICE_ACCOUNT_MAIL, null, null, null); + System.out.println(response); + } catch (Exception e) { + throw new RuntimeException(e); + } - System.out.println(response); - } catch (Exception e) { - throw new RuntimeException(e); - } - } + /////////////////////////////////////////////////////// + // Option 2: setting the service account key (and private key) as configuration + /////////////////////////////////////////////////////// + String SERVICE_ACCOUNT_KEY = "{\n" + + " \"id\": \"uuid\",\n" + + " \"publicKey\": \"public key\",\n" + + " \"createdAt\": \"2023-08-24T14:15:22Z\",\n" + + " \"validUntil\": \"2023-08-24T14:15:22Z\",\n" + + " \"keyType\": \"USER_MANAGED\",\n" + + " \"keyOrigin\": \"USER_PROVIDED\",\n" + + " \"keyAlgorithm\": \"RSA_2048\",\n" + + " \"active\": true,\n" + + " \"credentials\": {\n" + + " \"kid\": \"string\",\n" + + " \"iss\": \"my-sa@sa.stackit.cloud\",\n" + + " \"sub\": \"uuid\",\n" + + " \"aud\": \"string\",\n" + + " \"privateKey\": \"(OPTIONAL) private key when generated by the SA service\"\n" + + " }\n" + + " }"; + String PRIVATE_KEY = "-----BEGIN PRIVATE KEY-----\n" + + "MIIJQw...ZL+U\n" + + "lm+dqO...xQ8=\n" + + "-----END PRIVATE KEY-----"; + + try { + ResourceManagerApi api = new ResourceManagerApi( + new CoreConfiguration() + .serviceAccountKey(SERVICE_ACCOUNT_KEY) + // Optional: if private key not included in service account key + .privateKeyPath(PRIVATE_KEY) + ); + + /* list all organizations */ + ListOrganizationsResponse response = + api.listOrganizations(null, SERVICE_ACCOUNT_MAIL, null, null, null); + + System.out.println(response); + } catch (Exception e) { + throw new RuntimeException(e); + } + + /////////////////////////////////////////////////////// + // Option 3: setting the service account key (and private key) as environment variable + /////////////////////////////////////////////////////// + // Set the service account key via environment variable: + // - STACKIT_SERVICE_ACCOUNT_KEY_PATH=/path/to/sa_key.json + // - STACKIT_SERVICE_ACCOUNT_KEY="" + // + // If the private key is not included in the service account key, set also: + // - STACKIT_PRIVATE_KEY_PATH=/path/to/private_key.pem + // - STACKIT_PRIVATE_KEY="" + // + // If no environment variable is set, fallback to credentials file in "$HOME/.stackit/credentials.json". + // Can be overridden with the environment variable `STACKIT_CREDENTIALS_PATH` + // The credentials file must be a json: + // { + // "STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json", + // "STACKIT_PRIVATE_KEY_PATH": "(OPTIONAL) when the private key isn't included in the Service Account key", + // // Alternative: + // "STACKIT_SERVICE_ACCOUNT_KEY": "", + // "STACKIT_PRIVATE_KEY": "(OPTIONAL) when the private key isn't included in the Service Account key", + // } + try { + ResourceManagerApi api = new ResourceManagerApi(); + + /* list all organizations */ + ListOrganizationsResponse response = + api.listOrganizations(null, SERVICE_ACCOUNT_MAIL, null, null, null); + + System.out.println(response); + } catch (Exception e) { + throw new RuntimeException(e); + } + } } From cb764df6db73991ac3c6a88646e96f63e287176d Mon Sep 17 00:00:00 2001 From: Marcel Jacek Date: Fri, 12 Sep 2025 13:58:59 +0200 Subject: [PATCH 2/8] extend README with Authorization --- README.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) diff --git a/README.md b/README.md index b00de48..e71ad30 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,141 @@ Add the dependencies to your project's build file (replace `` with Examples on services, configuration and authentication possibilities can be found in the [examples folder](https://github.com/stackitcloud/stackit-sdk-java/tree/main/examples). +## Authorization + +To authenticate to the SDK, you will need a [service account](https://docs.stackit.cloud/stackit/en/service-accounts-134415819.html). Create it in the STACKIT Portal and assign it the necessary permissions, e.g. `project.owner`. + +The Java SDK supports only Key flow for authentication. + +When setting up authentication, the SDK will search for credentials in several locations, following a specific order: + +1. Explicit configuration, e.g. by using the option `new CoreConfiguration().serviceAccountKeyPath("path/to/sa_key.json")` +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 file should be a json and each credential should be set using the name of the respective environment variable, as stated below in each flow. Example: + + ```json + { + "STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json", + "STACKIT_PRIVATE_KEY_PATH": "(OPTIONAL) when the private key isn't included in the Service Account key" + } + ``` + +### Example + +The following instructions assume that you have created a service account and assigned it the necessary permissions, e.g. `project.owner`. + +To use the key flow, you need to have a service account key, which must have an RSA key-pair attached to it. + +When creating the service account key, a new pair can be created automatically, which will be included in the service account key. +This will make it much easier to configure the key flow authentication in the SDK, by just providing the service account key. + +> **Optionally**, you can provide your own private key when creating the service account key, which will then require you to also provide it explicitly to the SDK, additionally to the service account key. +> Check the STACKIT Knowledge Base for an [example of how to create your own key-pair](https://docs.stackit.cloud/stackit/en/usage-of-the-service-account-keys-in-stackit-175112464.html#UsageoftheserviceaccountkeysinSTACKIT-CreatinganRSAkey-pair). + +To configure the key flow, follow this steps: + +1. Create a service account key: + - Use the STACKIT Portal: go to the `Service Accounts` tab, choose a `Service Account` and go to `Service Account Keys` to create a key. For more details, see [Create a service account key](https://docs.stackit.cloud/stackit/en/create-a-service-account-key-175112456.html). +2. Save the content of the service account key by copying it and saving it in a JSON file. The expected format of the service account key is **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", + "privateKey": "(OPTIONAL) private key when generated by the SA service" + } + } + ``` + +3. Configure the service account key for authentication in the SDK by following one of the alternatives below: + - using the configuration options: + ```java + CoreConfiguration config = + new CoreConfiguration() + ... + .serviceAccountKeyPath("/path/to/service_account_key.json"); + + ResourceManagerApi api = new ResourceManagerApi(config); + ``` + - setting the environment variable: `STACKIT_SERVICE_ACCOUNT_KEY_PATH` + - setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH` in the credentials file (see above) + +> **Optionally, only if you have provided your own RSA key-pair when creating the service account key**, you also need to configure your private key (takes precedence over the one included in the service account key, if present). **The private key must be PEM encoded** and can be provided using one of the options below: +> +> - using the configuration options: +> ```java +> CoreConfiguration config = +> new CoreConfiguration() +> ... +> .privateKeyPath("/path/to/private_key.pem"); +> ``` +> - setting the environment variable: `STACKIT_PRIVATE_KEY_PATH` +> - setting `STACKIT_PRIVATE_KEY_PATH` in the credentials file (see above) + +> **Alternatively, if you can't store the credentials in a file, e.g. when using it in a pipeline**, you can store the credentials in environment variables: +> - setting the environment variable `STACKIT_SERVICE_ACCOUNT_KEY` with the content of the service account key +> - (OPTIONAL) setting the environment variable `STACKIT_PRIVATE_KEY` with the content of the private key + + +4. The SDK will search for the keys and, if valid, will use them to get access and refresh tokens which will be used to authenticate all the requests. + +Check the [authentication example](examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java) for more details. + +## Using custom endpoints + +The example below shows how to use the STACKIT Java SDK in custom STACKIT enviroments. + +```java +import cloud.stackit.sdk.core.config.CoreConfiguration; +import cloud.stackit.sdk.resourcemanager.api.ResourceManagerApi; +import cloud.stackit.sdk.resourcemanager.model.ListOrganizationsResponse; + +import java.io.IOException; + +class CustomEndpointExample { + public static void main(String[] args) { + CoreConfiguration config = + new CoreConfiguration() + .serviceAccountKey("/path/to/sa_key.json") + .customEndpoint("https://resource-manager.api.stackit.cloud") + .tokenCustomUrl("https://service-account.api.stackit.cloud/token"); + + try { + ResourceManagerApi resourceManagerApi = new ResourceManagerApi(config); + + /* list all organizations */ + ListOrganizationsResponse response = + resourceManagerApi.listOrganizations( + null, + "service-account-mail@sa.stackit.cloud", + null, + null, + null + ); + + System.out.println(response); + } catch (Exception e) { + throw new RuntimeException(e); + } + } +} +``` + ## Reporting issues If you encounter any issues or have suggestions for improvements, please open an issue in the repository or create a ticket in the [STACKIT Help Center](https://support.stackit.cloud/). From b1f07637140068c8a91a29fe75ca28c732ca6f61 Mon Sep 17 00:00:00 2001 From: Marcel Jacek Date: Fri, 12 Sep 2025 14:16:43 +0200 Subject: [PATCH 3/8] formatting auth example --- .../examples/AuthenticationExample.java | 185 +++++++++--------- 1 file changed, 95 insertions(+), 90 deletions(-) diff --git a/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java index 1578704..282ee19 100644 --- a/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java +++ b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java @@ -5,104 +5,109 @@ import cloud.stackit.sdk.resourcemanager.model.ListOrganizationsResponse; class AuthenticationExample { - public static void main(String[] args) { - /////////////////////////////////////////////////////// - // Option 1: setting the paths to service account key (and private key) as configuration - /////////////////////////////////////////////////////// - String SERVICE_ACCOUNT_KEY_PATH = "/path/to/sa_key.json"; - String PRIVATE_KEY_PATH = "/path/to/private_key.pem"; - String SERVICE_ACCOUNT_MAIL = "name-1234@sa.stackit.cloud"; + public static void main(String[] args) { + /////////////////////////////////////////////////////// + // Option 1: setting the paths to service account key (and private key) as configuration + /////////////////////////////////////////////////////// + String SERVICE_ACCOUNT_KEY_PATH = "/path/to/sa_key.json"; + String PRIVATE_KEY_PATH = "/path/to/private_key.pem"; + String SERVICE_ACCOUNT_MAIL = "name-1234@sa.stackit.cloud"; - try { - ResourceManagerApi api = new ResourceManagerApi( - new CoreConfiguration() - .serviceAccountKeyPath(SERVICE_ACCOUNT_KEY_PATH) - // Optional: if private key not included in service account key - .privateKeyPath(PRIVATE_KEY_PATH) - ); + try { + ResourceManagerApi api = + new ResourceManagerApi( + new CoreConfiguration() + .serviceAccountKeyPath(SERVICE_ACCOUNT_KEY_PATH) + // Optional: if private key not included in service account key + .privateKeyPath(PRIVATE_KEY_PATH)); - /* list all organizations */ - ListOrganizationsResponse response = - api.listOrganizations(null, SERVICE_ACCOUNT_MAIL, null, null, null); + /* list all organizations */ + ListOrganizationsResponse response = + api.listOrganizations(null, SERVICE_ACCOUNT_MAIL, null, null, null); - System.out.println(response); - } catch (Exception e) { - throw new RuntimeException(e); - } + System.out.println(response); + } catch (Exception e) { + throw new RuntimeException(e); + } - /////////////////////////////////////////////////////// - // Option 2: setting the service account key (and private key) as configuration - /////////////////////////////////////////////////////// - String SERVICE_ACCOUNT_KEY = "{\n" + - " \"id\": \"uuid\",\n" + - " \"publicKey\": \"public key\",\n" + - " \"createdAt\": \"2023-08-24T14:15:22Z\",\n" + - " \"validUntil\": \"2023-08-24T14:15:22Z\",\n" + - " \"keyType\": \"USER_MANAGED\",\n" + - " \"keyOrigin\": \"USER_PROVIDED\",\n" + - " \"keyAlgorithm\": \"RSA_2048\",\n" + - " \"active\": true,\n" + - " \"credentials\": {\n" + - " \"kid\": \"string\",\n" + - " \"iss\": \"my-sa@sa.stackit.cloud\",\n" + - " \"sub\": \"uuid\",\n" + - " \"aud\": \"string\",\n" + - " \"privateKey\": \"(OPTIONAL) private key when generated by the SA service\"\n" + - " }\n" + - " }"; - String PRIVATE_KEY = "-----BEGIN PRIVATE KEY-----\n" + - "MIIJQw...ZL+U\n" + - "lm+dqO...xQ8=\n" + - "-----END PRIVATE KEY-----"; + /////////////////////////////////////////////////////// + // Option 2: setting the service account key (and private key) as configuration + /////////////////////////////////////////////////////// + String SERVICE_ACCOUNT_KEY = + "{\n" + + " \"id\": \"uuid\",\n" + + " \"publicKey\": \"public key\",\n" + + " \"createdAt\": \"2023-08-24T14:15:22Z\",\n" + + " \"validUntil\": \"2023-08-24T14:15:22Z\",\n" + + " \"keyType\": \"USER_MANAGED\",\n" + + " \"keyOrigin\": \"USER_PROVIDED\",\n" + + " \"keyAlgorithm\": \"RSA_2048\",\n" + + " \"active\": true,\n" + + " \"credentials\": {\n" + + " \"kid\": \"string\",\n" + + " \"iss\": \"my-sa@sa.stackit.cloud\",\n" + + " \"sub\": \"uuid\",\n" + + " \"aud\": \"string\",\n" + + " \"privateKey\": \"(OPTIONAL) private key when generated by the SA service\"\n" + + " }\n" + + " }"; + String PRIVATE_KEY = + "-----BEGIN PRIVATE KEY-----\n" + + "MIIJQw...ZL+U\n" + + "lm+dqO...xQ8=\n" + + "-----END PRIVATE KEY-----"; - try { - ResourceManagerApi api = new ResourceManagerApi( - new CoreConfiguration() - .serviceAccountKey(SERVICE_ACCOUNT_KEY) - // Optional: if private key not included in service account key - .privateKeyPath(PRIVATE_KEY) - ); + try { + ResourceManagerApi api = + new ResourceManagerApi( + new CoreConfiguration() + .serviceAccountKey(SERVICE_ACCOUNT_KEY) + // Optional: if private key not included in service account key + .privateKeyPath(PRIVATE_KEY)); - /* list all organizations */ - ListOrganizationsResponse response = - api.listOrganizations(null, SERVICE_ACCOUNT_MAIL, null, null, null); + /* list all organizations */ + ListOrganizationsResponse response = + api.listOrganizations(null, SERVICE_ACCOUNT_MAIL, null, null, null); - System.out.println(response); - } catch (Exception e) { - throw new RuntimeException(e); - } + System.out.println(response); + } catch (Exception e) { + throw new RuntimeException(e); + } - /////////////////////////////////////////////////////// - // Option 3: setting the service account key (and private key) as environment variable - /////////////////////////////////////////////////////// - // Set the service account key via environment variable: - // - STACKIT_SERVICE_ACCOUNT_KEY_PATH=/path/to/sa_key.json - // - STACKIT_SERVICE_ACCOUNT_KEY="" - // - // If the private key is not included in the service account key, set also: - // - STACKIT_PRIVATE_KEY_PATH=/path/to/private_key.pem - // - STACKIT_PRIVATE_KEY="" - // - // If no environment variable is set, fallback to credentials file in "$HOME/.stackit/credentials.json". - // Can be overridden with the environment variable `STACKIT_CREDENTIALS_PATH` - // The credentials file must be a json: - // { - // "STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json", - // "STACKIT_PRIVATE_KEY_PATH": "(OPTIONAL) when the private key isn't included in the Service Account key", - // // Alternative: - // "STACKIT_SERVICE_ACCOUNT_KEY": "", - // "STACKIT_PRIVATE_KEY": "(OPTIONAL) when the private key isn't included in the Service Account key", - // } - try { - ResourceManagerApi api = new ResourceManagerApi(); + /////////////////////////////////////////////////////// + // Option 3: setting the service account key (and private key) as environment variable + /////////////////////////////////////////////////////// + // Set the service account key via environment variable: + // - STACKIT_SERVICE_ACCOUNT_KEY_PATH=/path/to/sa_key.json + // - STACKIT_SERVICE_ACCOUNT_KEY="" + // + // If the private key is not included in the service account key, set also: + // - STACKIT_PRIVATE_KEY_PATH=/path/to/private_key.pem + // - STACKIT_PRIVATE_KEY="" + // + // If no environment variable is set, fallback to credentials file in + // "$HOME/.stackit/credentials.json". + // Can be overridden with the environment variable `STACKIT_CREDENTIALS_PATH` + // The credentials file must be a json: + // { + // "STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json", + // "STACKIT_PRIVATE_KEY_PATH": "(OPTIONAL) when the private key isn't included in the + // Service Account key", + // // Alternative: + // "STACKIT_SERVICE_ACCOUNT_KEY": "", + // "STACKIT_PRIVATE_KEY": "(OPTIONAL) when the private key isn't included in the Service + // Account key", + // } + try { + ResourceManagerApi api = new ResourceManagerApi(); - /* list all organizations */ - ListOrganizationsResponse response = - api.listOrganizations(null, SERVICE_ACCOUNT_MAIL, null, null, null); + /* list all organizations */ + ListOrganizationsResponse response = + api.listOrganizations(null, SERVICE_ACCOUNT_MAIL, null, null, null); - System.out.println(response); - } catch (Exception e) { - throw new RuntimeException(e); - } - } + System.out.println(response); + } catch (Exception e) { + throw new RuntimeException(e); + } + } } From 4dc8a7afeac934201db43dcc185f1875a0293209 Mon Sep 17 00:00:00 2001 From: Marcel Jacek Date: Tue, 16 Sep 2025 12:20:17 +0200 Subject: [PATCH 4/8] rework AuthenticationExample option 2 --- README.md | 53 ++++++++-------- .../examples/AuthenticationExample.java | 60 +++++++++++-------- .../dummy_credentials/dummy-private-key.pem | 5 ++ .../dummy-service-account-key.json | 17 ++++++ 4 files changed, 85 insertions(+), 50 deletions(-) create mode 100644 examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-private-key.pem create mode 100644 examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-service-account-key.json diff --git a/README.md b/README.md index e71ad30..e39fa67 100644 --- a/README.md +++ b/README.md @@ -16,12 +16,12 @@ This repository contains the STACKIT SDKs for Java. Requires Java 8 or higher. -The release artifacts of the STACKIT Java SDK are available on [Maven Central](https://central.sonatype.com/namespace/cloud.stackit.sdk). +The release artifacts of the STACKIT Java SDK are available on [Maven Central](https://central.sonatype.com/namespace/cloud.stackit.sdk). See below how to use them in your Java project. ### Maven -Add the dependencies for the services you want to interact with to your project's POM, e.g. `iaas` and `resourcemanager` (replace `` with the latest version of each SDK submdoule): +Add the dependencies for the services you want to interact with to your project's POM, e.g. `iaas` and `resourcemanager` (replace `` with the latest version of each SDK submdoule): ```xml @@ -97,31 +97,33 @@ This will make it much easier to configure the key flow authentication in the SD To configure the key flow, follow this steps: 1. Create a service account key: - - Use the STACKIT Portal: go to the `Service Accounts` tab, choose a `Service Account` and go to `Service Account Keys` to create a key. For more details, see [Create a service account key](https://docs.stackit.cloud/stackit/en/create-a-service-account-key-175112456.html). + - Use the STACKIT Portal: go to the `Service Accounts` tab, choose a `Service Account` and go to `Service Account Keys` to create a key. For more details, see [Create a service account key](https://docs.stackit.cloud/stackit/en/create-a-service-account-key-175112456.html). 2. Save the content of the service account key by copying it and saving it in a JSON file. The expected format of the service account key is **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", - "privateKey": "(OPTIONAL) private key when generated by the SA service" - } - } - ``` + ```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", + "privateKey": "(OPTIONAL) private key when generated by the SA service" + } + } + ``` 3. Configure the service account key for authentication in the SDK by following one of the alternatives below: + - using the configuration options: + ```java CoreConfiguration config = new CoreConfiguration() @@ -130,6 +132,7 @@ To configure the key flow, follow this steps: ResourceManagerApi api = new ResourceManagerApi(config); ``` + - setting the environment variable: `STACKIT_SERVICE_ACCOUNT_KEY_PATH` - setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH` in the credentials file (see above) @@ -145,11 +148,11 @@ To configure the key flow, follow this steps: > - setting the environment variable: `STACKIT_PRIVATE_KEY_PATH` > - setting `STACKIT_PRIVATE_KEY_PATH` in the credentials file (see above) -> **Alternatively, if you can't store the credentials in a file, e.g. when using it in a pipeline**, you can store the credentials in environment variables: +> **Alternatively, if you can't store the credentials in a file, e.g. when using it in a pipeline**, you can store the credentials in environment variables: +> > - setting the environment variable `STACKIT_SERVICE_ACCOUNT_KEY` with the content of the service account key > - (OPTIONAL) setting the environment variable `STACKIT_PRIVATE_KEY` with the content of the private key - 4. The SDK will search for the keys and, if valid, will use them to get access and refresh tokens which will be used to authenticate all the requests. Check the [authentication example](examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java) for more details. @@ -166,7 +169,7 @@ import cloud.stackit.sdk.resourcemanager.model.ListOrganizationsResponse; import java.io.IOException; class CustomEndpointExample { - public static void main(String[] args) { + public static void main(String[] args) { CoreConfiguration config = new CoreConfiguration() .serviceAccountKey("/path/to/sa_key.json") diff --git a/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java index 282ee19..da1c4bd 100644 --- a/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java +++ b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java @@ -3,9 +3,13 @@ import cloud.stackit.sdk.core.config.CoreConfiguration; import cloud.stackit.sdk.resourcemanager.api.ResourceManagerApi; import cloud.stackit.sdk.resourcemanager.model.ListOrganizationsResponse; +import java.io.File; +import java.io.FileNotFoundException; +import java.io.IOException; +import java.util.Scanner; class AuthenticationExample { - public static void main(String[] args) { + public static void main(String[] args) throws IOException { /////////////////////////////////////////////////////// // Option 1: setting the paths to service account key (and private key) as configuration /////////////////////////////////////////////////////// @@ -33,29 +37,35 @@ public static void main(String[] args) { /////////////////////////////////////////////////////// // Option 2: setting the service account key (and private key) as configuration /////////////////////////////////////////////////////// - String SERVICE_ACCOUNT_KEY = - "{\n" - + " \"id\": \"uuid\",\n" - + " \"publicKey\": \"public key\",\n" - + " \"createdAt\": \"2023-08-24T14:15:22Z\",\n" - + " \"validUntil\": \"2023-08-24T14:15:22Z\",\n" - + " \"keyType\": \"USER_MANAGED\",\n" - + " \"keyOrigin\": \"USER_PROVIDED\",\n" - + " \"keyAlgorithm\": \"RSA_2048\",\n" - + " \"active\": true,\n" - + " \"credentials\": {\n" - + " \"kid\": \"string\",\n" - + " \"iss\": \"my-sa@sa.stackit.cloud\",\n" - + " \"sub\": \"uuid\",\n" - + " \"aud\": \"string\",\n" - + " \"privateKey\": \"(OPTIONAL) private key when generated by the SA service\"\n" - + " }\n" - + " }"; - String PRIVATE_KEY = - "-----BEGIN PRIVATE KEY-----\n" - + "MIIJQw...ZL+U\n" - + "lm+dqO...xQ8=\n" - + "-----END PRIVATE KEY-----"; + + // read key content from a file, in production you can also read it e.g. from STACKIT + // secrets manager, so it's only kept in-memory + String serviceAccountKeyPath = + "examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-service-account-key.json"; + File serviceAccountKeyFile = new File(serviceAccountKeyPath); + StringBuilder serviceAccountKeyContent = new StringBuilder(); + try (Scanner myReader = new Scanner(serviceAccountKeyFile)) { + while (myReader.hasNextLine()) { + serviceAccountKeyContent.append(myReader.nextLine()); + } + } catch (FileNotFoundException e) { + throw new RuntimeException(e); + } + + String privateKeyPath = + "examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-private-key.pem"; + File privateKeyFile = new File(privateKeyPath); + StringBuilder privateKeyContent = new StringBuilder(); + try (Scanner myReader = new Scanner(privateKeyFile)) { + while (myReader.hasNextLine()) { + privateKeyContent.append(myReader.nextLine()); + } + } catch (FileNotFoundException e) { + throw new RuntimeException(e); + } + + String SERVICE_ACCOUNT_KEY = serviceAccountKeyContent.toString(); + String PRIVATE_KEY = privateKeyContent.toString(); try { ResourceManagerApi api = @@ -63,7 +73,7 @@ public static void main(String[] args) { new CoreConfiguration() .serviceAccountKey(SERVICE_ACCOUNT_KEY) // Optional: if private key not included in service account key - .privateKeyPath(PRIVATE_KEY)); + .privateKey(PRIVATE_KEY)); /* list all organizations */ ListOrganizationsResponse response = diff --git a/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-private-key.pem b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-private-key.pem new file mode 100644 index 0000000..d4ba858 --- /dev/null +++ b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-private-key.pem @@ -0,0 +1,5 @@ +-----BEGIN PRIVATE KEY----- +MIIJQw...ZL+U +... +lm+dqO...xQ8= +-----END PRIVATE KEY----- \ No newline at end of file diff --git a/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-service-account-key.json b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-service-account-key.json new file mode 100644 index 0000000..bba8876 --- /dev/null +++ b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-service-account-key.json @@ -0,0 +1,17 @@ +{ + "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", + "privateKey": "(OPTIONAL) private key when generated by the SA service" + } +} \ No newline at end of file From ece0c348c189fbee7fb38f201381923560784b58 Mon Sep 17 00:00:00 2001 From: Marcel Jacek Date: Tue, 16 Sep 2025 12:23:56 +0200 Subject: [PATCH 5/8] set mainClassName property for authentication example --- examples/authentication/build.gradle | 2 ++ 1 file changed, 2 insertions(+) diff --git a/examples/authentication/build.gradle b/examples/authentication/build.gradle index 1518830..5d6f7db 100644 --- a/examples/authentication/build.gradle +++ b/examples/authentication/build.gradle @@ -1,3 +1,5 @@ dependencies { implementation project (':services:resourcemanager') } + +ext.mainClassName = 'cloud.stackit.sdk.authentication.examples.AuthenticationExample' \ No newline at end of file From 9747d4f8f461d2734e4d11884df4c0b7d2ad6134 Mon Sep 17 00:00:00 2001 From: Marcel Jacek Date: Tue, 16 Sep 2025 12:32:20 +0200 Subject: [PATCH 6/8] update AuthenticationExample --- .../sdk/authentication/examples/AuthenticationExample.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java index da1c4bd..b292f3d 100644 --- a/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java +++ b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java @@ -40,7 +40,7 @@ public static void main(String[] args) throws IOException { // read key content from a file, in production you can also read it e.g. from STACKIT // secrets manager, so it's only kept in-memory - String serviceAccountKeyPath = + String serviceAccountKeyPath = // replace it with the path to your service account key "examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-service-account-key.json"; File serviceAccountKeyFile = new File(serviceAccountKeyPath); StringBuilder serviceAccountKeyContent = new StringBuilder(); @@ -52,7 +52,7 @@ public static void main(String[] args) throws IOException { throw new RuntimeException(e); } - String privateKeyPath = + String privateKeyPath = // replace it with the path to your private key "examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-private-key.pem"; File privateKeyFile = new File(privateKeyPath); StringBuilder privateKeyContent = new StringBuilder(); From e2077f173f6f56fe0aed22498fdefbdb07d5bd5a Mon Sep 17 00:00:00 2001 From: Marcel Jacek Date: Tue, 16 Sep 2025 13:06:05 +0200 Subject: [PATCH 7/8] formatter --- examples/authentication/build.gradle | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/authentication/build.gradle b/examples/authentication/build.gradle index 5d6f7db..55e63ea 100644 --- a/examples/authentication/build.gradle +++ b/examples/authentication/build.gradle @@ -2,4 +2,4 @@ dependencies { implementation project (':services:resourcemanager') } -ext.mainClassName = 'cloud.stackit.sdk.authentication.examples.AuthenticationExample' \ No newline at end of file +ext.mainClassName = 'cloud.stackit.sdk.authentication.examples.AuthenticationExample' From df1b27dc24328f68d8e261382d057ddf6dd7be8b Mon Sep 17 00:00:00 2001 From: Marcel Jacek Date: Tue, 16 Sep 2025 13:51:37 +0200 Subject: [PATCH 8/8] review feedback --- .../examples/AuthenticationExample.java | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java index b292f3d..6dbe00f 100644 --- a/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java +++ b/examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java @@ -13,9 +13,9 @@ public static void main(String[] args) throws IOException { /////////////////////////////////////////////////////// // Option 1: setting the paths to service account key (and private key) as configuration /////////////////////////////////////////////////////// - String SERVICE_ACCOUNT_KEY_PATH = "/path/to/sa_key.json"; - String PRIVATE_KEY_PATH = "/path/to/private_key.pem"; - String SERVICE_ACCOUNT_MAIL = "name-1234@sa.stackit.cloud"; + final String SERVICE_ACCOUNT_KEY_PATH = "/path/to/sa_key.json"; + final String PRIVATE_KEY_PATH = "/path/to/private_key.pem"; + final String SERVICE_ACCOUNT_MAIL = "name-1234@sa.stackit.cloud"; try { ResourceManagerApi api = @@ -64,16 +64,16 @@ public static void main(String[] args) throws IOException { throw new RuntimeException(e); } - String SERVICE_ACCOUNT_KEY = serviceAccountKeyContent.toString(); - String PRIVATE_KEY = privateKeyContent.toString(); + String serviceAccountKey = serviceAccountKeyContent.toString(); + String privateKey = privateKeyContent.toString(); try { ResourceManagerApi api = new ResourceManagerApi( new CoreConfiguration() - .serviceAccountKey(SERVICE_ACCOUNT_KEY) + .serviceAccountKey(serviceAccountKey) // Optional: if private key not included in service account key - .privateKey(PRIVATE_KEY)); + .privateKey(privateKey)); /* list all organizations */ ListOrganizationsResponse response =