Skip to content

Changes

Page history
Create Labradoor authored by Timur Oberhuber's avatar Timur Oberhuber
Hide whitespace changes
Inline Side-by-side
Labradoor.md 0 → 100644
View page @ c9a1734e
## API
The CORE service is exposed to other services through a REST API. LabraDoor offers a generated client that can connect to this REST API. LabraDoor also takes care of the needed security protocols that are in place to connect to CORE.
All that is needed to configure the API client is to provide the following information in your `application.yml`:
```yaml
labracore:
url: http://localhost:8082 # The URL where CORE lives
apiKey: test-key # The name/key of your API key with CORE, usually a UUID
apiSecret: njkdabnjuasdkjbjbdaioasd # The secret of your API key with CORE
```
## Security
A couple security protocols are implemented and enabled by LabraDoor. These were added to a library because we found that we had to implement the same protocols multiple times over similar projects. The protocols are based on the fact that authentication is usually provided by an external service.
### TUD
TU Delft has a single authentication service (commonly referred to as an IdP, for Identity Provider) that is used by all TU Delft services to identify users.
For instance, when logging into Brightspace, the user is redirected to Gatekeeper, the TU Delft Identity Provider, and asked to login there.
LabraDoor implements the connection to any Gatekeeper-like service and gets the information about the user as granted by Gatekeeper out of the response from Gatekeeper.
### Testing
<b>WARNING: DO NOT USE THIS IN PRODUCTION EVER</b>
For testing purposes, LabraDoor also provides an in-memory implementation of an external IdP.
This means that, when testing a Spring application using LabraDoor, one can provide LabraDoor with a few users and simulate a login page through LabraDoor.
### Implementation
To implement and use the security protocols provided by LabraDoor, a couple classes/interfaces need to be extended/implemented and exposed to Spring by the Spring application using LabraDoor.
Additionally, some configurations are required to properly set things up and for in-memory, a custom login page needs to be served.
#### Configurations
The following configurations are required to be added to `application.yml` depending on your needs for your chosen identity provider:
```yml
# As explained in the CORE API sections:
labracore:
url: http://localhost:8082
apiKey: test
apiSecret: test
# General settings of the SSO Provider to use and login and logout path.
labrador:
sso:
type: in-memory # The SSO provider to use, either 'in-memory' or 'saml'
login-path: /login-custom # The logout page path, defaults to /logout
logout-path: /logout-custom # The login page path, defaults to /login
# Only use the following for in-memory.
mem:
saved-request-aware: true # Whether the login should redirect to the last attempted page
success-url: / # The URL that logins get redirected to if none is cached or saved-request-aware is turned off
# For the SAML security configurations, we refer to documentation here:
# https://github.com/ulisesbocchio/spring-boot-security-saml
# The following configuration is taken from our test setup for LabraDoor:
saml.sso.authentication-provider.force-principal-as-string: false
saml.sso.metadata-generator.entity-id: labracore.test
saml.sso.metadata-generator.entity-base-url: http://localhost:8082
saml.sso.key-manager.store-location: classpath:/security/testKeystore.jks
saml.sso.key-manager.default-key: 1
saml.sso.key-manager.store-pass: password
saml.sso.key-manager.key-passwords.1: password
saml.sso.extended-delegate.metadata-require-signature: false
saml.sso.extended-delegate.metadata-trust-check: true
saml.sso.extended-metadata.idp-discovery-enabled: false
saml.sso.idp.metadata-location: https://eipdev.ewi.tudelft.nl/saml/saml2/idp/metadata.php
saml.sso.context-provider.lb.scheme: http
saml.sso.context-provider.lb.server-name: localhost
saml.sso.context-provider.lb.server-port: 8082
saml.sso.context-provider.lb.include-server-port-in-request-url: false
```
#### Beans
The classes that need to be exposed are:
1. `LabradorSecurityConfigurerAdapter` as a configuration. This class configures the LabraDoor security protocols.
When extending this class, you can configure your own authorizations and security protocols on top of the Labradoor security configurations.
For instance, the following security configuration allows all requests on the `/bla` endpoint, but requires users to be authenticated on all other endpoints:
```java
@Configuration
public class CustomSecurityConfig extends LabradorSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
super.configure(http); // First, let LabraDoor configure your SSO security
http.authorizeRequests()
.antMatcher("/bla").permitAll()
.anyRequest().authenticated();
}
}
```
2. `LabradorUserHandler` as any bean. This class is used to update whatever user information that the implementing Spring application holds in their own database.
This update only happens after the user was successfully identified and authenticated by LabraDoor.
The following empty implementation provides no local user updating:
```java
@Service
public class CustomUserHandler extends LabradorUserHandler {
@Override
protected void handleUserLogin(Person person) {
// empty
}
}
```
3. `InMemoryUserProvider` as any bean if testing with the in-memory SSO provider.
This bean is used to provide a 'database' of login information when testing.
```java
@Service
public class CustomUserProvider extends InMemoryUserProvider {
public CustomUserProvider() {
super();
add("Student 1", 1, STUDENT); // Creates a new student user with username `student1`
add("Teacher 1", 2, TEACHER); // Creates a new teacher user with username `teacher1`
}
}
```
#### Login page for in-memory
Finally, when using the in-memory provider, currently we need to serve some login page that submits a username and password to the server. For this the implementing Spring application needs to serve a page on `/login`.
The provided HTML must contain a form that submits to `/perform-login` with a POST. The following HTML can accomplish this goal:
```html
<form method="POST" action="/perform-login">
<input type="username" name="username">
<input type="password" name="password">
</form>
```
\ No newline at end of file