Authentication

Authentication in daikoku can be tricky. It's a tenant configuration, we are here to setup some examples.

Local
LDAP
Otoroshi
OAuth2

this is the default authentication mode. Every user can create an account in your Daikoku instance, the user profil is saved in database. There is no needed configuration for this mode.

Before starting

If you already have an up and running Daikoku instance, you can skip the following instructions and log in to your instance.

Let’s start by downloading the latest Daikoku and run it

Once Daikoku is started you can log in to your brand new instance.

Running an openldap server

Run ghcr.io/rroemhild/docker-test-openldap:master docker Image

note

you can find all documention on the github repo

first, pull and run your ldap. This openldap is already initialized with data based on futurama tv show.

docker pull ghcr.io/rroemhild/docker-test-openldap:master
docker run --rm -p 10389:10389 -p 10636:10636 ghcr.io/rroemhild/docker-test-openldap:master

Let’s make the first search in our LDAP container :

# List all Users
ldapsearch -H ldap://localhost:10389 -x -b "ou=people,dc=planetexpress,dc=com" -D "cn=admin,dc=planetexpress,dc=com" -w GoodNewsEveryone "(objectClass=inetOrgPerson)"

the response is very long due to image but at the end you shoulf have the following output:

  ...
  ...
  # admin_staff, people, planetexpress.com
  dn: cn=admin_staff,ou=people,dc=planetexpress,dc=com
  objectClass: Group
  objectClass: top
  groupType: 2147483650
  cn: admin_staff
  member: cn=Hubert J. Farnsworth,ou=people,dc=planetexpress,dc=com
  member: cn=Hermes Conrad,ou=people,dc=planetexpress,dc=com

  # ship_crew, people, planetexpress.com
  dn: cn=ship_crew,ou=people,dc=planetexpress,dc=com
  objectClass: Group
  objectClass: top
  groupType: 2147483650
  cn: ship_crew
  member: cn=Philip J. Fry,ou=people,dc=planetexpress,dc=com
  member: cn=Turanga Leela,ou=people,dc=planetexpress,dc=com
  member:: Y249QmVuZGVyIEJlbmRpbmcgUm9kcsOtZ3VleixvdT1wZW9wbGUsZGM9cGxhbmV0ZXhwc
  mVzcyxkYz1jb20=

  # search result
  search: 2
  result: 0 Success

  # numResponses: 11
  # numEntries: 10

Create an Authentication configuration

Go ahead and navigate to your Daikoku home page
Click on the your avatar on bottom left of the screen
Then <your-tenant-name> settings
Then Authentication on left panel
You must be on <your-domain>/settings/settings/authentication
This page show the settings for the current authentication mode (by default Local)
Click on LDAP at the top of the form
Add a LDAP Server URL with value ldap://localhost:10389 and dc=planetexpress,dc=com as Search base
Set ou=people as Users search base
Set cn=ship_crew as Simple user filter
Set cn=admin_staff as Daikoku admin filter
Set (mail=${username}) as Search filter
Set cn=admin,dc=planetexpress,dc=com as Admin username (bind DN)
Set GoodNewsEveryone as Admin password
Name fields name can be givenName and sn
Set mail as Email field name

With this configuration, all ldap users with cn admin_staff will be Daikoku admin otherwise, with cn ship_crew he will be a simple user.

Testing your configuration

Disconnect from your instance Then click on the Login button (or navigate to <your-daikoku-domain>/login) Set fry@planetexpress.com/fry as credentials for a simple user and professor@planetexpress.com/professor for a Daikoku admin.

A fallback solution is always available in the event of a bad authentication configuration. By going to <your-daikoku-domain>.login, the previous local administrators will be able to login.

warning

In one case, your search filter can be annoying. if instead of mail, you've choose to log user by uid, when team admins will wants to invite a collaborator, they will be required to know the user uid.

In this case you can replace Search filter by (|(uid=${username})(mail=${username})) both uid and mail will be auhtorized to log in (and search collaborator)

Before starting

If you already have an up and running Daikoku instance, you can skip the following instructions and log in to your instance.

Let’s start by downloading the latest Daikoku and run it

Once Daikoku is started you can log in to your brand new instance.

Running an otoroshi server

