Skip to main content

Authentication modules

Overview​

Authentication modules allow Otoroshi to centralize user authentication in a single place, so that your backend services do not have to implement login flows themselves. Otoroshi acts as an authentication proxy: it intercepts incoming requests, verifies user identity through a configured identity provider, and forwards authenticated requests to your services. This offloads the entire login complexity -- session management, token exchange, protocol handling -- from your applications.

Two authentication contexts​

Authentication modules serve two distinct purposes in Otoroshi:

  • Back-office authentication: Controls who can access the Otoroshi admin UI. A global setting defines which auth module administrators must use to log in. This secures the management console where routes, API keys, certificates, and all other entities are configured.

  • Private apps authentication: Protects user-facing routes. When a route has the Authentication plugin enabled, it becomes a private app -- any unauthenticated user hitting that route is automatically redirected to a login page. After successful authentication, the user is redirected back to the original URL with a valid session. This lets you add authentication to any HTTP service without modifying its code.

How auth modules connect to other entities​

  • Routes: A route becomes a private app by adding the Authentication plugin (or MultiAuthModule for multiple providers) to its plugin chain. The plugin references an auth module by its ID.
  • Global config: The back-office auth module is configured globally, determining which identity provider administrators must use.
  • User sessions: Once a user authenticates, Otoroshi creates a session (stored as a cookie) and can pass user identity information downstream to your services through the Otoroshi claim token.
  • User validators: After successful login, validators can further restrict access based on the user's profile content (email, groups, custom attributes), enabling fine-grained authorization on top of authentication.

Supported authentication protocols​

Otoroshi supports several authentication protocols. The choice depends on your identity infrastructure:

  • OAuth 2.0/2.1 (OIDC): The recommended choice for modern single sign-on (SSO). Use it to integrate with providers like Keycloak, Auth0, Azure AD, Google, or any OpenID Connect-compliant identity provider. Supports PKCE, token refresh, and token introspection.
  • OAuth 1.0a: The original OAuth standard for access delegation. Use it when integrating with services that have not migrated to OAuth 2.0 (e.g., some legacy Twitter/X APIs).
  • LDAP: Connect to enterprise directory servers (Active Directory, OpenLDAP) to authenticate users against their corporate credentials. Ideal when your organization manages identities in an LDAP directory and you want direct integration without an intermediary identity provider.
  • SAML v2: An XML-based federation standard commonly used in enterprise environments. Use it when integrating with identity providers that only support SAML (e.g., legacy enterprise SSO systems, ADFS, or Shibboleth).
  • In-memory: Define users directly within Otoroshi with passwords, rights, and metadata. Useful for development, testing, or small deployments where an external identity provider is not needed. Also supports WebAuthn login.
  • WASM: Delegate the entire authentication logic to a WebAssembly plugin for fully custom authentication flows.

Common configuration fields​

All authentication modules have a unique id, a name and a description.

Each module has also the following fields :

  • Tags: list of tags associated to the module
  • Metadata: list of metadata associated to the module
  • HttpOnly: if enabled, the cookie cannot be accessed through client side script, prevent cross-site scripting (XSS) by not revealing the cookie to a third party
  • Secure: if enabled, avoid to include cookie in an HTTP Request without secure channel, typically HTTPs.
  • Session max. age: duration until the session expired
  • User validators: a list of validator that will check if, a user that successfully logged in has the right to actually, pass otoroshi based on the content of it's profile. A validator is composed of a JSONPath that will tell what to check and a value that is the expected value. The JSONPath will be applied on a document that will look like
{
    "_loc": {
        "tenant": "default",
        "teams": [
            "default"
        ]
    },
    "randomId": "xxxxx",
    "name": "john.doe@otoroshi.io",
    "email": "john.doe@otoroshi.io",
    "authConfigId": "xxxxxxxx",
    "profile": { // the profile shape depends heavily on the identity provider
        "sub": "xxxxxx",
        "nickname": "john.doe",
        "name": "john.doe@otoroshi.io",
        "picture": "https://foo.bar/avatar.png",
        "updated_at": "2022-04-20T12:57:39.723Z",
        "email": "john.doe@otoroshi.io",
        "email_verified": true,
        "rights": ["one", "two"]
    },
    "token": { // the token shape depends heavily on the identity provider
        "access_token": "xxxxxx",
        "refresh_token": "yyyyyy",
        "id_token": "zzzzzz",
        "scope": "openid profile email address phone offline_access",
        "expires_in": 86400,
        "token_type": "Bearer"
    },
    "realm": "global-oauth-xxxxxxx",
    "otoroshiData": {
        ...
    },
    "createdAt": 1650459462650,
    "expiredAt": 1650545862652,
    "lastRefresh": 1650459462650,
    "metadata": {},
    "tags": []
}

