Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/libregraph/lico
LibreGraph Connect implements an OpenID provider (OP) with integrated web login and consent forms.
https://github.com/libregraph/lico
hacktoberfest ldap-authentication openid-connect openid-provider
Last synced: 3 months ago
JSON representation
LibreGraph Connect implements an OpenID provider (OP) with integrated web login and consent forms.
- Host: GitHub
- URL: https://github.com/libregraph/lico
- Owner: libregraph
- License: apache-2.0
- Created: 2021-06-15T10:28:50.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-07-16T12:03:54.000Z (4 months ago)
- Last Synced: 2024-07-16T14:47:41.530Z (4 months ago)
- Topics: hacktoberfest, ldap-authentication, openid-connect, openid-provider
- Language: Go
- Homepage:
- Size: 14.9 MB
- Stars: 24
- Watchers: 3
- Forks: 5
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-starred - libregraph/lico - LibreGraph Connect implements an OpenID provider (OP) with integrated web login and consent forms. (hacktoberfest)
README
# LibreGraph Connect
LibreGraph Connect implements an [OpenID provider](http://openid.net/specs/openid-connect-core-1_0.html)
(OP) with integrated web login and consent forms.
[](https://goreportcard.com/report/github.com/libregraph/lico)
LibreGraph Connect has it origin in Kopano Konnect and is meant as its vendor
agnostic successor.
## Technologies
- Go
- React
## Standards supported by Lico
Lico provides services based on open standards. To get you an idea what
Lico can do and how you could use it, this section lists the
[OpenID Connect](https://openid.net/connect/) standards which are implemented.
- https://openid.net/specs/openid-connect-core-1_0.html
- https://openid.net/specs/openid-connect-discovery-1_0.html
- https://openid.net/specs/openid-connect-frontchannel-1_0.html
- https://openid.net/specs/openid-connect-session-1_0.html
- https://openid.net/specs/openid-connect-registration-1_0.html
Furthermore the following extensions/base specifications extend, define and
combine the implementation details.
- https://tools.ietf.org/html/rfc6749
- https://tools.ietf.org/html/rfc7517
- https://tools.ietf.org/html/rfc7519
- https://tools.ietf.org/html/rfc7636
- https://tools.ietf.org/html/rfc7693
- https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html
- https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html
- https://www.iana.org/assignments/jose/jose.xhtml
- https://nacl.cr.yp.to/secretbox.html
## Build dependencies
Make sure you have Go 1.18 or later installed. This project uses Go Modules.
Lico also includes a modern web app which requires a couple of additional
build dependencies which are furthermore also assumed to be in your $PATH.
- yarn - [Yarn](https://yarnpkg.com)
- convert, identify - [Imagemagick](https://www.imagemagick.org)
- scour - [Scour](https://github.com/scour-project/scour)
To build Lico, a `Makefile` is provided, which requires [make](https://www.gnu.org/software/make/manual/make.html).
When building, third party dependencies will tried to be fetched from the Internet
if not there already.
## Building from source
```
git clone lico
cd lico
make
```
### Optional build dependencies
Some optional build dependencies are required for linting and continuous
integration. Those tools are mostly used by make to perform various tasks and
are expected to be found in your $PATH.
- golangci-lint - [golangci-lint](https://github.com/golangci/golangci-lint)
- go2xunit - [go2xunit](https://github.com/tebeka/go2xunit)
- gocov - [gocov](https://github.com/axw/gocov)
- gocov-xml - [gocov-xml](https://github.com/AlekSi/gocov-xml)
- gocovmerge - [gocovmerge](https://github.com/wadey/gocovmerge)
### Build with Docker
```
docker build -t licod-builder -f Dockerfile.build .
docker run -it --rm -u $(id -u):$(id -g) -v $(pwd):/build licod-builder
```
## Running Lico
Lico can provide user login based on available backends.
All backends require certain general parameters to be present. Create a RSA
key-pair file with `openssl genpkey -algorithm RSA -out private-key.pem -pkeyopt rsa_keygen_bits:4096`
and provide the key file with the `--signing-private-key` parameter. Lico can
load PEM encoded PKCS#1 and PKCS#8 key files and JSON Web Keys from `.json` files
If you skip this, Lico will create a random non-persistent RSA key on startup.
To encrypt certain values, Lico needs a secure encryption key. Create a
suitable key of 32 bytes with `openssl rand -out encryption.key 32` and provide
the full path to that file via the `--encryption-secret` parameter. If you skip
this, Lico will generate a random key on startup.
To run a functional OpenID Connect provider, an issuer identifier is required.
The `iss` is a full qualified https:// URI pointing to the web server which
serves the requests to Lico (example: https://example.com). Provide the
Issuer Identifier with the `--iss` parametter when starting Lico.
Furthermore to allow clients to utilize the Lico services, clients need to
be known/registered. For now Lico uses a static configuration file which
allows clients and their allowed urls to be registered. See the the example at
`identifier-registration.yaml.in`. Copy and modify that file to include all
the clients which should be able to use OpenID Connect and/or OAuth2 and start
Lico with the `--identifier-registration-conf` parameter pointing to that
file. Without any explicitly registered clients, Lico will only accept clients
which redirect to an URI which starts with the value provided with the `--iss`
parameter.
### Lico cryptography and validation
A tool can be used to create keys for Lico and also to validate tokens to
ensure correct operation is [Step CLI](https://github.com/smallstep/cli). This
helps since OpenSSL is not able to create or validate all of the different key
formats, ciphers and curves which are supported by Lico.
Here are some examples relevant for Lico.
```
step crypto keypair 1-rsa.pub 1-rsa.pem \
--kty RSA --size 4096 --no-password --insecure
```
```
step crypto keypair 1-ecdsa-p-256.pub 1-ecdsa-p-256.pem \
--kty EC --curve P-256 --no-password --insecure
```
```
step crypto jwk create 1-eddsa-ed25519.pub.json 1-eddsa-ed25519.key.json \
-kty OKP --crv Ed25519 --no-password --insecure
```
```
echo $TOKEN_VALUE | step crypto jwt verify --iss $ISS \
--aud playground-trusted.js --jwks $ISS/konnect/v1/jwks.json
```
### URL endpoints
Take a look at `Caddyfile.example` on the URL endpoints provided by Lico and
how to expose them through a TLS proxy.
The base URL of the frontend proxy is what will become the value of the `--iss`
parameter when starting up Lico. OIDC requires the Issuer Identifier to be
secure (https:// required).
### LibreGraph backend
Generic backend support is available through the LibreGraph API. Any service can
provide the required endpoints and Lico connects to them.
```
export LIBREGRAPH_URI=http://your-backend.local:5050
bin/licod serve --listen=127.0.0.1:8777 \
--iss=https://mylico.local \
libregraph
```
### LDAP backend
This assumes that Lico can directly connect to an LDAP server via TCP.
```
export LDAP_URI=ldap://myldap.local:389
export LDAP_BINDDN="cn=admin,dc=example,dc=local"
export LDAP_BINDPW="its-a-secret"
export LDAP_BASEDN="dc=example,dc=local"
export LDAP_SCOPE=sub
export LDAP_LOGIN_ATTRIBUTE=uid
export LDAP_EMAIL_ATTRIBUTE=mail
export LDAP_NAME_ATTRIBUTE=cn
export LDAP_UUID_ATTRIBUTE=uidNumber
export LDAP_UUID_ATTRIBUTE_TYPE=text
export LDAP_FILTER="(objectClass=organizationalPerson)"
bin/licod serve --listen=127.0.0.1:8777 \
--iss=https://mylico.local \
ldap
```
### Build Lico Docker image
This project includes a `Dockerfile` which can be used to build a Docker
container from the locally build version. Similarly the `Dockerfile.release`
builds the Docker image locally from the latest release download.
```
docker build -t licod .
```
```
docker build -f Dockerfile.release -t licod .
```
## Run unit tests
```
make test
```
## Development
As Lico includes a web application (identifier), a `Caddyfile.dev` file is
provided which exposes the identifier's web application directly via a
webpack dev server.
### Debugging
Lico is built stripped and without debug symbols by default. To build for
debugging, compile with additional environment variables which override/reset
build optimization like this
```
LDFLAGS="" GCFLAGS="all=-N -l" ASMFLAGS="" make cmd/licod
```
The resulting binary is not stripped and sutiable to be debugged with [Delve](https://github.com/go-delve/delve).
To connect Delve to a running Lico binary you can use the `make dlv` command.
Control its behavior via `DLV_*` environment variables. See the `Makefile` source
for details.
```
DLV_ARGS= make dlv
```
#### Remote debugging
To use remote debugging, pass additional args like this.
```
DLV_ARGS=--listen=:2345 make dlv
```
## Usage survey
By default, any running licod regularly transmits survey data to a Kopano
user survey service at https://stats.kopano.io . To disable participation, set
the environment variable `KOPANO_SURVEYCLIENT_AUTOSURVEY` to `no`.
The survey data includes system and platform information and the following
specific settings:
- Identify manager name (as selected when starting licod)
See [here](https://stash.kopano.io/projects/KGOL/repos/ksurveyclient-go) for further
documentation and customization possibilities.
## License
See `LICENSE.txt` for licensing information of this project.