mirror of
https://github.com/Luzifer/nginx-sso.git
synced 2024-11-09 09:50:01 +00:00
Created Auth Provider Configuration (markdown)
parent
3ccb2f92e8
commit
073846f2bb
1 changed files with 152 additions and 0 deletions
152
Auth-Provider-Configuration.md
Normal file
152
Auth-Provider-Configuration.md
Normal file
|
|
@ -0,0 +1,152 @@
|
|||
## Atlassian Crowd (`crowd`)
|
||||
|
||||
The crowd auth provider connects nginx-sso with an Atlassian Crowd directory server. The SSO authentication cookie used by Jira and Confluence is also used by nginx-sso which means a login in Jira will also perform a login on nginx-sso and vice versa.
|
||||
|
||||
```yaml
|
||||
providers:
|
||||
crowd:
|
||||
url: "https://crowd.example.com/crowd/"
|
||||
app_name: ""
|
||||
app_pass: ""
|
||||
```
|
||||
|
||||
The configuration is quite simple: Create an application in Crowd, enter the Crowd URL and the application credentials into the config and you're done.
|
||||
|
||||
## LDAP Auth (`ldap`)
|
||||
|
||||
The LDAP provider connects to a (remote) LDAP directory server and authenticates users against and reads groups from it.
|
||||
|
||||
```yaml
|
||||
providers:
|
||||
ldap:
|
||||
enable_basic_auth: false
|
||||
manager_dn: "cn=admin,dc=example,dc=com"
|
||||
manager_password: ""
|
||||
root_dn: "dc=example,dc=com"
|
||||
server: "ldap://ldap.example.com"
|
||||
# Optional, defaults to root_dn
|
||||
user_search_base: ou=users,dc=example,dc=com
|
||||
# Optional, defaults to '(uid={0})'
|
||||
user_search_filter: ""
|
||||
# Optional, defaults to root_dn
|
||||
group_search_base: "ou=groups,dc=example,dc=com"
|
||||
# Optional, defaults to '(|(member={0})(uniqueMember={0}))'
|
||||
group_membership_filter: ""
|
||||
# Replace DN as the username with another attribute
|
||||
# Optional, defaults to "dn"
|
||||
username_attribute: "uid"
|
||||
# Configure TLS parameters for LDAPs connections
|
||||
# Optional, defaults to null
|
||||
tls_config:
|
||||
# Set the hostname for certificate validation
|
||||
# Optional, defaults to host from the connection URI
|
||||
validate_hostname: ldap.example.com
|
||||
# Disable certificate validation
|
||||
# Optional, defaults to false
|
||||
allow_insecure: false
|
||||
```
|
||||
|
||||
To use this provider you need to have a LDAP server set up and filled with users. The example (and default) config above assumes each of your users carries an `uid` attribute and groups does contains `member` or `uniqueMember` attributes. Inside the groups full DNs are expected. For the ACL also full DNs are used.
|
||||
|
||||
- `enable_basic_auth` - optional - Allows automated clients to pass credentials using basic auth instead of using the login form
|
||||
- `manager_dn` - required - A LDAP account which is allowed to list users and groups (it needs no access to the password!)
|
||||
- `manager_password` - required - The password for the `manager_dn`
|
||||
- `root_dn` - required - The base of your directory
|
||||
- `server` - required - Connection string to the LDAP server in format `ldap[s]://<host>[:<port>]`
|
||||
- `user_search_base` - optional - Using this parameter you can limit the user search to a certain sub-tree. Within this sub-tree the `uid` must be unique (as the name already states). If unset the `root_dn` is used here
|
||||
- `user_search_filter` - optional - The query to issue to find the user from its `uid` (`{0}` is replaced with the `uid`). If unset the query `(uid={0})` is used
|
||||
- `group_search_base` - optional - Like the `user_search_base` this limits the sub-tree where to search for groups, also defaults to `root_dn`
|
||||
- `group_membership_filter` - optional - The query to issue to list all groups the user is a member of. The DN of each group is used as the group name. If unset the query `(|(member={0})(uniqueMember={0}))` is used (`{0}` is replaced with the users DN, `{1}` is replaced with the content of the `username_attribute`)
|
||||
- `username_attribute` - optional - The attribute containing the username returned to nginx instead of the dn. If unset the `dn` is used
|
||||
- `tls_config` - optional - Configures TLS parameters for LDAPs connections
|
||||
- `validate_hostname` - optional - Set the hostname for certificate validation, when unset the hostname from the `server` URI is used
|
||||
- `allow_insecure` - optional - Disable certificate validation. Setting this is not recommended for production setups
|
||||
|
||||
When using the LDAP provider you need to pay attention when writing your ACL. As DNs are used as names for users and groups you also need to specify those in the ACL:
|
||||
|
||||
```yaml
|
||||
acl:
|
||||
rule_sets:
|
||||
- rules:
|
||||
- field: "host"
|
||||
equals: "test.example.com"
|
||||
allow:
|
||||
- "cn=myuser,ou=users,dc=example,dc=com"
|
||||
- "@cn=mygroup,ou=groups,dc=example,dc=com"
|
||||
```
|
||||
|
||||
## Simple Auth (`simple`)
|
||||
|
||||
The simple auth provider consists of a static mapping between users and passwords and groups and users. This can be seen as the replacement of htpasswd files.
|
||||
|
||||
```yaml
|
||||
providers:
|
||||
simple:
|
||||
enable_basic_auth: false
|
||||
|
||||
# Unique username mapped to bcrypt hashed password
|
||||
users:
|
||||
luzifer: "$2a$10$FSGAF8qDWX52aBID8.WpxOyCvfSQ3JIUVFiwyd1jolb4jM3BzJmNu"
|
||||
mike: "$2a$10$/0nrpYkdVhAifCLCI1DTz.4CkbCkc8CsvYhfvBRIhTTQDfBrkJ8Re"
|
||||
|
||||
# Groupname to users mapping
|
||||
groups:
|
||||
admins: ["luzifer"]
|
||||
users: ["mike"]
|
||||
|
||||
# MFA configs: Username to configs mapping
|
||||
mfa:
|
||||
luzifer:
|
||||
- provider: google
|
||||
attributes:
|
||||
secret: asdgsdfhgshf
|
||||
```
|
||||
|
||||
You can see how to configure the provider the example above: No surprises, just ensure you are using bcrypt hashes for the passwords, no other hash functions are supported.
|
||||
|
||||
If `enable_basic_auth` is set to `true` the credentials can also be submitted through basic auth. This is useful for services whose clients does not support other types of authentication.
|
||||
|
||||
When there is at least one MFA configuration provided for the user inside the `mfa` block the user will be forced to enter a MFA token during login or otherwise the login will fail.
|
||||
|
||||
### Provider configuration: Token Auth (`token`)
|
||||
|
||||
The token auth provider is intended to give machines access to endpoints. Users will not be able to "login" using tokens when they see the login form.
|
||||
|
||||
```yaml
|
||||
providers:
|
||||
token:
|
||||
# Mapping of unique token names to the token
|
||||
tokens:
|
||||
tokenname: "MYTOKEN"
|
||||
mycli: "kQHjQLuQdkSPwdJ1mueniLMPSjCc6GVt"
|
||||
|
||||
# Groupname to token mapping
|
||||
groups:
|
||||
mytokengroup: ["tokenname"]
|
||||
```
|
||||
|
||||
When accessing the sites using a token this header is expected:
|
||||
|
||||
`Authorization: Token MYTOKEN`
|
||||
|
||||
## Yubikey One-Factor-Auth (`yubikey`)
|
||||
|
||||
The Yubikey auth provider is a one-factor-authentication mechanism. Not to be confused by U2F or HOTP two-factor methods. Your users only need to press the button to fully login. (Be sure you know what you're doing here!)
|
||||
|
||||
```yaml
|
||||
providers:
|
||||
yubikey:
|
||||
# Get your client / secret from https://upgrade.yubico.com/getapikey/
|
||||
client_id: "12345"
|
||||
secret_key: "foobar"
|
||||
|
||||
# First 12 characters of the OTP string mapped to the username
|
||||
devices:
|
||||
ccccccfcvuul: "luzifer"
|
||||
|
||||
# Groupname to users mapping
|
||||
groups:
|
||||
admins: ["luzifer"]
|
||||
```
|
||||
|
||||
You need to configure the `client_id` and the `secret_key` for the Yubico online validation service and the Yubikeys need to comply the specifications of that API (do not put random values into the device ID). Afterwards just take the first 12 characters of the keys OTP and map it to an user.
|
||||
Loading…
Reference in a new issue