the expected value support some syntax tricks like

  • Not(value) on a string to check if the current value does not equals another value
  • Regex(regex) on a string to check if the current value matches the regex
  • RegexNot(regex) on a string to check if the current value does not matches the regex
  • Wildcard(*value*) on a string to check if the current value matches the value with wildcards
  • WildcardNot(*value*) on a string to check if the current value does not matches the value with wildcards
  • Contains(value) on a string to check if the current value contains a value
  • ContainsNot(value) on a string to check if the current value does not contains a value
  • Contains(Regex(regex)) on an array to check if one of the item of the array matches the regex
  • ContainsNot(Regex(regex)) on an array to check if one of the item of the array does not matches the regex
  • Contains(Wildcard(*value*)) on an array to check if one of the item of the array matches the wildcard value
  • ContainsNot(Wildcard(*value*)) on an array to check if one of the item of the array does not matches the wildcard value
  • Contains(value) on an array to check if the array contains a value
  • ContainsNot(value) on an array to check if the array does not contains a value

for instance to check if the current user has the right two, you can write the following validator

{
  "path": "$.profile.rights",
  "value": "Contains(two)"
}

OAuth 2.0 / OIDC provider​

If you want to secure an app or your Otoroshi UI with this provider, you can check these tutorials : Secure an app with keycloak or Secure an app with auth0

  • Use cookie: If your OAuth2 provider does not support query param in redirect uri, you can use cookies instead
  • Use json payloads: the access token, sended to retrieve the user info, will be pass in body as JSON. If disabled, it will sended as Map.
  • Enabled PKCE flow: This way, a malicious attacker can only intercept the Authorization Code, and they cannot exchange it for a token without the Code Verifier.
  • Disable wildcard on redirect URIs: As of OAuth 2.1, query parameters on redirect URIs are no longer allowed
  • Refresh tokens: Automatically refresh access token using the refresh token if available
  • Read profile from token: if enabled, the user profile will be read from the access token, otherwise the user profile will be retrieved from the user information url
  • Super admins only: All logged in users will have super admins rights
  • Client ID: a public identifier of your app
  • Client Secret: a secret known only to the application and the authorization server
  • Authorize URL: used to interact with the resource owner and get the authorization to access the protected resource
  • Token URL: used by the application in order to get an access token or a refresh token
  • Introspection URL: used to validate access tokens
  • Userinfo URL: used to retrieve the profile of the user
  • Login URL: used to redirect user to the login provider page
  • Logout URL: redirect uri used by the identity provider to redirect user after logging out
  • Callback URL: redirect uri sended to the identity provider to redirect user after successfully connecting
  • Access token field name: field used to search access token in the response body of the token URL call
  • Scope: presented scopes to the user in the consent screen. Scopes are space-separated lists of identifiers used to specify what access privileges are being requested
  • Claims: asked name/values pairs that contains information about a user.
  • Name field name: Retrieve name from token field
  • Email field name: Retrieve email from token field
  • Otoroshi metadata field name: Retrieve metadata from token field
  • Otoroshi rights field name: Retrieve user rights from user profile
  • Extra metadata: merged with the user metadata
  • Data override: merged with extra metadata when a user connects to a private app
  • Rights override: useful when you want erase the rights of an user with only specific rights. This field is the last to be applied on the user rights.
  • Api key metadata field name: used to extract api key metadata from the OIDC access token
  • Api key tags field name: used to extract api key tags from the OIDC access token
  • Proxy host: host of proxy behind the identify provider
  • Proxy port: port of proxy behind the identify provider
  • Proxy principal: user of proxy
  • Proxy password: password of proxy
  • OIDC config url: URI of the openid-configuration used to discovery documents. By convention, this URI ends with .well-known/openid-configuration
  • Token verification: What kind of algorithm you want to use to verify/sign your JWT token with
  • SHA Size: Word size for the SHA-2 hash function used
  • Hmac secret: The Hmac secret
  • Base64 encoded secret: Is the secret encoded with base64
  • Custom TLS Settings: TLS settings for JWKS fetching
  • TLS loose: if enabled, will block all untrustful ssl configs
  • Trust all: allows any server certificates even the self-signed ones
  • Client certificates: list of client certificates used to communicate with JWKS server
  • Trusted certificates: list of trusted certificates received from JWKS server

OAuth 1.0a provider​

If you want to secure an app or your Otoroshi UI with this provider, you can check this tutorial : Secure an app with OAuth 1.0a

  • Http Method: method used to get request token and the access token
  • Consumer key: the identifier portion of the client credentials (equivalent to a username)
  • Consumer secret: the identifier portion of the client credentials (equivalent to a password)
  • Request Token URL: url to retrieve the request token
  • Authorize URL: used to redirect user to the login page
  • Access token URL: used to retrieve the access token from the server
  • Profile URL: used to get the user profile
  • Callback URL: used to redirect user when successfully connecting
  • Rights override: override the rights of the connected user. With JSON format, each authenticated user, using email, can be associated to a list of rights on tenants and Otoroshi teams.

