Connection and authorization examples, custom sidebar

Installation.md

@@ -0,0 +1,28 @@
+# Java Vault Connector 
+
+## Installation
+
+[![Maven Central](https://img.shields.io/maven-central/v/de.stklcode.jvault/connector.svg)](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22de.stklcode.jvault%22%20AND%20a%3A%22connector%22)
+
+The connector is published at Maven Central and may be included into your project easily.
+
+### Maven Dependency
+
+```xml
+<dependency>
+    <groupId>de.stklcode.jvault</groupId>
+    <artifactId>connector</artifactId>
+    <version>0.7.1</version>
+</dependency>
+```
+
+### Gradle Dependency
+```groovy
+compile group: 'de.stklcode.jvault', name: 'connector', version: '0.7.1'
+``` 
+
+### SBT Dependency
+```
+libraryDependencies += "de.stklcode.jvault" % "connector" % "0.7.1"
+
+```

Usage-Authorization.md

@@ -0,0 +1,77 @@
+# Java Vault Connector 
+
+## Usage Examples
+
+### Authorization
+
+The connector currently supports four authorization methods.
+ * Token
+ * Username & Password
+ * AppRole
+ * AppID [_deprecated_]
+ 
+ #### Token
+ 
+ ##### Authenticate
+ 
+ ```java
+ VaultConnector connector = ...;
+ connector.authToken("01234567-89ab-cdef-0123-456789abcdef");
+```
+
+##### Create new Token
+```java
+ // Create new token using the builder (supports all current parameters).
+ Token token = new TokenBuilder()
+                   .withId("token-id")
+                   .withDisplayName("token name")
+                   .build();
+ // Write token to Vault (orphan creatin and role binding possible).
+ AuthResponse createResponse = connector.createToken(token);
+```
+
+
+
+#### Username & Password
+ 
+##### Authenticate
+ 
+ ```java
+ VaultConnector connector = ...;
+ connector.authUserPass("username", "p4ssw0rd");
+```
+
+ #### AppRole
+ 
+ ##### Authenticate
+ ```java
+ VaultConnector connector = ...;
+ // connector.authAppId("role-id", "secret-id");
+ connector.authAppRole("01234567-89ab-cdef-0123-456789abcdef", "fedcba98-7654-3210-fedc-ba9876543210");
+```
+
+##### Manage roles and secrets
+
+ ```java
+ // Create new role using the builder. Supports all current role parameters.
+ AppRole role = new AppRoleBuilder("role-name").build();
+ 
+ // Write the new role to Vault.
+ boolean createSuccess = connector.createAppRole(role);
+ 
+ // Lookup the role by name.
+ AppRoleResponse res = connector.lookupAppRole("role-name");
+ 
+ // Create a new secret with random ID.
+ AppRoleSecretResponse secret = connector.createAppRoleSecret("role-name");
+ 
+ // Destroy the secret.
+ boolean destroySuccess = connector.destroyAppRoleSecret("role-name", secret.getSecret().getId());
+```
+
+ #### AppID
+ ```java
+ VaultConnector connector = ...;
+ // connector.authAppId("app-id", "user-id");
+ connector.authAppId("01234567-89ab-cdef-0123-456789abcdef", "fedcba98-7654-3210-fedc-ba9876543210");
+```

Usage-Connection.md

@@ -0,0 +1,54 @@
+# Java Vault Connector 
+
+## Usage Examples
+
+### Connection
+
+The package features an HTTP connector by default.
+To establish connection to your Vault cluter, the connector needs to be instantiated with the relevant parameters.
+
+To do so, use the builder to configure your connector.
+
+#### Simple instantiation
+
+```java
+ // Instantiate using builder pattern style factory (TLS enabled by default)
+ VaultConnector connector = VaultConnectorBuilder.http()
+   .withHost("vault.example.com")   // Default: 127.0.0.1
+   .withPort(8200)                  // Default: 8200
+   .withTLS()                       // Default. Possible without TLS and with explicit version.
+   .build();
+```
+
+#### Provide custom CA certificate
+
+For internal sites or to enforce a specific CA you might provide a custom CA certificate to trust.
+
+```java
+ VaultConnector connector = VaultConnectorBuilder.http()
+   .withHost("vaultexample.com")
+   .withPort(8200)
+   .withTrustedCA(Paths.get("/path/to/CA.pem"))
+   .build();
+```
+
+#### Configuration from environment variables
+
+It is also possible to provide the configuraiton externally through environment variables.
+This feature supports the default Vault environment variables:
+
+* `VAULT_ADDR`        - URL to Vault cluster (e.g. _https://vault.example.com:8200_)
+* `VAULT_CACERT`      - Path to custom CA certificate
+* `VAULT_MAX_RETRIES` - Maximum number of retries on connection failure
+* `VAULT_TOKEN`       - Token for automatic authentication.
+
+```java
+ VaultConnector vault = VaultConnectorBuilder.http()
+   .fromEnv()
+   .build();
+
+ // Or with automatic authentication.
+ VaultConnector connector = VaultConnectorBuilder.http()
+   .fromEnv()
+   .buildAndAuth();
+```

Usage.md

@@ -0,0 +1,13 @@
+# Java Vault Connector 
+
+## Usage Examples
+
+This section provides usage examples.
+All code snippets are written in Java.
+The examples assume using the latest published version of the connector.
+Common use cases are shown tha do not necessarily show the full functionality.
+For a complete guide refer to the API docs.
+
+### Topics:
+* [[Connection|Usage Connection]]
+* [[Authorization|Usage Authorization]]

_Sidebar.md

@@ -0,0 +1,7 @@
+# [[Home|Home]]
+
+# [[Installation|Installation]]
+
+# [[Usage Examples|Usage]]
+* [[Connection|Usage Connection]]
+* [[Authorization|Usage Authorization]]