Windermere is an open source SCIM server for the EGIL profile of SS12000:2018.
It is built to make it easy to quickly get started with EGIL as a service provider.
Before getting started you need a few things:
- A host with the Go compiler installed (v1.16 or later)
- URL and public keys to the authentication federation
- A certificate to use in PEM format
- A configuration file for Windermere
You can find the URL and public keys for Moa (previously Kontosynk) at Kontosynk
A certificate can be generated with OpenSSL, for instance:
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes
Put the certificates and keys file in a new directory, and create a Windermere config file, for instance named config.yaml.
You can start with the following example:
# Configuration of the authentication federation and metadata
MetadataURL: https://fed.skolfederation.se/trial/md/kontosynk.jws
JWKSPath: /home/joe/windermere/jwks.trial
MetadataCachePath: /home/joe/windermere/metadata-cache.json
# Information to be published about this server in the
# federation metadata.
MetadataEntityID: https://egil.serviceprovider.com
MetadataBaseURI: https://egil.serviceprovider.com
MetadataOrganization: Service Provider Ltd.
MetadataOrganizationID: SE1234567890
# HTTP server settings
Cert: /home/joe/windermere/cert.pem
Key: /home/joe/windermere/key.pem
ListenAddress: :443
# Rate limiting
EnableLimiting: true
LimitRequestsPerSecond: 20
LimitBurst: 20
# Storage backend
StorageType: sqlite
StorageSource: storage.db
Replace path names, and information about your organization as appropriate.
The StorageType specifies which SQL driver to use. Currently included drivers are:
- sqlite (SQLite)
- sqlserver (Microsoft SQL Server)
- mysql (MySQL, MariaDB, Percona Server, Google CloudSQL or Sphinx)
Depending on which driver is used, the StorageSource has a different format for specifying access to the database. For SQLite you can simply specify a filename.
Example for SQL Server:
sqlserver://<user>:<passwd>@<host>?database=<database>
Example for MySQL/MariaDB:
<user>:<password>@<host>/<database>?multiStatements=true
multiStatements=true
is currently needed for this driver
(other drivers allow this by default).
To build Windermere, go into the directory cmd/windermere
and run go build
,
this should give you an executable named windermere
in the same directory.
Go to the directory where you have the certificates and windermere configuration and run windermere, for instance:
$ windermere config.yaml
Specify the full path to the binary unless you've added it to your $PATH
.
Before clients can connect to the server you need to upload your metadata to the federation operator (Moa). Windermere can generate your metadata for you, but you need to activate the administration HTTP interface.
You can activate the administration interface by specifying the AdminListenAddress
parameter in the configuration file, for instance:
AdminListenAddress: 127.0.0.1:4443
Currently the administration interface only implements two end-points:
- Metadata (
/metadata
) - Debug tools (
/debug/pprof
)
You can download the metadata with your web browser, or for instance with curl:
curl -k https://127.0.0.1:4443/metadata
The administration interface uses the same certificate as the EGIL SCIM server
(hence the need for -k
above in case the certificate is self signed).
If you want to log all (authenticated) requests to the server you can specify a path to an access log file, for instance:
AccessLogPath: /home/windermere/access.log
The access log will show who made the request (ip and federation entity id), what URL was requested, result code and execution time for each request.
If you wish to allow Skolsynk to connect you need to configure a separate listening address, for instance:
SkolsynkListenAddress: :4430
If you wish you can configure which HTTP header to use for authentication key:
SkolsynkAuthHeader: X-API-Key
The default, if you don't configure this, is X-API-Key.
Then you also need to create API keys for your clients:
SkolsynkClients:
- name: skolsynkGoogle
key: HfACARee4G3qrtBx
- name: skolsynkMicrosoft
key: fjEGgDnDBAaBh4rN
What you specify after name
will be used as the tenant name in the database
(similar to entity ID if you're using Federated TLS (Moa)). You should generate
the key
yourself and hand it over to Skolsynk in a secure way.
By default, the same certificate will be used for the HTTPS traffic for Skolsynk, but if you wish you can specify a separate certificate also:
SkolsynkCert: /home/windermere/skolsynkcert.pem
SkolsynkKey: /home/windermere/skolsynkkey.pem
You can choose to run only Federated TLS (Moa), only Skolsynk, or both at the same
time (by configuring ListenAddress
and/or SkolsynkListenAddress
).