Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/fernandoescolar/minioidc

A lightweight OpenID Connect (OIDC) server
https://github.com/fernandoescolar/minioidc

golang lightweight oidc server

Last synced: 7 months ago
JSON representation

A lightweight OpenID Connect (OIDC) server

Awesome Lists containing this project

README 

          
# minioidc



minioidc is a lightweight OpenID Connect (OIDC) server designed to provide Single Sign-On (SSO) functionality for small or home networks. While not a complete OIDC implementation, minioidc currently supports the following grant types:



- *Authorization Code with PKCE*: Securely obtain an authorization code using Proof Key for Code Exchange (PKCE).

- *Refresh Token*: Extend the validity of access tokens using refresh tokens.

- *Client Credentials*: Authenticate clients using client credentials.

- *Password*: Authenticate users using their username and password.

- *Implicit*: Obtain tokens directly from the authorization endpoint.

- *Hybrid*: Combine the authorization code and implicit flows.



## Features



- **Simple and Lightweight**: minioidc is designed to be a straightforward solution for enabling SSO in small or home networks.

- **Client and User Configuration**: Easily configure client and user data directly in the YAML configuration file.

- **Flexible Data Storage**: Store grant and session data in memory or use a SQLite v3 database for more persistent storage.

- **LDAP Users Integration**: Use LDAP users to login.

- **MFA**: Require MFA for all users using TOTP App (e.g. Google Authenticator).

- **Secure by Default**: Enable HTTP Strict Transport Security (HSTS), Content Security Policy (CSP), secure cookies, and more with a single configuration option.



## Roadmap



The following features are planned for future releases:



- [x] OIDC Discovery endpoint with JWKS

- [x] Authorization endpoint

  - [x] Authorization Code with PKCE

  - [x] Implicit flow

  - [x] Hybrid flow

- [ ] Device Code authorization endpoint

- [x] Token endpoint

  - [x] Refresh Token

  - [x] Client Credentials

  - [x] Password

- [x] Userinfo endpoint

- [ ] Introspection endpoint

- [ ] Revocation endpoint

- [ ] End session endpoint

- [x] CSRF

- [x] Yaml config file

- [x] ENV secrets inside yaml config file

- [x] Sqlite database for grants and sessions (and also for MFA)

- [x] MFA with TOTP App (e.g. Google Authenticator)

- [ ] MFA with email?

- [x] Ldap Users integration

- [ ] Change password

- [ ] Forgot password

- [ ] MFAs management

- [ ] MongoDB database for users, clients, grants and sessions (and also for MFA)

- [ ] Groups or roles

- [ ] Management API



## Getting Started



- You can create a docker image and run it with the following commands:



```bash

make build-docker && make run-docker

```



