> For the complete documentation index, see [llms.txt](https://documentation.ocsinventory-ng.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ocsinventory-ng.org/administrator-docs/server-setup/configuration/basics/authentication.md). # Authentication OCS allows authentication to be made from multiple sources. The system supports four authentication methods, which can be configured to meet your organization's needs. *** ## Supported authentication methods OCS currently supports the following authentication methods: | Method | Type | Description | | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- | | Local | Standard | Classic Django authentication. Users are created and managed locally within OCS. | | LDAP | Standard | Connect to an LDAP compatible directory server to authenticate users. Supports multiple configurations with fallback. | | OIDC | SSO | OpenID Connect protocol. | | CAS | SSO | Central Authentication Service. | ## Authentication selection process When a user attempts to log in, OCS follows these steps to determine how authentication is handled: #### 1. Checking enabled methods OCS first checks which authentication methods are enabled. If **no methods are enabled**, the system will display an error and prevent login. #### 2. SSO vs. Standard methods * If an **SSO method (OIDC or CAS) is enabled:** The user is presented with an SSO login option. Only one SSO method can be active at a time: if both OIDC and CAS are configured, you must choose which one to enable. * If configured for **auto-redirect**, the user is automatically redirected to the SSO provider. * If **auto-redirect is disabled**, a login button is displayed allowing the user to choose when to redirect. * If only **standard methods are enabled (Local and/or LDAP):** The user sees the usual login form. Credentials are checked in order of priority: 1. **Local authentication** is checked first (if enabled), unless LDAP has been given higher priority. 2. **LDAP authentication** is checked next (if enabled). If LDAP is configured with multiple configurations, each configuration is tried in order until one succeeds. #### 3. Priority and fallback For non-SSO methods, a **priority system** determines the order in which authentication sources are checked: * Lower priority numbers are checked first. * If the first method fails, the next method in priority order is attempted. * This allows for fallback options (e.g., if your primary LDAP server is unavailable, a secondary LDAP configuration or Local authentication can take over). {% hint style="info" %} If **SSO auto-redirect** is enabled but you need to access the login form or alternate authentication methods, you can bypass auto-redirect by appending `?noAUTO=1` to the login URL: ``` https:///login?noAUTO=1 ``` {% endhint %} ## Configuration Authentication methods are managed through the OCS admin panel. Each method can be independently enabled or disabled, and each supports its own set of configurations. ### Enabling/disabling a method Configuration for all authentication methods can be found under **Configurations** **→ General → Authentication**. You'll need to first enable the method before accessing its tab. ### Configurations options by method
Local **Local authentication** requires no additional configuration beyond enabling it. Users can be created directly in OCS using the [user](/administrator-docs/server-setup/configuration/basics/users.md#user-creation) management interface.
LDAP LDAP allows OCS to authenticate users against an LDAP-compatible directory server such as Active Directory or OpenLDAP. For LDAP authentication issues, review [Troubleshooting](/administrator-docs/server-setup/troubleshooting.md#log-files). {% hint style="info" %} You can define multiple LDAP configurations (e.g., primary and backup servers). Each configuration is attempted in priority order until one succeeds. {% endhint %} **Required configuration fields:** | **Name** | Name of the configuration (allows you to differentiate) | `Default LDAP configuration` | | -------------------- | ------------------------------------------------------- | ----------------------------------------------------------- | | **Description** | Brief description field for any additional details | `This is our default LDAP configuration` | | **Server URI** | The LDAP server address and port | `ldap://ad.company.com:389` or `ldaps://ad.company.com:636` | | **Bind DN** | Credentials to authenticate to the LDAP server | `CN=ServiceAccount,CN=Users,DC=company,DC=com` | | **Bind Password** | Password for the bind account | `***` | | **Base DN** | The LDAP branch under which users are searched | `CN=Users,DC=company,DC=com` | | **User Login Field** | The LDAP attribute used as the username | `sAMAccountName` | | **Protocol Version** | LDAP protocol version | `2` or `3` | | **Activate** | Enable or not this configuration | True |
OIDC OIDC enables SSO through a modern identity provider such as Keycloak, Azure AD, etc. For OIDC authentication issues, review [Troubleshooting](/administrator-docs/server-setup/troubleshooting.md#log-files). {% hint style="info" %} Only one SSO method (OIDC or CAS) can be enabled at a time. {% endhint %} **Required configuration fields:** | **PROXY** | Proxy server URL for requests to the OIDC provider | Empty or `http://proxy.company.com:8080` | | --------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------ | | **SCOPES** | Requested permission scopes from the provider | `profile openid email` | | **CLIENT\_ID** | Identifier for OCS in the OIDC provider | `ocs-app` | | **SIGN\_ALGO** | Algorithm used by the provider to sign ID tokens | `RS256` | | **AUTO\_REDIRECT** | Whether to automatically redirect users to the provider on login | `true` or `false` | | **CLIENT\_SECRET** | Secret key for secure communication with the provider | `***` | | **JWKS\_ENDPOINT** | URL to retrieve public keys for token verification | `https://auth.provider.org/protocol/openid-connect/certs` | | **TOKEN\_ENDPOINT** | URL to exchange authorization code for tokens | `https://auth.provider.org/protocol/openid-connect/token` | | **USERINFO\_ENDPOINT** | URL to retrieve user information | `https://auth.provider.org/protocol/openid-connect/userinfo` | | **AUTHORIZATION\_ENDPOINT** | URL where users are redirected to log in | `https://auth.provider.org/protocol/openid-connect/auth` | | **LOGOUT\_ENDPOINT** | URL where users are redirected to log out if SLO is enabled | `https://auth.provider.org/protocol/openid-connect/logout` | | **SLO\_ENABLED** | Whether users should be logged out using Single Logout | `true` or `false` |
CAS For CAS authentication issues, review [Troubleshooting](/administrator-docs/server-setup/troubleshooting.md#log-files). {% hint style="info" %} Only one SSO method (OIDC or CAS) can be enabled at a time. {% endhint %} **Required configuration fields:** | Field | Description | Example | | ------------------ | ------------------------------------------------------------------ | ---------------------------------------- | | **VERSION** | CAS protocol version | `v2` or `v3` | | **SERVER\_URL** | Base URL of the CAS server | `http://auth.provider.org/protocol/cas/` | | **LOGIN\_ROUTE** | The login endpoint path on the CAS server | `login` | | **LOGOUT\_ROUTE** | The logout endpoint path on the CAS server | `logout` | | **AUTO\_REDIRECT** | Whether to automatically redirect users to the CAS server on login | `true` or `false` | | **SLO\_ENABLED** | Whether users should be logged out using Single Logout | `true` or `false` |
## Field mapping When a user successfully authenticates through LDAP, OIDC, or CAS, OCS retrieves user information from the provider. Field mappings determine which provider fields populate which OCS user fields. #### Common mappings | Provider Field | OCS User Field | | --------------------------- | -------------- | | `mail` or `email` | `email` | | `sAMAccountName` or `uid` | `username` | | `givenName` or `given_name` | `first_name` | | `sn` or `family_name` | `last_name` | ### Configuring field mappings {% stepper %} {% step %} When examining the configuration for a method, locate the **gear icon** button and click it. {% endstep %} {% step %} Fill the form. Refer yourself to [#common-mappings](#common-mappings "mention") for examples. {% endstep %} {% step %} Click **Save**. {% endstep %} {% endstepper %} {% hint style="info" %} OCS does not validate provider field names at configuration time. Ensure field names match your provider's schema exactly. If a field is misspelled or does not exist, the mapping will fail silently. {% endhint %} ### Configuring token lifetime Once a user logs in, OCS Inventory Server issues an authentication token. Two settings in the server's `.env` file control how long that token stays valid and whether it renews itself automatically. | Variable | Default | Description | | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | | `TOKEN_TTL` | `10` | How long an authentication token stays valid, in hours. | | `TOKEN_AUTO_REFRESH` | `True` | Whether the token is automatically refreshed while the user is active, extending the session instead of requiring a new login. | ```bash TOKEN_TTL=10 TOKEN_AUTO_REFRESH=True ``` #### `TOKEN_TTL` This sets the maximum lifetime of a token, in hours, from the moment it's issued. Once that time has passed, the token is no longer accepted and the user is asked to log in again. * A **shorter** value reduces how long a stolen or leaked token stays usable, at the cost of asking users to log in more often. * A **longer** value is more convenient for users, but keeps a token valid for a longer window if it's ever compromised. #### `TOKEN_AUTO_REFRESH` When set to `True`, the token is automatically renewed while the user remains active, so an active session doesn't get interrupted by `TOKEN_TTL` expiring mid-use. When set to `False`, the token strictly expires after `TOKEN_TTL` hours regardless of activity, and the user has to log in again once it does. #### Applying the change After editing `.env`, restart the backend service for the new values to take effect. ## Limitations * **Only one SSO method at a time:** If you have both OIDC and CAS configured, only one can be enabled simultaneously. If you need to switch between them, disable one and enable the other. * **No simultaneous SSO auto-redirect and standard methods:** When an SSO method is enabled, users must use SSO to log in. Standard authentication methods (Local, LDAP) are available as fallback but are not presented to users if SSO is active. * **Field mapping validation:** Provider field names are not validated when creating mappings. Verify field names against your provider's documentation to avoid mapping errors. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.ocsinventory-ng.org/administrator-docs/server-setup/configuration/basics/authentication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.