Otoroshi have his own manual to this part let's get as run your Otoroshi.

Create an authentication module

Like the previous section, you can follow instructions in here to create a new Auth plugin in Otoroshi. You can find many possibility to secure Daikoku with Otoroshi in the documentation.

Expose your daikoku by Otoroshi

warning

before exposing your daikoku instance with otoroshi, you need to setup exposing mode to Otoroshi.

You ultimately have to add some plugins along the route to make this work :

Authentication, select the created Auth module in configuration to use it
Otoroshi info. token, you can configure the name of the header in which the authentication token will be passed and the secert to signe this token.

Create an Authentication configuration

Go ahead and navigate to your Daikoku home page
Click on the your avatar on bottom left of the screen
Then <your-tenant-name> settings
Then Authentication on left panel
You must be on <your-domain>/settings/settings/authentication
This page show the settings for the current authentication mode (by default Local)
Click on Otoroshi at the top of the form
Fill the header name previously setup
Fill the secret previously setup

Testing your configuration

Disconnect from your instance Then click on the Login button (or navigate to <your-daikoku-domain>/login) You can now login with a user setup with the auth module.

warning

To be daikoku admin, a user need to have a daikokuAdmin property in his definition setup to true. You can cerate a Daikoku admin by adding a metadata in the user definition in the Auth. plugin :

{daikokuAdmin: true}

info

For this tutorial, we'll use Auth0

Before starting

If you already have an up and running Daikoku instance, you can skip the following instructions and log in to your instance.

Let’s start by downloading the latest Daikoku and run it

Once Daikoku is started you can log in to your brand new instance.

Configure an Auth0 client

The first step of this tutorial is to setup an Auth0 application with the information of the instance of our Otoroshi.

Navigate to https://manage.auth0.com (create an account if it’s not already done).

Let’s create an application when clicking on the Applications button on the sidebar. Then click on the Create application button on the top right.

Choose Regular Web Applications as Application type Then set for example daikoku-client as Name, and confirm the creation Jump to the Settings tab Scroll to the Application URLs section and add the following urls

http://localhost:9000/auth/oauth2/callback as Allowed Callback URLs
http://localhost:9000 as Allowed Logout URLs
http://localhost:9000 as Allowed Web Origins Save changes at the bottom of the page.

Once done, we have a full setup, with a client ID and secret at the top of the page, which authorizes our Daikoku and redirects the user to the callback url when they log into Auth0.

warning

To be daikoku admin, a user need to have a daikokuAdmin property in his definition setup to true. Daikoku get this information in the metadata of user.

In the Auth0 case, here are the steps to follow :

add app metadata to a user daikokuAdmin with true as value
create a new custom action in auth0 :

exports.onExecutePostLogin = async (event, api) => {
  const { daikokuAdmin } = event.user.app_metadata;

  if (event.authorization) {
    api.idToken.setCustomClaim(`daikokuAdmin`, daikokuAdmin);
  }
};

deploy it

Create authentication configuration

Go ahead and navigate to your Daikoku home page
Click on the your avatar on bottom left of the screen
Then <your-tenant-name> settings
Then Authentication on left panel
You must be on <your-domain>/settings/settings/authentication
This page show the settings for the current authentication mode (by default Local)
Click on OAuth2 at the top of the form
Enable Read profile from JWT token
Fill Token scope with openid profile name email picture
Fill Client Id with the client ID provided by Auth0
Fill Client Secret with the client secret provided by Auth0
Fill Authorize URL with https://<your-auth0-tenant>.eu.auth0.com/authorize
Fill Token URL with https://<your-auth0-tenant>.eu.auth0.com/oauth/token
Fill Userinfo URL with https://<your-auth0-tenant>.eu.auth0.com/userinfo
Fill Login URL with https://<your-auth0-tenant>.eu.auth0.com/authorize
Fill Logout URL with https://<your-auth0-tenant>.eu.auth0.com/oidc/logout?redirectTo=${redirect}&client_id=${clientId}
Fill Callback URL with http://localhost:9000/auth/oauth2/callback
Fill Access token field name with access_token
Fill Name field name with name
Fill Email field name with email
Fill Picture field name with picture

Two optional fields can be filled :

