zalando-stups / scala-typesafe-config-tokens

A Scala typesafe config wrapper over the Tokens library that is used for STUPS authentication

GitHub

Scala-Typesafe Config STUPS AccessTokens Support Build Status

Is a small wrapper around Tokens with autoconfiguration support in Scala applications using Typesafe Config. The intention is to make it very easy to get access token details, especially when using OAuth2 via stups.

The project has minimal dependencies so it can easily be integrated into various Scala projects.

Build

sbt compile

Install

Add the following to your build.sbt when using SBT.

libraryDependencies += "org.zalando" %% "scala-typesafe-config-tokens" % "0.2.0"

You will also need to add the following repository

resolvers += Resolver.jcenterRepo

Currently built for Scala 2.11 and Scala 2.12

Configuration

Place the following in application.conf in your resources folder (create it if doesn't exist)

tokens {
  accessTokenUri="http://localhost:9191/access_token?realm=whatever"
  clientCredentialsDirectory="/somepath/credentials"

  tokenConfigurationList = [{
    tokenId=firstService
    scopes=[
      "refole:read",
      "refole:write",
      "refole:all"
    ]
  },{
    tokenId=secondService
    scopes=["singleScope:all"]
  }]
}

This is a proper typesafe config, so you can for example use environment variable substitutions, i.e.

accessTokenUri="http://localhost:9191/access_token?realm=whatever"
accessTokenUri=${?ZALANDO_STUPS_TOKENS_ACCESS_TOKEN_URI}

Below is a table of the configuration options

.conf Configuration Key AccessTokenBuilder Method Example Config Default
accessTokenUri Tokens.createAccessTokensWithUri "http://localhost:9191/access_token?realm=whatever" N/A
clientCredentials AccessTokensBuilder.usingClientCredentialsProvider ${user.dir}"/somepath/credentials/client.json" N/A
userCredentials AccessTokensBuilder.usingUserCredentialsProvider ${user.dir}"/somepath/credentials/user.json" N/A
credentialsDirectory N/A (convenience method) ${user.dir}"/somepath/credentials N/A
userDirectoryCredentialFile N/A (only used by credentialsDirectory) "user.json" "user.json"
clientDirectoryCredentialFile N/A (only used by credentialsDirectory) "client.json" "client.json"
tokenConfigurationList See TokenConfigurationList Object Array of TokenConfigurationList Object See TokenConfigurationList Object
httpProviderConfiguration AccessTokensBuilder.usingHttpProviderFactory See HttpProviderConfiguration Object See HttpProviderConfiguration Object
connectionRequestTimeout AccessTokensBuilder.connectionRequestTimeout "1 second" Provided by Tokens
connectTimeout AccessTokensBuilder.connectTimeout "1 second" Provided by Tokens
schedulingPeriod AccessTokensBuilder.schedulingTimeUnit && AccessTokensBuilder.schedulingPeriod "1 hour" Provided by Tokens
metricsListener AccessTokensBuilder.metricsListener some.package.MetricsListenerImplementation Provided by Tokens
existingExecutorService AccessTokensBuilder.existingExecutorService some.package.ScheduledExecutorServiceImplementation Provided by Tokens
tokenInfoUri AccessTokensBuilder.tokenInfoUri "http://localhost:9191/tokenInfoUri" Provided by Tokens
tokenRefresherMcbConfig AccessTokensBuilder.tokenRefresherMcbConfig See MCBConfiguration Object See MCBConfiguration Object
tokenVerifierMcbConfig AccessTokensBuilder.tokenVerifierMcbConfig See MCBConfiguration Object See MCBConfiguration Object
tokenVerifierSchedulingPeriod AccessTokensBuilder.tokenVerifierSchedulingTimeUnit && AccessTokensBuilder.tokenVerifierSchedulingPeriod "1 minute" Provided by Tokens
refreshPercentLeft AccessTokensBuilder.refreshPercentLeft 30 Provided by Tokens
warnPercentLeft AccessTokensBuilder.warnPercentLeft 30 Provided by Tokens

TokenConfigurationList Object

.conf Configuration Key AccessTokenBuilder Method Example Config Default
tokenId manageToken firstService N/A
scopes addScopes ["singleScope:all"] N/A

HttpProviderConfiguration Object

.conf Configuration Key AccessTokenBuilder Method Example Config Default
clientCredentials ClosableHttpProviderFactory.create ${user.dir}"/somepath/credentials/client.json" N/A
userCredentials ClosableHttpProviderFactory.create ${user.dir}"/somepath/credentials/user.json" N/A
accessTokenUri ClosableHttpProviderFactory.create "http://localhost:9191/access_token?realm=whatever" N/A
httpConfig new HttpConfig See HttpConfiguration Object Provided by Tokens

HttpConfiguration Object

.conf Configuration Key AccessTokenBuilder Method Example Config Default
socketTimeout HttpConfig.setSocketTimeout "1 second" Provided by Tokens
setConnectTimeout HttpConfig.setConnectTimeout "1 second" Provided by Tokens
setConnectionRequestTimeout HttpConfig.setConnectionRequestTimeout "1 second" Provided by Tokens
setStaleConnectionCheckEnabled HttpConfig.setStaleConnectionCheckEnabled false Provided by Tokens

MCBConfiguration Object

.conf Configuration Key AccessTokenBuilder Method Example Config Default
errorThreshold MCBConfig.Builder.withErrorThreshold 10 Provided by Tokens
timeout MCBConfig.Builder.withTimeUnit && MCBConfig.Builder.withTimeout "1 second" Provided by Tokens
maxMulti MCBConfig.Builder.maxMulti 20 Provided by Tokens
name MCBConfig.Builder.withName "my-breaker" Provided by Tokens

Usage

With a configuration in place, you can then need to create an instance of org.zalando.stups.tokens.AccessTokenFactory. By default the AccessTokenFactory will load the config using ConfigFactory.load() however you can provide your own instance of config.

For typical usage you would do something like this

import org.zalando.stups.tokens.AccessTokenFactory

object AccessTokensInstance extends AccessTokenFactory()

// And then to get your access tokens you would do

AccessTokensInstance.accessTokens

Contributing

Please make sure that you format the code using scalafmt. You can do this by running scalafmt in sbt before committing. See scalafmt for more info.

License

Copyright © 2016 Zalando SE

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.