Skip to content

Commit a87d7a4

Browse files
mrtsmrts
committed
Update README.md
Signed-off-by: Mart Sõmermaa <[email protected]>
1 parent 1ec25c3 commit a87d7a4

File tree

1 file changed

+154
-9
lines changed

1 file changed

+154
-9
lines changed

‎README.md‎

Lines changed: 154 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,21 @@
44

55
![European Regional Development Fund](https://github.com/e-gov/RIHA-Frontend/raw/master/logo/EU/EU.png)
66

7-
The Web eID authentication token validation library for Java allows validating
7+
The Web eID authentication token validation library for Java allows issuing challenge nonces and validating
88
Web eID JWT authentication tokens during authentication in web applications.
99

1010
# Quickstart
1111

12-
Complete the steps below to add strong authentication support to your web application back end.
12+
Complete the steps below to add strong authentication support to your web application back end. Instructions for the font end are available [here](https://github.com/web-eid/web-eid.js).
1313

14-
To run this quickstart you need a Java web application that uses Maven or Gradle to manage packages.
14+
A Java web application that uses Maven or Gradle to manage packages is needed for running this quickstart.
15+
Examples are for Maven, but they are straightforward to translate to Gradle.
1516

16-
See full example [here]().
17+
See full example [here](https://github.com/web-eid/web-eid-spring-boot-example).
1718

18-
## 1. Add the library to your Maven or Gradle project
19+
## 1. Add the library to your project
1920

20-
Add the following lines to Maven `pom.xml`:
21+
Add the following lines to Maven `pom.xml` to include the Web eID authentication token validation library in your project:
2122

2223
```xml
2324
<dependency>
@@ -36,12 +37,156 @@ Add the following lines to Maven `pom.xml`:
3637

3738
## 2. Add cache support
3839

39-
## 3. Add trusted certificate authorities
40+
The validation library needs a cache for storing issued authentication tokens. Any *javax.cache.Cache* JSR107 API compatible implementation is suitable, we use Hazelcast here.
41+
42+
Add the following lines to Maven `pom.xml`:
43+
44+
```xml
45+
<dependency>
46+
<groupId>javax.cache</groupId>
47+
<artifactId>cache-api</artifactId>
48+
<version>1.1.1</version>
49+
</dependency>
50+
<dependency>
51+
<groupId>com.hazelcast</groupId>
52+
<artifactId>hazelcast</artifactId>
53+
</dependency>
54+
```
55+
56+
Configure the cache as follows:
57+
58+
```java
59+
import javax.cache.Cache;
60+
import javax.cache.CacheManager;
61+
import javax.cache.Caching;
62+
import javax.cache.configuration.CompleteConfiguration;
63+
import javax.cache.configuration.MutableConfiguration;
64+
65+
...
66+
private Cache<String, LocalDateTime> nonceCache() {
67+
CacheManager cacheManager = Caching.getCachingProvider().getCacheManager();
68+
Cache<String, LocalDateTime> cache = cacheManager.getCache("nonceCache");
69+
70+
if (cache == null) {
71+
CompleteConfiguration<String, LocalDateTime> cacheConfig =
72+
new MutableConfiguration<String, LocalDateTime>().setTypes(String.class, LocalDateTime.class);
73+
cache = cacheManager.createCache(CACHE_NAME, cacheConfig);
74+
}
75+
return cache;
76+
}
77+
...
78+
```
79+
80+
## 3. Configure the nonce generator
81+
82+
The validation library needs to generate authentication challenge nonces and store them in the cache when issuing tokens.
83+
The nonce generator will be used in the REST endpoint that issues challenges; it is thread-safe and should be scoped as a singleton.
4084

41-
## 4. Add REST endpoints for the authentication requests
85+
Configure the nonce generator as follows:
4286

43-
## 5. Add authentication token validation
87+
```java
88+
import org.webeid.security.nonce.NonceGenerator;
89+
import org.webeid.security.nonce.NonceGeneratorBuilder;
90+
91+
...
92+
public NonceGenerator nonceGenerator() {
93+
return new NonceGeneratorBuilder()
94+
.withNonceCache(nonceCache())
95+
.build();
96+
}
97+
...
98+
```
4499

100+
## 4. Add trusted certificate authority certificates
101+
102+
You must explicitly specify which certificate authorities (CAs) are trusted to issue the eID certificates for authentication.
103+
CA certificates can be loaded from either the truststore file or any stream source.
104+
We use the [`CertificateLoader`](https://github.com/web-eid/web-eid-authtoken-validation-java/blob/main/src/test/java/org/webeid/security/testutil/CertificateLoader.java) helper class from [`testutil`](https://github.com/web-eid/web-eid-authtoken-validation-java/tree/main/src/test/java/org/webeid/security/testutil) to load CA certificates from resouces here, but consider using [the truststore file](https://github.com/web-eid/web-eid-spring-boot-example/blob/main/src/main/java/org/webeid/example/config/ValidationConfiguration.java#L104-L122) instead.
105+
106+
First, copy the trusted certificates, for example `ESTEID-SK_2015.cer` and `ESTEID2018.cer`, to `resources/cacerts/`, then load the certificates as follows:
107+
108+
```java
109+
import java.security.cert.X509Certificate;
110+
111+
...
112+
private X509Certificate[] trustedCertificateAuthorities() {
113+
return CertificateLoader.loadCertificatesFromResources("cacerts/ESTEID-SK_2015.cer",
114+
"cacerts/ESTEID2018.cer");
115+
}
116+
...
117+
```
118+
119+
## 5. Configure the authentication token validator
120+
121+
Once the prerequisites have been met, the authentication token validator itself can be configured.
122+
The minimum parameters are the website origin (the URL where the application is served from), nonce cache and trusted certificate authorities.
123+
The authentication token validator will be used in the login processing component of your web application authentication framework;
124+
it is thread-safe and should be scoped as a singleton.
125+
126+
```java
127+
import org.webeid.security.validator.AuthTokenValidator;
128+
import org.webeid.security.validator.AuthTokenValidatorBuilder;
129+
130+
...
131+
public AuthTokenValidator validator() {
132+
return new AuthTokenValidatorBuilder()
133+
.withSiteOrigin("https://example.org")
134+
.withNonceCache(nonceCache())
135+
.withTrustedCertificateAuthorities(trustedCertificateAuthorities())
136+
.build();
137+
}
138+
...
139+
```
140+
141+
## 6. Add a REST endpoint for issuing challenge nonces
142+
143+
A REST endpoint that issues challenge nonces is required for authentication. The endpoint must support `GET` requests.
144+
145+
In the following example, we are using the [Spring RESTful Web Services framework](https://spring.io/guides/gs/rest-service/) to implement the endpoint, see also full implementation [here](https://github.com/web-eid/web-eid-spring-boot-example/blob/main/src/main/java/org/webeid/example/web/rest/ChallengeController.java).
146+
147+
```java
148+
import org.springframework.web.bind.annotation.GetMapping;
149+
import org.springframework.web.bind.annotation.RequestMapping;
150+
import org.springframework.web.bind.annotation.RestController;
151+
...
152+
153+
@RestController
154+
@RequestMapping("auth")
155+
public class ChallengeController {
156+
157+
@Autowired // for brevity
158+
private NonceGenerator nonceGenerator;
159+
160+
@GetMapping("challenge")
161+
public ChallengeDTO challenge() {
162+
final ChallengeDTO challenge = new ChallengeDTO(); // a simple DTO with a single 'challenge' field
163+
challenge.setNonce(nonceGenerator.generateAndStoreNonce());
164+
return challenge;
165+
}
166+
}
167+
```
168+
169+
Also, see general guidelines for implementing secure authentication services [here](https://github.com/SK-EID/smart-id-documentation/wiki/Secure-Implementation-Guide).
170+
171+
## 7. Implement authentication
172+
173+
Authentication consists of calling the `validate()` method of the authentication token validator. The internal implementation of the validation process is described in more detail below and in the [Web eID system architecture document](https://github.com/web-eid/web-eid-system-architecture-doc#authentication-1).
174+
175+
When using [Spring Security](https://spring.io/guides/topicals/spring-security-architecture) with standard cookie-based authentication,
176+
177+
- implement a custom authentication provider that uses the authentication token validator for authentication as shown [here](https://github.com/web-eid/web-eid-spring-boot-example/blob/main/src/main/java/org/webeid/example/security/AuthTokenDTOAuthenticationProvider.java),
178+
- implement an AJAX authentication processing filter that extracts the authentication token and passes it to the authentication manager as shown [here](https://github.com/web-eid/web-eid-spring-boot-example/blob/main/src/main/java/org/webeid/example/security/WebEidAjaxLoginProcessingFilter.java),
179+
- configure the authentication provider and authentication processing filter in the application configuration as shown [here](https://github.com/web-eid/web-eid-spring-boot-example/blob/main/src/main/java/org/webeid/example/config/ApplicationConfiguration.java).
180+
181+
The gist of the validation is [in the `authenticate()` method](https://github.com/web-eid/web-eid-spring-boot-example/blob/main/src/main/java/org/webeid/example/security/AuthTokenDTOAuthenticationProvider.java#L70-L72) of the authentication provider:
182+
183+
```java
184+
try {
185+
X509Certificate userCertificate = tokenValidator.validate(token);
186+
return new PreAuthenticatedAuthenticationToken(getPrincipalFromCertificate(userCertificate), null, authorities);
187+
} catch (...) {
188+
...
189+
```
45190

46191
# Introduction
47192

0 commit comments

Comments
 (0)