LDAP Authentication provider​

If you want to secure an app or your Otoroshi UI with this provider, you can check this tutorial : Secure an app with LDAP

  • Basic auth.: if enabled, user and password will be extract from the Authorization header as a Basic authentication. It will skipped the login Otoroshi page
  • Allow empty password: LDAP servers configured by default with the possibility to connect without password can be secured by this module to ensure that user provides a password
  • Super admins only: All logged in users will have super admins rights
  • Extract profile: extract LDAP profile in the Otoroshi user
  • LDAP Server URL: list of LDAP servers to join. Otoroshi use this list in sequence and swap to the next server, each time a server breaks in timeout
  • Search Base: used to global filter
  • Users search base: concat with search base to search users in LDAP
  • Mapping group filter: map LDAP groups with Otoroshi rights
  • Search Filter: used to filter users. ${username} is replace by the email of the user and compare to the given field
  • Admin username (bind DN): holds the name of the environment property for specifying the identity of the principal for authenticating the caller to the service
  • Admin password: holds the name of the environment property for specifying the credentials of the principal for authenticating the caller to the service
  • Extract profile filters attributes in: keep only attributes which are matching the regex
  • Extract profile filters attributes not in: keep only attributes which are not matching the regex
  • Name field name: Retrieve name from LDAP field
  • Email field name: Retrieve email from LDAP field
  • Otoroshi metadata field name: Retrieve metadata from LDAP field
  • Extra metadata: merged with the user metadata
  • Data override: merged with extra metadata when a user connects to a private app
  • Additional rights group: list of virtual groups. A virtual group is composed of a list of users and a list of rights for each teams/organizations.
  • Rights override: useful when you want erase the rights of an user with only specific rights. This field is the last to be applied on the user rights.

In memory provider​

  • Basic auth.: if enabled, user and password will be extract from the Authorization header as a Basic authentication. It will skipped the login Otoroshi page
  • Login with WebAuthn : enabled logging by WebAuthn
  • Users: list of users with name, email and metadata. The default password is password. The edit button is useful when you want to change the password of the user. The reset button reinitialize the password.
  • Users raw: show the registered users with their profile and their rights. You can edit directly each field, especially the rights of the user.

SAML v2 provider​

  • Single sign on URL: the Identity Provider Single Sign-On URL
  • The protocol binding for the login request: the protocol binding for the login request
  • Single Logout URL: a SAML flow that allows the end-user to logout from a single session and be automatically logged out of all related sessions that were established during SSO
  • The protocol binding for the logout request: the protocol binding for the logout request
  • Sign documents: Should SAML Request be signed by Otoroshi ?
  • Validate Assertions Signature: Enable/disable signature validation of SAML assertions
  • Validate assertions with Otoroshi certificate: validate assertions with Otoroshi certificate. If disabled, the Encryption Certificate and Encryption Private Key fields can be used to pass a certificate and a private key to validate assertions.
  • Encryption Certificate: certificate used to verify assertions
  • Encryption Private Key: privaye key used to verify assertions
  • Signing Certificate: certicate used to sign documents
  • Signing Private Key: private key to sign documents
  • Signature al: the signature algorithm to use to sign documents
  • Canonicalization Method: canonicalization method for XML signatures
  • Encryption KeyPair: the keypair used to sign/verify assertions
  • Name ID Format: SP and IdP usually communicate each other about a subject. That subject should be identified through a NAME-IDentifier, which should be in some format so that It is easy for the other party to identify it based on the Format
  • Use NameID format as email: use NameID format as email. If disabled, the email will be search from the attributes
  • URL issuer: provide the URL to the IdP's who will issue the security token
  • Validate Signature: enable/disable signature validation of SAML responses
  • Validate Assertions Signature: should SAML Assertions to be decrypted ?
  • Validating Certificates: the certificate in PEM format that must be used to check for signatures.

Special routes​

when using private apps with auth. modules, you can access special routes that can help you

GET 'http://xxxxxxxx.xxxx.xx/.well-known/otoroshi/logout' # trigger logout for the current auth. module
GET 'http://xxxxxxxx.xxxx.xx/.well-known/otoroshi/me'     # get the current logged user profile (do not forget to pass cookies)

Admin API​

GET    /api/auths           # List all auth modules
POST   /api/auths           # Create an auth module
GET    /api/auths/:id       # Get an auth module
PUT    /api/auths/:id       # Update an auth module
DELETE /api/auths/:id       # Delete an auth module
PATCH  /api/auths/:id       # Partially update an auth module