Project: CyberArk Conjur (Provisioning / Key Management)
File: authn-status-new-implem.md

The authenticator status APIallows operators to get immediate feedback on the authenticator configuration. Once the configuration of an authenticator is complete, the operator sends a status request and the status of the given authenticator is returned. If the configuration was successful, the response received will reflect this. If not, an error will be provided in the response, identifying the step of failure. The first authenticator to utilize this feature is Authn OpenID Connect. For more information about the design behind the Status API and implementation details see the . It is advised that you read the epic before expanding status to other authenticators. For a complete status flow This doc describes how to expand the status functionality to other authenticators. For each authenticator, a suite of checks are run followed by those specific to the authenticator. General checks are outlined below and steps that require developer intervention to implement and enable status for authenticators are italicized accordingly. The requesting user has access to the authenticator status webservice See the security section for more info about this webservice The authenticator implements the status method The account exists The webservice exists The authenticator is enabled in the ENV Checks specific requirements for the new authenticator To properly implement the status functionality in the new authenticator, you will need to expand on italicized checks 2 and 6. As described in step 2, the status of an authenticator method is checked for implementation. Therefore, you will need to add a status method to the Authenticator class (`Authentication::Authn<Type>::Authenticator`) like so: ```ruby def status(authenticatorstatusinput:) Authentication::Authn<Type>::ValidateStatus.new.call( <ValidateStatus input> ) end ``` NOTE: It is important to keep the `Authn<Type>` pattern when defining the class structure. The `authenticatorstatusinput` object wraps a group of fields that may be needed by authenticators to perform their configuration checks. Each authenticator may require different variations of the provided fields. The fields in the `authenticatorstatusinput` object include: `authenticator_name`- type of authenticator, for example authn-oidc `service_id`- ID of the authenticator provider, for example Okta `account`- name of organization `username`- name of the user who sent the status request `webservice`- resource for the authenticator `status_webservice`- resource for the authenticator's status endpoint See below for an example of the for OIDC. Notice how this particular status implementation uses only the `account` and `serviceid` fields from the `authenticatorstatus_input` object. ```ruby def status(authenticatorstatusinput:) Authentication::AuthnOidc::ValidateStatus.new.call( account: authenticatorstatusinput.account, serviceid: authenticatorstatusinput.serviceid ) end end ``` This status method will call the ValidateStatuss CommandClass and run the new authenticator-specific checks as described in step 6. This new ValidateStatus CommandClass should be in the structure of `Authentication::Authn<Type>::ValidateStatus` and will need to be in a format similar to: ```ruby module Authentication module Authn<Type> Err = Errors::Authentication::Authn<Type> ValidateStatus = CommandClass.new( dependencies: { }, inputs: %i() ) do def call specificauthncheck1 specificauthncheck2 . . end private def specificauthncheck1 end def specificauthncheck2 end end end end ``` NOTE: It is important to keep the `Authn<Type>` pattern when defining the class structure. NOTE: For an example of an Authenticator ValidateStatus CommandClass see All new status implementations should inspire a new suite of unit and integration tests appropriate for that authenticator. The response from each test should be consistent with previous status implementations. For example: A successful response: ```json { "status": "ok" } ``` A failure: ```json { "status": "error", "error": "<configuration_error>" } ``` An example of an error response resulting from an incorrect configuration of the authenticator: ```json { "status": "error", "error": "#<Errors::Authentication::AuthenticatorNotSupported: CONJ00001E Authenticator 'Authn<Type>' is not implemented in Conjur>" } ``` *NOTE:* All new errors should be placed in the `error.rb` and be referenced in the tests as displayed above.