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 |
LDAP Bind DN, LDAP Bind Password |
The service account used for searches, such as |
LDAP Start TLS |
Upgrade an |
LDAP User Search |
Where and how to find users: base DN, scope and filter, where |
LDAP User DN Template |
Instead of a search, the DN of every user, such as |
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, |
LDAP Connection Options |
Options of the LDAP library, such as |
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.
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".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.
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.
Register a confidential client at the provider, with the callback URL of the method as its redirect URI.
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.Set Username Key and Groups Claim to the claims that hold the username and the groups (
preferred_usernameandGroupby 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).
In Entra ID, register an application, add a web redirect URI with the callback URL of the method, and create a client secret.
Create the method with Client ID (the application ID) and Secret.
To use groups in rules, add a groups claim to the tokens of the application. Groups Claim is
groupsby default. Entra ID sends group object IDs unless you configure it to send names.Field to use as username chooses the claim used as the username, such as
preferred_usernameoremail.
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 (
asciiby default,paporchap), 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.