Auth Provider Configuration

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.

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.

Google oAuth2 (google_oauth)

This provider sends the user to Google for oAuth2 login using the configured consent screen and returns their identification afterwards as the user.

providers:
  google_oauth:
    client_id: ""
    client_secret: ""
    redirect_url: "https://login.luzifer.io/login"

    # Optional, defaults to no limitations
    require_domains: [ "example.com" ]
    # Optional, defaults to "user-id"
    user_id_method: "full-email"

To obtain the client_id and client_secret create a new project in the Google Cloud Console and under "API & Services" set up the oAuth2 consent screen. Afterwards create new oAuth2 credentials for your project.

The redirect_url must point back to the /login path of nginx-sso to complete the login process. With the require_domain parameter you can limit the users being allowed to sign in to users of a specific domain (useful for company internal portals with whitelisting for the company domain). For this the primary email address of the user is matched (in case your Google Apps account does have aliases set up an alias domain will not work).

By default the user identifier will be the user-id, which is a quite long numeric ID. When changing the primary domain or changing the name of the user this ID will not change and is therefore the safest possible variant. Also supported are the user_id_methods of full-email and local-part which both are derived from the users primary address. For the user knut@example.com the full-email will set the username to knut@example.com while local-part will set it to knut.

After a new user signed up you can point them to the /debug route in your nginx-sso instance and let them send you the displayed username (user ID) for assigning to ACLs.

LDAP Auth (ldap)

The LDAP provider connects to a (remote) LDAP directory server and authenticates users against and reads groups from it.

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: The username reported to nginx will also be used to check the access. So if you're using the default (username_attribute: dn) you need to use those DN in your ACL:

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"

OpenID Connect (oidc)

This provider sends the user to the configured OpenID Connect provider for oAuth2 login and returns their identification afterwards as the user.

providers:
  oidc:
    client_id: ""
    client_secret: ""
    redirect_url: "https://login.luzifer.io/login"
    # Optional, defaults to "OpenID Connect"
    issuer_name: ""
    issuer_url: ""

    # Optional, defaults to no limitations
    require_domain: "example.com"
    # Optional, defaults to "user-id"
    user_id_method: "full-email"

The redirect_url must point back to the /login path of nginx-sso to complete the login process. With the require_domain parameter you can limit the users being allowed to sign in to users of a specific domain (useful for company internal portals with whitelisting for the company domain).

By default the user identifier will be the subject, which is defined by your OIDC provider. Also supported are the user_id_methods of full-email and local-part which both are derived from the users email address. For the user knut@example.com the full-email will set the username to knut@example.com while local-part will set it to knut.

After a new user signed up you can point them to the /debug route in your nginx-sso instance and let them send you the displayed username (user ID) for assigning to ACLs.

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.

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.

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.

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!)

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.