Skip to content

Commit 7e824cf

Browse files
marceljkmarceljk
authored
feat(docs): add authentication and custom endpoint guide (#26)
relates to STACKITSDK-183
1 parent 44d23b5 commit 7e824cf

File tree

5 files changed

+266
-8
lines changed

5 files changed

+266
-8
lines changed

‎README.md‎

Lines changed: 140 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,12 @@ This repository contains the STACKIT SDKs for Java.
1616

1717
Requires Java 8 or higher.
1818

19-
The release artifacts of the STACKIT Java SDK are available on [Maven Central](https://central.sonatype.com/namespace/cloud.stackit.sdk).
19+
The release artifacts of the STACKIT Java SDK are available on [Maven Central](https://central.sonatype.com/namespace/cloud.stackit.sdk).
2020
See below how to use them in your Java project.
2121

2222
### Maven
2323

24-
Add the dependencies for the services you want to interact with to your project's POM, e.g. `iaas` and `resourcemanager` (replace `<SDK_VERSION>` with the latest version of each SDK submdoule):
24+
Add the dependencies for the services you want to interact with to your project's POM, e.g. `iaas` and `resourcemanager` (replace `<SDK_VERSION>` with the latest version of each SDK submdoule):
2525

2626
```xml
2727
<dependency>
@@ -59,6 +59,144 @@ Add the dependencies to your project's build file (replace `<SDK_VERSION>` with
5959

6060
Examples on services, configuration and authentication possibilities can be found in the [examples folder](https://github.com/stackitcloud/stackit-sdk-java/tree/main/examples).
6161

62+
## Authorization
63+
64+
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`.
65+
66+
The Java SDK supports only Key flow for authentication.
67+
68+
When setting up authentication, the SDK will search for credentials in several locations, following a specific order:
69+
70+
1. Explicit configuration, e.g. by using the option `new CoreConfiguration().serviceAccountKeyPath("path/to/sa_key.json")`
71+
2. Environment variable, e.g. by setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH`
72+
3. Credentials file
73+
74+
The SDK will check the credentials file located in the path defined by the `STACKIT_CREDENTIALS_PATH` env var, if specified,
75+
or in `$HOME/.stackit/credentials.json` as a fallback.
76+
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:
77+
78+
```json
79+
{
80+
"STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json",
81+
"STACKIT_PRIVATE_KEY_PATH": "(OPTIONAL) when the private key isn't included in the Service Account key"
82+
}
83+
```
84+
85+
### Example
86+
87+
The following instructions assume that you have created a service account and assigned it the necessary permissions, e.g. `project.owner`.
88+
89+
To use the key flow, you need to have a service account key, which must have an RSA key-pair attached to it.
90+
91+
When creating the service account key, a new pair can be created automatically, which will be included in the service account key.
92+
This will make it much easier to configure the key flow authentication in the SDK, by just providing the service account key.
93+
94+
> **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.
95+
> 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).
96+
97+
To configure the key flow, follow this steps:
98+
99+
1. Create a service account key:
100+
- 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).
101+
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:
102+
103+
```json
104+
{
105+
"id": "uuid",
106+
"publicKey": "public key",
107+
"createdAt": "2023-08-24T14:15:22Z",
108+
"validUntil": "2023-08-24T14:15:22Z",
109+
"keyType": "USER_MANAGED",
110+
"keyOrigin": "USER_PROVIDED",
111+
"keyAlgorithm": "RSA_2048",
112+
"active": true,
113+
"credentials": {
114+
"kid": "string",
115+
"iss": "[email protected]",
116+
"sub": "uuid",
117+
"aud": "string",
118+
"privateKey": "(OPTIONAL) private key when generated by the SA service"
119+
}
120+
}
121+
```
122+
123+
3. Configure the service account key for authentication in the SDK by following one of the alternatives below:
124+
125+
- using the configuration options:
126+
127+
```java
128+
CoreConfiguration config =
129+
new CoreConfiguration()
130+
...
131+
.serviceAccountKeyPath("/path/to/service_account_key.json");
132+
133+
ResourceManagerApi api = new ResourceManagerApi(config);
134+
```
135+
136+
- setting the environment variable: `STACKIT_SERVICE_ACCOUNT_KEY_PATH`
137+
- setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH` in the credentials file (see above)
138+
139+
> **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:
140+
>
141+
> - using the configuration options:
142+
> ```java
143+
> CoreConfiguration config =
144+
> new CoreConfiguration()
145+
> ...
146+
> .privateKeyPath("/path/to/private_key.pem");
147+
> ```
148+
> - setting the environment variable: `STACKIT_PRIVATE_KEY_PATH`
149+
> - setting `STACKIT_PRIVATE_KEY_PATH` in the credentials file (see above)
150+
151+
> **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:
152+
>
153+
> - setting the environment variable `STACKIT_SERVICE_ACCOUNT_KEY` with the content of the service account key
154+
> - (OPTIONAL) setting the environment variable `STACKIT_PRIVATE_KEY` with the content of the private key
155+
156+
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.
157+
158+
Check the [authentication example](examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java) for more details.
159+
160+
## Using custom endpoints
161+
162+
The example below shows how to use the STACKIT Java SDK in custom STACKIT enviroments.
163+
164+
```java
165+
import cloud.stackit.sdk.core.config.CoreConfiguration;
166+
import cloud.stackit.sdk.resourcemanager.api.ResourceManagerApi;
167+
import cloud.stackit.sdk.resourcemanager.model.ListOrganizationsResponse;
168+
169+
import java.io.IOException;
170+
171+
class CustomEndpointExample {
172+
public static void main(String[] args) {
173+
CoreConfiguration config =
174+
new CoreConfiguration()
175+
.serviceAccountKey("/path/to/sa_key.json")
176+
.customEndpoint("https://resource-manager.api.stackit.cloud")
177+
.tokenCustomUrl("https://service-account.api.stackit.cloud/token");
178+
179+
try {
180+
ResourceManagerApi resourceManagerApi = new ResourceManagerApi(config);
181+
182+
/* list all organizations */
183+
ListOrganizationsResponse response =
184+
resourceManagerApi.listOrganizations(
185+
null,
186+
"[email protected]",
187+
null,
188+
null,
189+
null
190+
);
191+
192+
System.out.println(response);
193+
} catch (Exception e) {
194+
throw new RuntimeException(e);
195+
}
196+
}
197+
}
198+
```
199+
62200
## Reporting issues
63201
64202
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/).

‎examples/authentication/build.gradle‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
11
dependencies {
22
implementation project (':services:resourcemanager')
33
}
4+
5+
ext.mainClassName = 'cloud.stackit.sdk.authentication.examples.AuthenticationExample'

‎examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/AuthenticationExample.java‎

Lines changed: 102 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,113 @@
33
import cloud.stackit.sdk.core.config.CoreConfiguration;
44
import cloud.stackit.sdk.resourcemanager.api.ResourceManagerApi;
55
import cloud.stackit.sdk.resourcemanager.model.ListOrganizationsResponse;
6+
import java.io.File;
7+
import java.io.FileNotFoundException;
8+
import java.io.IOException;
9+
import java.util.Scanner;
610

711
class AuthenticationExample {
8-
public static void main(String[] args) {
9-
String SERVICE_ACCOUNT_KEY_PATH = "/path/to/your/sa/key.json";
10-
String SERVICE_ACCOUNT_MAIL = "[email protected]";
12+
public static void main(String[] args) throws IOException {
13+
///////////////////////////////////////////////////////
14+
// Option 1: setting the paths to service account key (and private key) as configuration
15+
///////////////////////////////////////////////////////
16+
final String SERVICE_ACCOUNT_KEY_PATH = "/path/to/sa_key.json";
17+
final String PRIVATE_KEY_PATH = "/path/to/private_key.pem";
18+
final String SERVICE_ACCOUNT_MAIL = "[email protected]";
1119

12-
CoreConfiguration config =
13-
new CoreConfiguration().serviceAccountKeyPath(SERVICE_ACCOUNT_KEY_PATH);
20+
try {
21+
ResourceManagerApi api =
22+
new ResourceManagerApi(
23+
new CoreConfiguration()
24+
.serviceAccountKeyPath(SERVICE_ACCOUNT_KEY_PATH)
25+
// Optional: if private key not included in service account key
26+
.privateKeyPath(PRIVATE_KEY_PATH));
27+
28+
/* list all organizations */
29+
ListOrganizationsResponse response =
30+
api.listOrganizations(null, SERVICE_ACCOUNT_MAIL, null, null, null);
31+
32+
System.out.println(response);
33+
} catch (Exception e) {
34+
throw new RuntimeException(e);
35+
}
36+
37+
///////////////////////////////////////////////////////
38+
// Option 2: setting the service account key (and private key) as configuration
39+
///////////////////////////////////////////////////////
40+
41+
// read key content from a file, in production you can also read it e.g. from STACKIT
42+
// secrets manager, so it's only kept in-memory
43+
String serviceAccountKeyPath = // replace it with the path to your service account key
44+
"examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-service-account-key.json";
45+
File serviceAccountKeyFile = new File(serviceAccountKeyPath);
46+
StringBuilder serviceAccountKeyContent = new StringBuilder();
47+
try (Scanner myReader = new Scanner(serviceAccountKeyFile)) {
48+
while (myReader.hasNextLine()) {
49+
serviceAccountKeyContent.append(myReader.nextLine());
50+
}
51+
} catch (FileNotFoundException e) {
52+
throw new RuntimeException(e);
53+
}
54+
55+
String privateKeyPath = // replace it with the path to your private key
56+
"examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-private-key.pem";
57+
File privateKeyFile = new File(privateKeyPath);
58+
StringBuilder privateKeyContent = new StringBuilder();
59+
try (Scanner myReader = new Scanner(privateKeyFile)) {
60+
while (myReader.hasNextLine()) {
61+
privateKeyContent.append(myReader.nextLine());
62+
}
63+
} catch (FileNotFoundException e) {
64+
throw new RuntimeException(e);
65+
}
66+
67+
String serviceAccountKey = serviceAccountKeyContent.toString();
68+
String privateKey = privateKeyContent.toString();
69+
70+
try {
71+
ResourceManagerApi api =
72+
new ResourceManagerApi(
73+
new CoreConfiguration()
74+
.serviceAccountKey(serviceAccountKey)
75+
// Optional: if private key not included in service account key
76+
.privateKey(privateKey));
77+
78+
/* list all organizations */
79+
ListOrganizationsResponse response =
80+
api.listOrganizations(null, SERVICE_ACCOUNT_MAIL, null, null, null);
81+
82+
System.out.println(response);
83+
} catch (Exception e) {
84+
throw new RuntimeException(e);
85+
}
1486

87+
///////////////////////////////////////////////////////
88+
// Option 3: setting the service account key (and private key) as environment variable
89+
///////////////////////////////////////////////////////
90+
// Set the service account key via environment variable:
91+
// - STACKIT_SERVICE_ACCOUNT_KEY_PATH=/path/to/sa_key.json
92+
// - STACKIT_SERVICE_ACCOUNT_KEY="<content of service account key>"
93+
//
94+
// If the private key is not included in the service account key, set also:
95+
// - STACKIT_PRIVATE_KEY_PATH=/path/to/private_key.pem
96+
// - STACKIT_PRIVATE_KEY="<content of private key>"
97+
//
98+
// If no environment variable is set, fallback to credentials file in
99+
// "$HOME/.stackit/credentials.json".
100+
// Can be overridden with the environment variable `STACKIT_CREDENTIALS_PATH`
101+
// The credentials file must be a json:
102+
// {
103+
// "STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json",
104+
// "STACKIT_PRIVATE_KEY_PATH": "(OPTIONAL) when the private key isn't included in the
105+
// Service Account key",
106+
// // Alternative:
107+
// "STACKIT_SERVICE_ACCOUNT_KEY": "<content of private key>",
108+
// "STACKIT_PRIVATE_KEY": "(OPTIONAL) when the private key isn't included in the Service
109+
// Account key",
110+
// }
15111
try {
16-
ResourceManagerApi api = new ResourceManagerApi(config);
112+
ResourceManagerApi api = new ResourceManagerApi();
17113

18114
/* list all organizations */
19115
ListOrganizationsResponse response =

‎examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-private-key.pem‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
-----BEGIN PRIVATE KEY-----
2+
MIIJQw...ZL+U
3+
...
4+
lm+dqO...xQ8=
5+
-----END PRIVATE KEY-----

‎examples/authentication/src/main/java/cloud/stackit/sdk/authentication/examples/dummy_credentials/dummy-service-account-key.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"id": "uuid",
3+
"publicKey": "public key",
4+
"createdAt": "2023-08-24T14:15:22Z",
5+
"validUntil": "2023-08-24T14:15:22Z",
6+
"keyType": "USER_MANAGED",
7+
"keyOrigin": "USER_PROVIDED",
8+
"keyAlgorithm": "RSA_2048",
9+
"active": true,
10+
"credentials": {
11+
"kid": "string",
12+
"iss": "[email protected]",
13+
"sub": "uuid",
14+
"aud": "string",
15+
"privateKey": "(OPTIONAL) private key when generated by the SA service"
16+
}
17+
}

0 commit comments

Comments
 (0)