Authentication providers

This page describes the settings of each type of authentication method, and what to set up on the provider side. The form shows a help text for every field, and the full list of settings of each type is available at /api/gateway/v1/authenticator_plugins/.

Every type also has Additional Authenticator Fields, for settings of the underlying library that the form does not show. They are passed as they are, without validation.

Before you start

The platform address. Providers redirect users back to the platform, so the address users reach it at must be final: the Route or Ingress host of the KoiosPlatform (see status.URL). If you change it, update the callback URL at every provider.

Certificates. The gateway connects to LDAP servers and to OIDC, Keycloak and Azure AD endpoints itself. If they use certificates from a private certificate authority, give the platform that CA with bundle_cacert_secret (see the KoiosPlatform reference).

Callback URLs. For SSO types, the gateway fills in the callback URL when you save the method:

https://<koios host>/api/gateway/social/complete/<slug>/

<slug> is generated when the method is created and does not change afterwards. Save the method first, then copy the callback URL from its details into the provider.

LDAP

Users log in with their directory username and password. The gateway binds with a service account, searches for the user, and then binds as the user to check the password.

Field

What to set

LDAP Server URI

One or more URIs, such as ldaps://ldap.example.com:636 or ldap://ldap.example.com:389. They are tried in order.

LDAP Bind DN, LDAP Bind Password

The service account used for searches, such as CN=koios,OU=Service Accounts,DC=example,DC=com.

LDAP Start TLS

Upgrade an ldap:// connection to TLS. Not needed with ldaps://.

LDAP User Search

Where and how to find users: base DN, scope and filter, where %(user)s is the username typed at login. To search several bases, give a list of searches.

LDAP User DN Template

Instead of a search, the DN of every user, such as uid=%(user)s,ou=people,dc=example,dc=com. Faster when all users share one format. When set, it is used instead of LDAP User Search.

LDAP User Attribute Map

Directory attributes for the user’s first name, last name and email.

LDAP Group Search

Where to find groups, used by group mapping rules.

LDAP Group Type, LDAP Group Type Parameters

How group membership is stored. For Active Directory and most servers, MemberDNGroupType with {"name_attr": "cn", "member_attr": "member"}; for nested Active Directory groups, NestedMemberDNGroupType.

LDAP Connection Options

Options of the LDAP library, such as {"OPT_REFERRALS": 0, "OPT_NETWORK_TIMEOUT": 30}. Referrals are off by default, which avoids searches that hang against Active Directory.

A user search for Active Directory:

["OU=Users,DC=example,DC=com", "SCOPE_SUBTREE", "(sAMAccountName=%(user)s)"]

The same for OpenLDAP, where the username is in uid, and a group search:

["ou=people,dc=example,dc=com", "SCOPE_SUBTREE", "(uid=%(user)s)"]
["ou=groups,dc=example,dc=com", "SCOPE_SUBTREE", "(objectClass=groupOfNames)"]

The attribute map for Active Directory:

{"first_name": "givenName", "last_name": "sn", "email": "mail"}

Test the bind DN and the searches with ldapsearch from a machine on the same network before you create the method:

ldapsearch -x -H ldaps://ldap.example.com -D "CN=koios,OU=Service Accounts,DC=example,DC=com" \
  -W -b "OU=Users,DC=example,DC=com" "(sAMAccountName=josie)"

Group names in rules are full DNs. Directories may return them with a different case than the one you write, so copy them from what the directory returns.

SAML

The platform is the service provider (SP), and your identity provider (IdP) authenticates users.

  1. Create a key pair for the platform, for example openssl req -new -x509 -days 3650 -nodes -keyout sp.key -out sp.crt -subj "/CN=koios.example.com".

  2. Create the method with:

    • SAML Service Provider Entity ID: an identifier for the platform at the IdP, usually its URL;

    • SAML Service Provider Public Certificate and Private Key: the key pair;

    • SAML Service Provider Organization Info, Technical Contact and Support Contact: the details published in the platform metadata, for example {"en-US": {"name": "koios", "displayname": "Koios Automation Platform", "url": "https://koios.example.com"}};

    • IdP Login URL, Entity ID and IdP Public Cert: from the metadata of your IdP;

    • the assertion attributes that hold the user’s Username, User Email, User First Name, User Last Name, User Permanent ID and Groups.

  3. Save it, and register the platform at the IdP with its entity ID and its SAML Assertion Consumer Service (ACS) URL. The IdP can also read the SP metadata from https://<koios host>/api/gateway/v1/authenticators/<id>/metadata/.

