CETAN Documentation

Authentication

CETAN supports multiple authentication mechanisms for securing web resources. Authentication consists of three components:

• An optional Identity Provider (IDP)
• An authentication scheme
• A protect_resources declaration

These components work together to validate user credentials, API keys, or JWT tokens before granting access to protected URLs.

How authentication is structured

The example below shows all three declarations working together:

<cetan_server>
  ...
  <idps>
    <idp name="cetan_basic_idp">
      <type>BasicFile</type>
      <lockout_time>100</lockout_time>
      <safe_idp_key>idp_key</safe_idp_key>
      <display_name>basic_idp</display_name>
      <max_failed_attempt>3</max_failed_attempt>
      <file_name>cetan_basic_account.txt</file_name>
    </idp>
  </idps>

  <auths>
    <authn name="cetan_basic_file_authn">
      <type>Basic</type>
      <idp>cetan_basic_idp</idp>
    </authn>
  </auths>

  <protect_resources>
    <uris>/</uris>
    <authn>cetan_basic_file_authn</authn>
  </protect_resources>
  ...
</cetan_server>

protect_resources references an authn entry, which in turn references an IDP. Removing protect_resources disables web authentication entirely.

Multiple IDPs and authentication schemes may be declared, but only one IDP and one authn entry are used per protected resource.

Identity Providers (IDPs)

CETAN supports the following IDP types:

• LDAP
• BasicFile
• KeyFile

LDAP IDP

<idp name="cetan_ldap">
  <type>LDAP</type>
  <lockout_time>100</lockout_time>
  <url>ldaps://ldap.cetan.io</url>
  <bind_attribute>uid</bind_attribute>
  <max_failed_attempt>3</max_failed_attempt>
  <base_dn>ou=People,dc=cetan,dc=io</base_dn>
  <admin_dn>cn=admin,dc=cetan,dc=io</admin_dn>
  <safe_admin_key>ldap_admin_key</safe_admin_key>
</idp>

• name — IDP name (required)
• type — must be LDAP
• url — LDAP server URL
• bind_attribute + base_dn form the Bind DN
• admin_dn — required if anonymous bind is not allowed
• safe_admin_key — Safe entry containing the admin password

Create the Safe entry:

bin/safe add -n security/cetan.safe -e ldap_admin_key

BasicFile IDP

BasicFile IDP stores user accounts in a text file using the format: uid;password_hmac;salt

<idp name="cetan_basic_idp">
  <type>BasicFile</type>
  <salt_size>24</salt_size>
  <lockout_time>100</lockout_time>
  <display_name>basic_idp</display_name>
  <hash_algorithm>SHA3-256</hash_algorithm>
  <max_failed_attempt>3</max_failed_attempt>
  <file_name>cetan_basic_account.txt</file_name>
  <safe_idp_key>basic_idp_key</safe_idp_key>
</idp>

• file_name — user account file
• hash_algorithm — default is SHA3‑256
• safe_idp_key — Safe entry containing the IDP key

Create the IDP key:

bin/safe gen-password -length 32
bin/safe add -n security/cetan.safe -e basic_idp_key

Adding users to BasicFile IDP

Using CETAN CLI:

bin/cetan add-user -idp-name cetan_basic_idp -uid user_uid

Manual method:

1. Generate salt: bin/safe gen-salt -length 24
2. Compute HMAC: bin/safe compute-hmac
3. Retrieve IDP key: bin/safe get -n security/cetan.safe -e basic_idp_key
4. Add record to file: uid;base64_hmac;base64_salt

KeyFile IDP

<idp name="cetan-api-key">
  <type>KeyFile</type>
  <key_size>64</key_size>
  <display_name>APIKey</display_name>
  <file_name>cetan_api_key.txt</file_name>
  <safe_idp_key>idp_api_key</safe_idp_key>
</idp>

Create the IDP key:

bin/safe gen-password -length 64
bin/safe add -n security/cetan.safe -e idp_api_key

Add API keys:

bin/cetan add-api-key

Authentication schemes

CETAN supports two authentication types:

• Basic — username/password
• Bearer — API keys or JWT tokens

Basic Authentication

<authn name="cetan_basic_file_authn">
  <type>Basic</type>
  <idp>cetan_basic_idp</idp>
</authn>

Bearer Authentication

Bearer tokens may be API keys or JWT tokens.

API Key example:

<authn name="cetan_key_bearer">
  <type>Bearer</type>
  <token>apikey</token>
  <idp>cetan-api-key</idp>
</authn>

JWT (HMAC) example:

<authn name="cetan_jwt_HS256_bearer">
  <type>Bearer</type>
  <token>jwt</token>
  <verify>HMAC</verify>
  <safe_key>HS256_secret</safe_key>
</authn>

JWT (RSA/EC/PS/EdDSA) examples:

<authn name="cetan_jwt_RS256_bearer">
  <type>Bearer</type>
  <token>jwt</token>
  <verify>signature</verify>
  <cert_file>jwt_rs256_public_key.pem</cert_file>
</authn>

Protecting resources

Use protect_resources to secure specific URL paths:

<protect_resources>
  <uris>/</uris>
  <authn>cetan_basic_ldap_authn</authn>
</protect_resources>

• uris — comma‑separated list of protected paths
• authn — authentication scheme name

Save and restart

After updating cetan_config.xml, restart the CETAN server for authentication changes to take effect.