Authentication modules
The authentication modules manage the access to Otoroshi UI and can protect a route.
A private Otoroshi app
is an Otoroshi route with the Authentication plugin enabled.
The list of supported authentication are :
OAuth 2.0/2.1
: an authorization standard that allows a user to grant limited access to their resources on one site to another site, without having to expose their credentialsOAuth 1.0a
: the original standard for access delegationIn memory
: create users directly in Otoroshi with rights and metadataLDAP : Lightweight Directory Access Protocol
: connect users using a set of LDAP serversSAML V2 - Security Assertion Markup Language
: an open-standard, XML-based data format that allows businesses to communicate user authentication and authorization information to partner companies and enterprise applications their employees may use.
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 moduleMetadata
: list of metadata associated to the moduleHttpOnly
: if enabled, the cookie cannot be accessed through client side script, prevent cross-site scripting (XSS) by not revealing the cookie to a third partySecure
: if enabled, avoid to include cookie in an HTTP Request without secure channel, typically HTTPs.Session max. age
: duration until the session expiredUser 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 valueRegex(regex)
on a string to check if the current value matches the regexRegexNot(regex)
on a string to check if the current value does not matches the regexWildcard(*value*)
on a string to check if the current value matches the value with wildcardsWildcardNot(*value*)
on a string to check if the current value does not matches the value with wildcardsContains(value)
on a string to check if the current value contains a valueContainsNot(value)
on a string to check if the current value does not contains a valueContains(Regex(regex))
on an array to check if one of the item of the array matches the regexContainsNot(Regex(regex))
on an array to check if one of the item of the array does not matches the regexContains(Wildcard(*value*))
on an array to check if one of the item of the array matches the wildcard valueContainsNot(Wildcard(*value*))
on an array to check if one of the item of the array does not matches the wildcard valueContains(value)
on an array to check if the array contains a valueContainsNot(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 insteadUse 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 allowedRefresh tokens
: Automatically refresh access token using the refresh token if availableRead 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 urlSuper admins only
: All logged in users will have super admins rightsClient ID
: a public identifier of your appClient Secret
: a secret known only to the application and the authorization serverAuthorize URL
: used to interact with the resource owner and get the authorization to access the protected resourceToken URL
: used by the application in order to get an access token or a refresh tokenIntrospection URL
: used to validate access tokensUserinfo URL
: used to retrieve the profile of the userLogin URL
: used to redirect user to the login provider pageLogout URL
: redirect uri used by the identity provider to redirect user after logging outCallback URL
: redirect uri sended to the identity provider to redirect user after successfully connectingAccess token field name
: field used to search access token in the response body of the token URL callScope
: presented scopes to the user in the consent screen. Scopes are space-separated lists of identifiers used to specify what access privileges are being requestedClaims
: asked name/values pairs that contains information about a user.Name field name
: Retrieve name from token fieldEmail field name
: Retrieve email from token fieldOtoroshi metadata field name
: Retrieve metadata from token fieldOtoroshi rights field name
: Retrieve user rights from user profileExtra metadata
: merged with the user metadataData override
: merged with extra metadata when a user connects to aprivate 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 tokenApi key tags field name
: used to extract api key tags from the OIDC access tokenProxy host
: host of proxy behind the identify providerProxy port
: port of proxy behind the identify providerProxy principal
: user of proxyProxy password
: password of proxyOIDC 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 withSHA Size
: Word size for the SHA-2 hash function usedHmac secret
: The Hmac secretBase64 encoded secret
: Is the secret encoded with base64Custom TLS Settings
: TLS settings for JWKS fetchingTLS loose
: if enabled, will block all untrustful ssl configsTrust all
: allows any server certificates even the self-signed onesClient certificates
: list of client certificates used to communicate with JWKS serverTrusted 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 tokenConsumer 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 tokenAuthorize URL
: used to redirect user to the login pageAccess token URL
: used to retrieve the access token from the serverProfile URL
: used to get the user profileCallback URL
: used to redirect user when successfully connectingRights 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 theAuthorization
header as a Basic authentication. It will skipped the login Otoroshi pageAllow 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 passwordSuper admins only
: All logged in users will have super admins rightsExtract profile
: extract LDAP profile in the Otoroshi userLDAP 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 timeoutSearch Base
: used to global filterUsers search base
: concat with search base to search users in LDAPMapping group filter
: map LDAP groups with Otoroshi rightsSearch Filter
: used to filter users. ${username} is replace by the email of the user and compare to the given fieldAdmin username (bind DN)
: holds the name of the environment property for specifying the identity of the principal for authenticating the caller to the serviceAdmin password
: holds the name of the environment property for specifying the credentials of the principal for authenticating the caller to the serviceExtract profile filters attributes in
: keep only attributes which are matching the regexExtract profile filters attributes not in
: keep only attributes which are not matching the regexName field name
: Retrieve name from LDAP fieldEmail field name
: Retrieve email from LDAP fieldOtoroshi metadata field name
: Retrieve metadata from LDAP fieldExtra metadata
: merged with the user metadataData override
: merged with extra metadata when a user connects to aprivate 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 theAuthorization
header as a Basic authentication. It will skipped the login Otoroshi pageLogin with WebAuthn
: enabled logging by WebAuthnUsers
: 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 URLThe protocol binding for the login request
: the protocol binding for the login requestSingle 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 SSOThe protocol binding for the logout request
: the protocol binding for the logout requestSign documents
: Should SAML Request be signed by Otoroshi ?Validate Assertions Signature
: Enable/disable signature validation of SAML assertionsValidate assertions with Otoroshi certificate
: validate assertions with Otoroshi certificate. If disabled, theEncryption Certificate
andEncryption Private Key
fields can be used to pass a certificate and a private key to validate assertions.Encryption Certificate
: certificate used to verify assertionsEncryption Private Key
: privaye key used to verify assertionsSigning Certificate
: certicate used to sign documentsSigning Private Key
: private key to sign documentsSignature al
: the signature algorithm to use to sign documentsCanonicalization Method
: canonicalization method for XML signaturesEncryption KeyPair
: the keypair used to sign/verify assertionsName 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 FormatUse NameID format as email
: use NameID format as email. If disabled, the email will be search from the attributesURL issuer
: provide the URL to the IdP’s who will issue the security tokenValidate Signature
: enable/disable signature validation of SAML responsesValidate 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)