Project: CyberArk Conjur (Provisioning / Key Management)
File: AUTHENTICATORS.md

Authenticators allow you to customize the user login and authentication methods for Conjur. There are two endpoints used by Conjur to authenticate users and services to the API. '/login' is used to authenticate users with a username and password. This endpoint allows users to initially authenticate with a memorable password and exchange it for an API key. The format of this key is configurable by the authenticator. '/authenticate' is used to authenticate either a user or service and returns a short-lived access token for API requests. Links to the current Authenticator Feature specs: This feature allows the person who configures an authenticator to get immediate feedback on its configuration. If there was a problem during the authenticator configuration process, the reason will be returned to the user so that they can make the necessary changes. Click for more details on this feature. Successful login returns an API key that can be used for authentication. A separate login step allows users to authenticate with a memorable password, while using a random, rotatable access key for actual API authentication. To login, send a `GET` request to: ``` /:authenticator-type/:optional-service-id/:conjur-account/login ``` is used to send the username and password. Let's break down the required pieces of this request: authenticator-type: The default Conjur authenticator type is `authn`, and all other authenticator types begin with the prefix `authn-`. For example, `authn-ldap` or `authn-my-awesome-authenticator`. optional-service-id: This is useful when you have two different "instances" of the same authenticator type. For example, your company might have two LDAP directories, one for system administrators and one for developers. These could both be enabled and accessed at the URLs `/authn-ldap/sysadmins/...` and `/authn-ldap/developers/...`. conjur-account: The Conjur account you'll be issued a token for. username: The username (from the point of view of the authenticator) of the person (or machine) requesting authentication. In the case of default Conjur authentication, this would be your Conjur username. In the case of LDAP authentication, this would be your LDAP username. The plain text response body will contain the API key for the user. Successful authentication returns a new Conjur token, which you can use to make subsequent requests to protected Conjur services. To authenticate and receive this token, `POST` to: ``` /:authenticator-type/:optional-service-id/:conjur-account/:username/authenticate ``` with the key (or other credential relevant to your authenticator) as plain text in the request

The request parameters are the same as login with the addition of: request body: The plain text password or other credential relevant to your authenticator. This could be an ordinary password, an API key, an OAuth token, etc -- depending on the type of authenticator. With the exception of the default Conjur authenticator named `authn`, all authenticators must be explicitly whitelisted via the environment variable `CONJUR_AUTHENTICATORS`. If the environment variable `CONJUR_AUTHENTICATORS` is not set, the default Conjur authenticator will be automatically whitelisted and ready for use. No other authenticators will be available in this case. If the environment variable `CONJUR_AUTHENTICATORS` is set, then only the authenticators listed will be whitelisted. This means that if `CONJUR_AUTHENTICATORS` is set and `authn` is not in the list, default Conjur authentication will not be available. Here is an example `CONJUR_AUTHENTICATORS` which whitelists an LDAP authenticator as well as the default Conjur authenticator: ``` CONJUR_AUTHENTICATORS=authn-ldap/sysadmins,authn ``` Note that this is a comma-separated list. Except for the default Conjur authenticator, authenticators must be listed as webservices in your Conjur policy, and users must be authorized to use them. This requires two steps: Add the authenticator as a webservice in your conjur policy: ```yaml !policy id: conjur/my-authenticator/optional-service-id ``` Add any users that need to access it to your policy, and grant them the `authenticate` privilege. Create a new directory under `/app/domain/authentication`. For example: ``` /app/domain/authentication/my_authenticator ``` That directory must contain a file named `authenticator.rb`, with the following structure: ```ruby module Authentication module MyAuthenticator class Authenticator def initialize(env:) end def login(input) end def valid?(input) end end end end ``` Your authenticator directory can contain other supporting files used by your authenticator. Conjur will instantiate your authenticator at boot up. By default, when your authenticator is instantiated by conjur, it will be passed the `ENV` through the kwarg `env`. If you don't need any configuration from the environment, you can opt out like so: ```ruby module Authentication module MyAuthenticator class Authenticator def self.requiresenvarg? false end def initialize end def valid?(input) end end end end ``` This section should only be relevant to Conjur developers. These are notes on the design of authenticator system itself: The architecture is objects nested like Russian dolls. All dependencies are passed explicitly through the constructor. It also uses `Dry::Struct` quite a bit. You can think of this like an `ostruct` with built-in type checking, which cleans up what would otherwise be verbose validation and initialization code.