forked from potsda.mn/mobilizon
Add basic documentation for LDAP & OAuth support
Signed-off-by: Thomas Citharel <tcit@tcit.fr>
This commit is contained in:
Thomas Citharel
parent
daa6b59af8
commit
c4f8c30c41
113
docs/administration/configure/auth.md
Normal file
113
docs/administration/configure/auth.md
Normal file
|
|
@ -0,0 +1,113 @@
|
||||||
|
# Authentification
|
||||||
|
|
||||||
|
## LDAP
|
||||||
|
|
||||||
|
Use LDAP for user authentication. When a user logs in to the Mobilizon instance, the email and password will be verified by trying to authenticate
|
||||||
|
(bind) to an LDAP server. If a user exists in the LDAP directory but there is no account with the same email yet on the Mobilizon instance then a new
|
||||||
|
Mobilizon account will be created (without needing email confirmation) with the same email as the LDAP email name.
|
||||||
|
|
||||||
|
!!! tip
|
||||||
|
As Mobilizon uses email for login and LDAP bind is often done with account UID/CN, we need to start by searching for LDAP account matching with this email. LDAP search without bind is often disallowed, so you'll probably need an admin LDAP user.
|
||||||
|
|
||||||
|
|
||||||
|
Change authentification method:
|
||||||
|
```elixir
|
||||||
|
config :mobilizon,
|
||||||
|
Mobilizon.Service.Auth.Authenticator,
|
||||||
|
Mobilizon.Service.Auth.LDAPAuthenticator
|
||||||
|
```
|
||||||
|
|
||||||
|
LDAP configuration under `:mobilizon, :ldap`:
|
||||||
|
|
||||||
|
* `enabled`: enables LDAP authentication
|
||||||
|
* `host`: LDAP server hostname
|
||||||
|
* `port`: LDAP port, e.g. 389 or 636
|
||||||
|
* `ssl`: true to use SSL, usually implies the port 636
|
||||||
|
* `sslopts`: additional SSL options
|
||||||
|
* `tls`: true to start TLS, usually implies the port 389
|
||||||
|
* `tlsopts`: additional TLS options
|
||||||
|
* `base`: LDAP base, e.g. "dc=example,dc=com"
|
||||||
|
* `uid`: LDAP attribute name to authenticate the user, e.g. when "cn", the filter will be "cn=username,base"
|
||||||
|
* `require_bind_for_search` whether admin bind is required to perform search
|
||||||
|
* `bind_uid` the admin uid/cn for binding before searching
|
||||||
|
* `bind_password` the admin password for binding before searching
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```elixir
|
||||||
|
config :mobilizon, :ldap,
|
||||||
|
enabled: true,
|
||||||
|
host: "localhost",
|
||||||
|
port: 636,
|
||||||
|
ssl: true,
|
||||||
|
sslopts: [],
|
||||||
|
tls: true,
|
||||||
|
tlsopts: [],
|
||||||
|
base: "ou=users,dc=example,dc=local",
|
||||||
|
uid: "cn",
|
||||||
|
require_bind_for_search: true,
|
||||||
|
bind_uid: "admin_account",
|
||||||
|
bind_password: "some_admin_password"
|
||||||
|
```
|
||||||
|
|
||||||
|
## OAuth
|
||||||
|
|
||||||
|
Mobilizon currently supports the following providers:
|
||||||
|
|
||||||
|
* [Discord](https://github.com/schwarz/ueberauth_discord)
|
||||||
|
* [Facebook](https://github.com/ueberauth/ueberauth_facebook)
|
||||||
|
* [Github](https://github.com/ueberauth/ueberauth_github)
|
||||||
|
* [Gitlab](https://github.com/mtchavez/ueberauth_gitlab) (including self-hosted)
|
||||||
|
* [Google](https://github.com/ueberauth/ueberauth_google)
|
||||||
|
* [Keycloak](https://github.com/Rukenshia/ueberauth_keycloak) (through OpenID Connect)
|
||||||
|
* [Twitter](https://github.com/Rukenshia/ueberauth_keycloak)
|
||||||
|
|
||||||
|
Support for [other providers](https://github.com/ueberauth/ueberauth/wiki/List-of-Strategies) can easily be added if requested.
|
||||||
|
|
||||||
|
!!! tip
|
||||||
|
We advise to look at each provider's README file for eventual specific instructions.
|
||||||
|
|
||||||
|
You'll have to start by registering an app at the provider. Be sure to activate features like "Sign-in with" and "emails" scope, as Mobilizon needs users emails to register them.
|
||||||
|
|
||||||
|
Add the configured providers to configuration (you may find the appropriate scopes on the provider's API documentation):
|
||||||
|
```elixir
|
||||||
|
config :ueberauth,
|
||||||
|
Ueberauth,
|
||||||
|
providers: [
|
||||||
|
gitlab: {Ueberauth.Strategy.Gitlab, [default_scope: "read_user"]},
|
||||||
|
keycloak: {Ueberauth.Strategy.Keycloak, [default_scope: "email"]}
|
||||||
|
# ...
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
In order for the « Sign-in with » buttons to be added on Register and Login pages, list your providers:
|
||||||
|
```elixir
|
||||||
|
config :mobilizon, :auth,
|
||||||
|
oauth_consumer_strategies: [
|
||||||
|
:gitlab,
|
||||||
|
{:keycloak, "My corporate account"}
|
||||||
|
# ...
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
If you use the `{:provider_id, "Some label"}` form, the label will be used inside the buttons on Register and Login pages.
|
||||||
|
|
||||||
|
Finally add the configuration for each specific provider. The Client ID and Client Secret are at least required:
|
||||||
|
```elixir
|
||||||
|
config :ueberauth, Ueberauth.Strategy.Facebook.OAuth,
|
||||||
|
client_id: "some_numeric_id",
|
||||||
|
client_secret: "some_secret"
|
||||||
|
|
||||||
|
keycloak_url = "https://some-keycloak-instance.org"
|
||||||
|
|
||||||
|
# Realm may be something else than master
|
||||||
|
config :ueberauth, Ueberauth.Strategy.Keycloak.OAuth,
|
||||||
|
client_id: "some_id",
|
||||||
|
client_secret: "some_hexadecimal_secret",
|
||||||
|
site: keycloak_url,
|
||||||
|
authorize_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/auth",
|
||||||
|
token_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/token",
|
||||||
|
userinfo_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/userinfo",
|
||||||
|
token_method: :post
|
||||||
|
```
|
||||||
Loading…
Reference in a new issue