And then visit [http://localhost:8000](http://localhost:8000).



- You can also use the visual studio code launch configuration to run the server in debug mode.



- Or you can call the `make run` command to run the server directly.



## Makefile Commands



There are several commands available in the Makefile:



- `make build` - Build the binary

- `make run` - Run the binary

- `make build-docker` - Build the docker image

- `make run-docker` - Run the docker image

- `make test` - Run the tests

- `make clean` - Clean the binary

- `make lint` - Run the linter

- `make hash text=plain_text_to_hash` - Generate a hash from a given `text`



## Configuration



You have to set the following environment variables:



- `MINIOIDC_ADDR` - The address to listen on (default: `:8000`)

- `MINIOIDC_CONFIG` - The path to the yaml configuration file



The configuration file is a yaml file with the following structure:



```yaml

name: My MiniOIDC

masterkey: 12345678901234567890123456789012

issuer: http://example.com

audience: http://example.com

require_mfa: true

reuse_refresh_tokens: false

private_rsa_key_path: private_key.pem

middlewares:

  hsts: true

  csp: true

  secure_cookies: true

  forward_headers: true

  log_requests: true

ttl:

  access: 20 # minutes

  refresh: 129600 # 90 days

  session: 129600 # 90 days

  code: 5 # minutes

  csrf: 5 # minutes

sqlite:

  filepath: db.sqlite3

  use_in_grants: true

  use_in_sessions: true

  use_in_mfa: true

ldap:

    server: localhost:389

    bind: uid=admin,cn=users,dc=example,dc=com

    password: password

    base_dn: dc=example,dc=com

    filter_dn: (&(uid={username})(objectClass=person))

    attributes:

      subject: uidNumber

      name: uid

      email: mail

      phone: phone

      address: address

templates:

  base: templates/base.html

  login: templates/login2.html

  mfa_create: templates/mfa_create.html

  mfa_verify: templates/mfa_verify.html

clients:

  - id: myclient

    secret_hash: $2a$06$L6/zALdtbkYajjHTZUW29ePBEb/hwhgjhXC4YpHANavvKDJl69ctK # secret

    redirect_uris:

     - http://myapi.com/callback

users:

  - subject: 1

    email: use@mail.com

    email_verified: true

    preferred_username: user

    password_hash: $2a$06$03dduqc0lMbsb5go/l6RI.cRb03Hos9CMpgm5/yYuRsSQPHtrFwSq # password

    phone: +1234567890

    address: 1 Main St. City, State 12345

    groups:

      - admin

```



In the root section, you can configure the following settings:



- `issuer` - The OIDC issuer

- `audience` - The OIDC audience

- `require_mfa` - Whether to require MFA for all users (default: `false`)

- `reuse_refresh_tokens` - Whether to allow re-use refresh tokens (default: `false`)

- `private_rsa_key_path` - The path to the private RSA key (if not set, a new random key will be generated)



In the `middlewares` section, you can activate the following middlewares:



- `hsts` - Whether to enable HTTP Strict Transport Security (HSTS) (default: `false`)

- `csp` - Whether to enable Content Security Policy (CSP) (default: `false`)

- `secure_cookies` - Whether to enable secure cookies (default: `false`)

- `forward_headers` - Whether to forward headers (default: `false`)

- `log_requests` - Whether to log requests (default: `false`)



In the `ttl` section, you can configure the following TTLs:



- `access` - The access token TTL in minutes (default: `20`)

- `refresh` - The refresh token TTL in minutes (default: `129600`, 90 days)

- `session` - The session TTL in minutes (default: `129600`, 90 days)

- `code` - The authorization code TTL in minutes (default: `5`)

- `csrf` - The CSRF token TTL in minutes (default: `5`)



In the `sqlite` section, you can configure the following SQLite settings:



- `filepath` - The path to the SQLite database file. It is mandatory if `use_in_grants` or `use_in_sessions` is set to `true`.

- `use_in_grants` - Whether to use the SQLite database for storing grant data (default: `false`)

- `use_in_sessions` - Whether to use the SQLite database for storing session data (default: `false`)

- `use_in_mfa` - Whether to use the SQLite database for storing MFA data (default: `false`)



In the `ldap` section, you can configure the LDAP user store settings:



- `server` - The LDAP server address

- `bind` - The LDAP bind DN

- `password` - The LDAP bind password

- `base_dn` - The LDAP base DN

- `filter_dn` - The LDAP filter DN

- `attributes` - The LDAP attributes to use for each user property

- `attributes.subject` - The LDAP attribute to use for the user subject

- `attributes.name` - The LDAP attribute to use for the user name

- `attributes.email` - The LDAP attribute to use for the user email

- `attributes.phone` - The LDAP attribute to use for the user phone

- `attributes.address` - The LDAP attribute to use for the user address



> If you use LDAP users, you can not configure the `users` section in the yaml configuration file.



In the `templates` section, you can configure the following html/templates:



- `base` - The base template

- `login` - The login page template

- `mfa_create` - The MFA create page template

- `mfa_verify` - The MFA verify page template



> you can add your static files (like css, js, images, ...) in the `static` folder and use them in your templates (e.g. ``



Seed data is provided in the `clients` and `users` sections. In the `clients` section, you can create the OIDC clients to use in the auth challenge. Each client has the following properties:



- `id` - The client ID

- `secret_hash` - The client secret hash (use the `make hash` command to generate a hash)

- `redirect_uris` - The list of allowed redirect URIs



In the `users` section, you can create the users to login. Each user has the following properties:



- `subject` - The user subject

- `email` - The user email

- `email_verified` - Whether the user email is verified

- `preferred_username` - The user preferred username (the username used for login)

- `password_hash` - The user password hash (use the `make hash` command to generate a hash)

- `phone` - The user phone number

- `address` - The user address

- `groups` - The list of user groups



The yaml configuration file can also reference environment variables. You can use the following syntax to use environment variables in your yaml configuration file:



```yaml

value1: ${ENV_VAR}

value2: $OTHER_ENV_VAR

```



## Use in your projects



You can use the `minioidc` package in your projects to add OIDC authentication to your web applications:



```go

package main



import (

	"log"

	"net/http"



	"github.com/fernandoescolar/minioidc/pkg/api"

)



func main() {

	builder := &api.Builder{

		Audience: "https://api.example.com",

		Issuer:   "https://minioidc.example.com",

		Clients: []api.Client{

			{

				ID:           "myclient",

				SecretHash:   "$2a$06$L6/zALdtbkYajjHTZUW29ePBEb/hwhgjhXC4YpHANavvKDJl69ctK", // secret

				RedirectURIs: []string{"https://api.example.com/callback"},

			},

		},

		Users: []api.User{

			{

				Subject:           "0000001",

				PreferredUsername: "user",

				PasswordHash:      "$2a$06$03dduqc0lMbsb5go/l6RI.cRb03Hos9CMpgm5/yYuRsSQPHtrFwSq", // password

			},

		},

	}



	minioidc, err := builder.Build(config)

	if err != nil {

		log.Fatal(err)

	}



	mux := http.NewServeMux()

	handler := minioidc.Wrap(mux)



	log.Printf("Listening http://localhost:8000")

	err = http.ListenAndServe(":8000", handler)

	if err != nil && err != http.ErrServerClosed {

		log.Fatal(err)

	}

}

```



The builder has the following fields:



- `Name string` - Set the OIDC name (default: `minioidc`)

- `MasterKey string` - Set the OIDC master key use to encrypt and decrypt internal data (if not set, a new random key will be generated)

- `Audience string` - Set the OIDC audience (it is MANADATORY)

- `Issuer string` - Set the OIDC issuer (it is MANADATORY)

- `RequireMFA bool` - Set whether to require MFA for all users (default: `false`)

- `ReuseRefreshTokens bool` - Set whether to allow re-use refresh tokens (default: `false`)

- `UseHSTS bool` - Set whether to enable HTTP Strict Transport Security (HSTS) (default: `false`)

- `UseCSP bool` - Set whether to enable Content Security Policy (CSP) (default: `false`)

- `UseSecureCookie bool` - Set whether to enable secure cookies (default: `false`)

- `UseForwardedHeaders bool` - Set whether to forward headers (default: `false`)

- `LogRequests bool` - Set whether to log requests (default: `false`)

- `Clients []Client` - Set the OIDC clients

- `Users []User` - Set the OIDC users

- `PrivateKey *rsa.PrivateKey` - Set the OIDC private key

- `PrivateKeyFile string` - Set the OIDC private key from a file

- `AccessTTL time.Duration` - Set the access token TTL

- `RefreshTTL time.Duration` - Set the refresh token TTL

- `SessionTTL time.Duration` - Set the session TTL

- `CodeTTL time.Duration` - Set the authorization code TTL

- `CSRFTTL time.Duration` - Set the CSRF token TTL

- `ClientStore ClientStore` - Set the client store

- `UserStore UserStore` - Set the user store

- `GrantStore GrantStore` - Set the grant store

- `SessionStore SessionStore` - Set the session store

- `MFAStore MFAStore` - Set the MFA store

- `BaseTemplate string` - Set the base template

- `LoginTemplate string` - Set the login template

- `MFACreateTemplate string` - Set the MFA create template

- `MFAVerifyTemplate string` - Set the MFA verify template



And the builder has the following methods:



- `UseSQLite(string, SqliteDatabases)` - Set the SQLite database file path and databases to use (flags: `NoSqliteDatabases`, `Grants`, `Sessions` or `MFA`)

- `UseLDAP(string, LDAPConfig)` - Set the LDAP server address and LDAP config to use



The `LDAPConfig` struct has the following fields:



- `Bind string` - The LDAP bind DN

- `Password string` - The LDAP bind password

- `BaseDN string` - The LDAP base DN

- `FilterDN string` - The LDAP filter DN

- `SubjectAttribute string` - The LDAP attribute to use for the user subject

- `NameAttribute string` - The LDAP attribute to use for the user name

- `EmailAttribute string` - The LDAP attribute to use for the user email

- `PhoneAttribute string` - The LDAP attribute to use for the user phone

- `AddressAttribute string` - The LDAP attribute to use for the user address



## Contributing



## License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details