Email of Daikoku Admins is a white list of Daikoku admins if you don't want use user metadata to setup admins
jwt verifier can be use to verify the JWT token received by Daikoku. According to the selected algorithm, the validation form will change.
- mac + SHA
  - SHA Size: Word size for the SHA-2 hash function used
  - Hmac secret: used to verify the token
  - Base64 encoded secret: if enabled, the extracted token will be base64 decoded before it is verifier
- RSASSA-PKCS1 + SHA
  - SHA Size: Word size for the SHA-2 hash function used
  - Public key: the RSA public key
  - Private key: the RSA private key that can be empty if not used for JWT token signing
- JWK Set (only for verification)
  - URL: the JWK set URL where the public keys are exposed
  - HTTP call timeout: timeout for fetching the keyset
  - TTL: cache TTL for the keyset
  - HTTP Headers: the HTTP headers passed
  - Key type: type of the key searched in the jwks

Role-based access control

You can restrict access to Daikoku based on the user's roles provided by the OAuth2/OIDC provider. Three optional fields are available for this:

Role claim name: the name of the claim in the ID token that contains the user's roles (e.g. role, roles, groups).
Admin role: the role value that grants Daikoku administrator access (e.g. daikoku-admin). Users with this role will be Daikoku admins.
User role (optional): the role value that grants standard user access (e.g. daikoku-user).

If Role claim name and Admin role are configured, Daikoku will look at the user's roles from the ID token to determine whether the user is an admin or a regular user.

If User role is also set, users who have neither the admin role nor the user role will be rejected at login with a clear error message. If User role is left empty, any authenticated user without the admin role will be allowed as a standard user (same behavior as before).

tip

This is useful when your OAuth2 provider manages roles (e.g. via groups or scopes) and you want to restrict which users can access Daikoku.

Logout URL

The Logout URL field configures where the user is redirected after logging out, in order to also terminate the session on the OAuth2/OIDC provider side.

You can use the following placeholders in the URL:

${redirect} — replaced by the Daikoku root URL (post-logout redirect)
${clientId} — replaced by the OAuth2 client ID
${idTokenHint} — replaced by the user's ID token (required by some providers like Duende IdentityServer)

Example for Auth0:

https://<auth0-tenant>/oidc/logout?redirectTo=${redirect}&client_id=${clientId}

Example for a standard OIDC provider (Keycloak, Duende, etc.):

https://<provider>/connect/endsession?id_token_hint=${idTokenHint}&post_logout_redirect_uri=${redirect}&client_id=${clientId}

OIDC Discovery

When using the OIDC Discovery feature (by providing a well-known configuration URL), the logout URL is automatically built from the end_session_endpoint advertised by the provider. The placeholders ${idTokenHint}, ${redirect} and ${clientId} are appended automatically if the discovered URL does not already contain them.

Since v18.7.0

The Logout URL field is now optional. If left empty (e.g. when the provider does not expose an end_session_endpoint, like some PingFederate configurations), Daikoku will simply clear the local session and redirect the user to the home page without calling the provider's logout endpoint.

Testing your configuration

Disconnect from your instance Then click on the Login button (or navigate to <your-daikoku-domain>/login) You can now login with a user setup with the auth module.

Before starting
Running an openldap server
Create an Authentication configuration
Testing your configuration
Before starting
Running an otoroshi server
Create an authentication module
Expose your daikoku by Otoroshi
Create an Authentication configuration
Testing your configuration
Before starting
Configure an Auth0 client
Create authentication configuration
Role-based access control
Logout URL
Testing your configuration

Before starting​

Running an openldap server​

Create an Authentication configuration​

Testing your configuration​

Before starting​

Running an otoroshi server​

Create an authentication module​

Expose your daikoku by Otoroshi​

Create an Authentication configuration​

Testing your configuration​

Before starting​

Configure an Auth0 client​

Create authentication configuration​

Role-based access control​

Logout URL​

Testing your configuration​

Before starting

Running an openldap server

Create an Authentication configuration

Testing your configuration

Before starting

Running an otoroshi server

Create an authentication module

Expose your daikoku by Otoroshi

Create an Authentication configuration

Testing your configuration

Before starting

Configure an Auth0 client

Create authentication configuration

Role-based access control

Logout URL

Testing your configuration