SAML Security Config and SAML Service Provider extra configuration data are passed to the python3-saml library, for example to require signed assertions:

{"wantAssertionsSigned": true, "requestedAuthnContext": false}

SAML IDP to extra_data attribute mapping keeps other assertion attributes with the user, so mapping rules can use them.

Generic OIDC

For any OpenID Connect provider.

  1. Register a confidential client at the provider, with the callback URL of the method as its redirect URI.

  2. Create the method with OIDC Provider URL (the issuer, the part before /.well-known/openid-configuration), OIDC Key (the client ID) and OIDC Secret. The other endpoints are discovered from the provider.

  3. Set Username Key and Groups Claim to the claims that hold the username and the groups (preferred_username and Group by default), and ask the provider to include them in the token or in the userinfo response.

Leave Verify OIDC Provider Certificate on. List of OAuth2 Scope(s) is openid, profile and email by default; add the scope your provider needs for groups, if any.

Keycloak

A dedicated type for Keycloak realms. Create a confidential OpenID Connect client in the realm with the callback URL as a valid redirect URI, and set:

  • Keycloak Provider URL: https://<keycloak>/realms/<realm>/protocol/openid-connect/auth;

  • Keycloak Access Token URL: https://<keycloak>/realms/<realm>/protocol/openid-connect/token;

  • Keycloak OIDC Key and Keycloak OIDC Secret: the client ID and secret;

  • Keycloak Public Key: the RS256 public key of the realm (Realm settings > Keys);

  • Groups Claim: the claim a group mapper of the client adds to the token.

Older Keycloak versions have /auth before /realms in these URLs. Generic OIDC also works with Keycloak.

Azure AD

For Microsoft Entra ID (formerly Azure Active Directory).

  1. In Entra ID, register an application, add a web redirect URI with the callback URL of the method, and create a client secret.

  2. Create the method with Client ID (the application ID) and Secret.

  3. To use groups in rules, add a groups claim to the tokens of the application. Groups Claim is groups by default. Entra ID sends group object IDs unless you configure it to send names.

  4. Field to use as username chooses the claim used as the username, such as preferred_username or email.

Google OAuth

Create an OAuth client ID of type Web application in the Google Cloud console, with the callback URL of the method as an authorized redirect URI, and set Google OAuth2 Key and Google OAuth2 Secret to its client ID and secret. Users log in with their Google account; use an allow rule to limit who can log in.

GitHub

All GitHub types take the GitHub OAuth2 Key and Secret of an OAuth app, created in GitHub under Settings > Developer settings > OAuth Apps with the callback URL of the method as its Authorization callback URL.

Type

Who can log in

Extra settings

GitHub

Any GitHub user

GitHub organization

Members of one organization

GitHub OAuth2 Organization Name

GitHub team

Members of one team

GitHub OAuth2 Team ID (numeric, from the GitHub API)

GitHub enterprise, organization, team

The same, on GitHub Enterprise Server

Base URL and Github OAuth2 Enterprise API URL of the server, plus the organization or team

RADIUS and TACACS+

Users log in with a username and password that the gateway checks against the server.

  • Radius: Hostname of RADIUS Server, Port number (1812 by default) and the Shared secret.

  • TACACS+: Hostname of TACACS+ Server, Port number (49 by default), the Shared secret, the Authentication Protocol (ascii by default, pap or chap), whether to send the client address, and the session timeout in seconds (5 by default; 0 disables it).

Neither returns groups, so their rules cannot be based on groups.

Local

The local database type has no settings, and one is created at installation. More local methods do not separate users: they all check the same users and passwords, and the first in the login order that accepts them applies its rules.