Skip to content

docs: add authentication and custom endpoint guide #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Sep 16, 2025
Merged

docs: add authentication and custom endpoint guide #26

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
df99dea
extend AuthenticationExample
marceljk Sep 12, 2025
cb764df
extend README with Authorization
marceljk Sep 12, 2025
b1f0763
formatting auth example
marceljk Sep 12, 2025
4dc8a7a
rework AuthenticationExample option 2
marceljk Sep 16, 2025
ece0c34
set mainClassName property for authentication example
marceljk Sep 16, 2025
9747d4f
update AuthenticationExample
marceljk Sep 16, 2025
e2077f1
formatter
marceljk Sep 16, 2025
df1b27d
review feedback
marceljk Sep 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 135 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,141 @@ Add the dependencies to your project's build file (replace `<SDK_VERSION>` 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": "[email protected]",
"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,
"[email protected]",
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/).
Expand Down
94 changes: 90 additions & 4 deletions ...cation/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,100 @@

class AuthenticationExample {
public static void main(String[] args) {
String SERVICE_ACCOUNT_KEY_PATH = "/path/to/your/sa/key.json";
///////////////////////////////////////////////////////
// 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 = "[email protected]";

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));

/* 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 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\": \"[email protected]\",\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="<content of 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="<content of 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": "<content of private key>",
// "STACKIT_PRIVATE_KEY": "(OPTIONAL) when the private key isn't included in the Service
// Account key",
// }
try {
ResourceManagerApi api = new ResourceManagerApi(config);
ResourceManagerApi api = new ResourceManagerApi();

/* list all organizations */
ListOrganizationsResponse response =
Expand Down