secure-token-service 
This an implementation of the secure token service as specified in the token exchange working draft https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-08.
This module does not implement oAuth2 authentication flows. The module focuses on the oAuth2 token production and management process. Most oAuth2 Server implement both authentication and token management.
Authentication is the process of identifying and legitimating the subject of authorization. Means the subject on behalf of which the oAuth token is produced. An authentication server does following:
- Authenticate the user
- Ask the token manager to produce the corresponding token
- Ask the token manager to invalidate the token
Token management solely focuses on managing oAuth tokens and exchanging them like specified in the token exchange working draft (https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-08)
STS usage example
Overview example to show the usage of the STS components.
Development
Dependencies
You can easily use this libraries in your spring boot app via maven dependency:
<dependency>
<groupId>de.adorsys.sts</groupId>
<artifactId>sts-spring</artifactId>
<version>${version}</version>
</dependency>
Annotations
You can easily use features by adding following annotations to your spring @Configuration class:
| Annotation | Description |
|---|---|
@EnablePOP |
Enables the Proof-Of-Possession endpoint |
@EnableResourceServerInitialization |
Enables the initialization of the resource server configuration read from the spring properties |
@EnableEncryption |
Enables the encryption service bean |
@EnableDecryption |
Enables the decryption service bean |
@EnableSecretDecryption |
Enables the secret claim decryption service bean |
@EnableKeyRotation |
Enables the key-rotation for the key-management |
@EnableServerInfo |
Enables the server-info endpoint |
@EnableTokenAuthentication |
Enables token-authentication-service bean |
@EnableSecurityContextSecretProviding |
Enables the security-context secret provider bean |
@EnableJacksonObjectMapping |
Enables jackson object mapper SPI bean |
@EnableSecretServer |
Enables the secret-server functionality in your application |
@EnableSecretServerClient |
Enables the secret-server client bean |
Features
Proof-Of-Possession
Provides the public keys for encryption and signature check via the /pop endpoint.
Depends on:
- Key-Management
Resource-Server-Configuration
Resource servers are used for encryption to manage the jwks-endpoints.
Configuration
You can configure the array of resources servers in your application.yml:
sts:
resource-server-management:
resource-retriever:
http-connect-timeout: <http connect timeout for JWK set retrieval in milliseconds, default: 250>
http-read-timeout: <http read timeout for JWK set retrieval in milliseconds, default: 250>
http-size-limit: <http entity size limit for JWK set retrieval in bytes, default: 50 * 1024>
# cache settings
cache:
enabled: <(boolean, optional, default: false) defines if the secret-server client uses a internal cache for the secrets>
maximum-size: <(integer, optional, default: 1000) defines the maximum cache size>
expire-after-access: <(integer, optional, default: 10) defines the expiration time in minutes>
resource-servers:
- audience: <(text) the name of your resource server / the audience key>
jwks-url: <(text, url) the jwks-url of the resource-server, like "http://localhost:8888/pop">
You have to decide:
- Which kind of
ResourceServerRepositoryyou will provide as Bean.
Encryption
Provides the EncryptionService which can be used to encrypt sensitive data. The resource servers are used to get the public keys for encryption from their /pop endpoint.
The encrypted ciphertext is created by Json Web Encryption.
Depends on:
- Resource-Server-Configuration
Decryption
Provides the DecryptionService which can be used to decrypt JWE-encrypted ciphertexts. The decryption-key has to be stored in local key-management, otherwise the decryption will fail.
Depends on:
- Key-Management
Secret decryption
Usage of annotation @EnableSecretDecryption provides the SecretDecryptionService instance which is used to get the decrypted secret.
The encrypted secret is provided by a bean implementing the SecretProvider interface.
Secret provider
Provided by the @EnableSecurityContextSecretProviding annotation a bean instance of SecurityContextSecretProvider class is provided.
This implementation reads the secret claims from the JWT token (stored in spring's security context).
Configuration
The SecurityContextSecretProvider needs the following configuration to work properly:
sts:
secret-claim-property-key: <the claim property key used to read the right claim from the claims-set, mandatory>
audience-name: <the application's audience name. Is used to read the right entry from the secrets map, mandatory)>
Key-Management
Manages key-pairs for encryption/decryption and key-pairs to create or check signatures. Additionally secret-keys will be managed.
You have to decide:
- Which kind of
KeyStoreRepositoryyou will provide as Bean.
Key-rotation
You may enable the key-rotation feature by adding the @EnableKeyRotation annotation to your spring boot @Configuration class. Additionally you have to configure following properties:
sts:
keymanagement:
rotation:
check-interval: <(long) the time interval in milliseconds the key-rotation will check the keys, default: 60000>
enc-key-pairs:
min-keys: <(integer) minimal count of stored encryption key-pairs, default: 5>
enabled: <(boolean) defines if the key-rotation is enabled for encryption key-pairs, default: false>
sign-key-pairs:
min-keys: <(integer) minimal count of stored signature key-pairs, default: 5>
enabled: <(boolean) defines if the key-rotation is enabled for signature key-pairs, default: false>
secret-keys:
min-keys: <(integer) minimal count of stored secret keys, default: 5>
enabled: <(boolean) defines if the key-rotation is enabled for secret-keys, default: false>
Key-generation
You have to configure the properties of the key-generation in your application.yml:
sts:
keymanagement:
keystore:
password: <(text) the key-store encryption password>
type: <(text) the key-store type, like "UBER">
name: <(text) the key-store name>
alias-prefix: <(text) the prefix of your generated key-aliases in this key-store>
keys:
enc-key-pairs:
initial-count: <(integer) initial count of generated encryption key-pairs>
algo: <(text) the key-pair algorithm, like "RSA">
sig-algo: <(text) the key-pair signature algorithm, like "SHA256withRSA">
size: <(integer) the key size, like 2048, 4096, ...>
name: <(text) the string-representation of your key-pair>
validity-interval: <(long) the interval in milliseconds the keys can be used for encryption>
legacy-interval: <(long) the interval in milliseconds the keys can be used for decryption>
sign-key-pairs:
initial-count: <(integer) initial count of generated signature key-pairs>
algo: <(text) the key-pair algorithm, like "RSA">
sig-algo: <(text) the key-pair signature algorithm, like "SHA256withRSA">
size: <(integer) the key size, like 2048, 4096, ...>
name: <(text) the string-representation of your key-pair>
validity-interval: <(long) the interval in milliseconds the keys can be used for signature creation>
legacy-interval: <(long) the interval in milliseconds the keys can be used for signature check>
secret-keys:
initial-count: <(integer) initial count of generated secret-keys>
algo: <(text) the key algorithm, like "AES">
size: <(integer) the key size, like 128, 256, ...>
validity-interval: <(long) the interval in milliseconds the keys can be used for encryption>
legacy-interval: <(long) the interval in milliseconds the keys can be used for decryption>
Token authentication
Provides the TokenAuthenticationService Bean which extracts the org.springframework.security.core.Authentication from the Bearer token. The token has to be valid, otherwise this operation will return null.
The validation of the token will also be handled in this operation. Only authentication-servers provided by the auth-servers configuration will be accepted.
It's recommended to use this service in a request-filter (like the JWTAuthenticationFilter in this project).
Depends on:
- Auth-Servers configuration
Configuration
You have to configure the array of authservers in your application.yml, otherwise no Bearer-token will be accepted:
sts:
authservers:
- name: <(text) custom name of your identity provider>
iss-url: <(text, url) the issuer-url of your identity-provider's token, like "https://your-idp-hostname/auth/realms/your-realm">
jwks-url: <(text, url) the jwks-endpoint url of your identity provider, like "https://your-idp-hostname/auth/realms/your-realm/protocol/openid-connect/certs">
refresh-interval-seconds: <(integer) --- unused >
Secret-server and its client
Provides server and client functionality to store secrets in a separate database. Only registered clients are able to get the secrets via a token-exchange endpoint. The delivered token has to be valid and the client has to be known as a resource server, its pop-endpoint have to be accessible for the secret-server.
Server side
You can provide the secret-server functionality while using the @EnableSecretServer annotation in your spring configuration.
This annotation enables the token-exchange endpoint with the needed services in the background. It needs a
SecretRepository instance which is used to persist the secrets. For example you can store your secrets in a RDBMS
like postgres or mysql if you use the additional annotation @EnableJpaPersistence in your configuration.
Alternatively you may deploy a ready-to-run secret-server provided by the sts-secret-server submodule and which
you can run via docker: the image name is adorsys/sts-secret-server and can be found on
docker-hub.
Configuration
sts:
secret-server:
secret-length: <(integer, optional) secret length in bits (not the length of the base64 encoded string!) default: 256>
endpoint: <(url as string, optional) the endpoint path of the secret-server's token-exchange endpoint. default: /secret-server/token-exchange >
encryption:
enabled: <(boolean, optional) defines if the secret encryption is enabled. default: false >
algorithm: <(string, optional) defines the encryption algorithm. default: A256GCMKW >
encryption-method: <(string, optional) defines the encryption method. default: A256GCM >
key: <(string, optional) defines the encryption key in json format. default: none >
# You need to configure the same IDP instance(s) and its pop-entpoint(s) as authserver(s) as the clients are using to authenticate.
# Here is an example:
authservers:
- name: "local keycloak"
iss-url : "http://localhost:8080/auth/realms/moped"
jwks-url: "http://localhost:8080/auth/realms/moped/protocol/openid-connect/certs"
# You need to configure the clients as resource-servers with its pop-endpoints:
# Here is an example:
resource-server-management:
resource-servers:
- audience: "moped-client"
jwks-url: "http://my-moped-application:8080/pop"
For further information consider the standalone secret-server documentation.
Client side
On client-side you can communicate with a secret-server via the SecretServerClient bean. The interface is quite
simple: there is a String getSecret(String token) method which delivers the decrypted and BASE64 encoded secret for
the specified. Quite easier is the usage of the SecretServerClientSecretProvider bean. It provides the secret without
the need to pass the token as parameter. Both beans are injectable after the usage of @EnableSecretServerClient
annotation in your spring configuration.
Configuration
sts:
secret-server-client:
audience: <(string, mandatory, no default) The audience name of your application which is used to communicate with the secret-server>
secret-server-uri: <(url as string, mandatory, no default) The url of the secret-server's token-exchange endpoint (Example: http://your-secret-server:8080/token/token-exchange)>
# cache settings:
cache:
enabled: <(boolean, optional, default: false) defines if the secret-server client uses a internal cache for the secrets>
maximum-size: <(integer, optional, default: 1000) defines the maximum cache size>
expire-after-access: <(integer, optional, default: 10) defines the expiration time in minutes>
Standalone secret-server
You can find a standalone, fully-configurable secret-server in submodule sts-secret-server. Please consider
the standalone secret-server documentation
for further information.
Build this solution
Within docker
docker-compose --file build.docker-compose.yml down --remove-orphans && docker-compose --file build.docker-compose.yml up --build
Run example application
with postgres database
docker-compose --file postgres.docker-compose.yml down --remove-orphans && docker-compose --file postgres.docker-compose.yml up --build
with mysql 8 database
docker-compose --file mysql8.docker-compose.yml down --remove-orphans && docker-compose --file mysql8.docker-compose.yml up --build
with mysql 5 database
docker-compose --file mysql5.docker-compose.yml down --remove-orphans && docker-compose --file mysql5.docker-compose.yml up --build
with mongo database
docker-compose --file mongo.docker-compose.yml down --remove-orphans && docker-compose --file mongo.docker-compose.yml up --build
without building locally and pulling images from Docker-Hub
docker-compose --file hub.docker-compose.yml down --remove-orphans && docker-compose --file hub.docker-compose.yml pull && docker-compose --file hub.docker-compose.yml up
| Container | URL |
|---|---|
| keycloak | http://localhost:8080 |
| STS | http://localhost:8888 |
| Service Component | http://localhost:8887 |
| Angular client | http://localhost:8090 |