Skip to content
This repository has been archived by the owner on Dec 5, 2022. It is now read-only.

Reorganized usage sections in README #199

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
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
34 changes: 18 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Some of the features Tokens offers:
- configuration flexibility; specify multiple tokens with different scopes
- the ability to inject fixed OAuth2 access tokens

Tokens can be useful to devs (at any company, large or small) who are working with highly-distributed microservices deployed in the cloud and need to authenticate the traffic generated when accessing APIs. For example, if your team wants to consume an API with OAuth2 credentials, Tokens will fetch the tokens for you. Then you just [add scopes](#Usage) in the token.
Tokens can be useful to devs (at any company, large or small) who are working with highly-distributed microservices deployed in the cloud and need to authenticate the traffic generated when accessing APIs. For example, if your team wants to consume an API with OAuth2 credentials, Tokens will fetch the tokens for you. Then you just [add scopes](#Usage) in the token (configuration based for k8s environment, or directly in code for Zalando STUPS environment).

When creating tokens, it's easy to make a lot of mistakes. Tokens aims to save you hassle and time.

Expand All @@ -43,7 +43,9 @@ Add it with:

``compile('org.zalando.stups:tokens:${version}') ``

### Usage in Zalandos K8s environment (with `PlatformCredentialsSet`)
### Usage

#### Usage in Zalandos K8s environment (with `PlatformCredentialsSet`)

It uses `/meta/credentials` as a default folder to look for provided tokens by `PlatformCredentialsSet`.

Expand All @@ -67,7 +69,7 @@ while (true) {

Want to migrate from STUPS to K8s? [See the hints](#migration-from-zalandos-stups-env-to-zalandos-k8s-env).

### Usage in Zalandos STUPS environment
#### Usage in Zalandos STUPS environment

```java
import org.zalando.stups.tokens.Tokens;
Expand All @@ -94,6 +96,19 @@ while (true) {
}
```

#### Local Testing

With Tokens, you can inject fixed OAuth2 access tokens via the `OAUTH2_ACCESS_TOKENS` environment variable and test applications locally with personal OAuth2 tokens. As an example:

```bash
$ MY_TOKEN_1=$(zign token -n mytok1)
$ MY_TOKEN_2=$(zign token -n mytok2)
$ export OAUTH2_ACCESS_TOKENS=mytok1=$MY_TOKEN_1,mytok2=$MY_TOKEN_2
$ lein repl # start my local Clojure app using the tokens library
```

In production on EC2 instances, Tokens fetches access tokens by requesting an authorization server with credentials, found in `client.json` and `user.json`. It's also possible to provide `client.json` and `user.json` with valid content and point this library to that directory.

### Migration from Zalandos STUPS env to Zalandos K8s env

Your code can stay as is.
Expand Down Expand Up @@ -131,19 +146,6 @@ spec:
- com.zalando::read
```

### Local Testing

With Tokens, you can inject fixed OAuth2 access tokens via the `OAUTH2_ACCESS_TOKENS` environment variable and test applications locally with personal OAuth2 tokens. As an example:

```bash
$ MY_TOKEN_1=$(zign token -n mytok1)
$ MY_TOKEN_2=$(zign token -n mytok2)
$ export OAUTH2_ACCESS_TOKENS=mytok1=$MY_TOKEN_1,mytok2=$MY_TOKEN_2
$ lein repl # start my local Clojure app using the tokens library
```

In production on EC2 instances, Tokens fetches access tokens by requesting an authorization server with credentials, found in `client.json` and `user.json`. It's also possible to provide `client.json` and `user.json` with valid content and point this library to that directory.

### Contributing

This project welcomes contributions, including bug fixes and documentation enhancements. To contribute, please use the Issues Tracker to let us know what you would like to do. We'll respond, and go from there.
Expand Down