Just a second...

Authentication

You can implement and register handlers to authenticate a client when the client connects to Diffusion™ Cloud or changes its principal.

Figure 1. Authentication model A connection request comes in from the client. Authentication handlers are called one after another. Principal, credentials, and session are passed as arguments to the handler's authenticate() method. If any handler returns an ALLOW or DENY response, that is used as the decision. If a handler returns an ABSTAIN response the decision passes to the next handler in the list. If all handlers return an ABSTAIN response, the connection is denied.
  1. A client tries to connect to Diffusion Cloud or change its principal.
  2. Diffusion Cloud provides the following information about the client session to the authentication handlers:
    Principal
    A String that contains the name of the principal or identity that is connecting to Diffusion Cloud or performing the action. This can have a value of ANONYMOUS.
    Credentials
    The Credentials object contains byte data that holds a piece of information that authenticates the principal. This can be empty or contain a password, a cryptographic key, an image, or any other piece of information. The authentication handler is responsible for interpreting the bytes.
    SessionDetails

    This contains information about the client. The available details depend on what information Diffusion Cloud holds about the client session. Some session information might not be available on initial connection.

    This information can be used in the authentication decision. For example, an authentication handler can only allow connection from clients that connect from a specific country.

    A control authentication handler can specify what details it requires, so only these details are sent by Diffusion Cloud (if available). This reduces the amount of data sent.

    Callback
    A callback that the authentication handler can use to return a decision to Diffusion Cloud by using the callback's allow(), deny(), or abstain() method.
  3. Diffusion Cloud calls authentication handlers in the following order:
    before-system-handler
    An authentication handler that has been registered with Diffusion Cloud using the name "before-system-handler". Use the AuthenticationControl feature of the API to develop and register your authentication handler.
    System authentication handler
    A system authentication handler that uses the information defined in the system administration store to make the decision whether to allow, deny, or abstain from the authentication decision.
    after-system-handler
    An authentication handler that has been registered with Diffusion Cloud using the name "after-system-handler". Use the AuthenticationControl feature of the API to develop and register your authentication handler.

    If multiple authentication handlers are registered against the same name, for example – "before-system-handler", only one of these authentication handlers is called. Diffusion Cloud load balances the authentication requests across all authentication handlers registered against the same name.

    If you want to call multiple authentication handlers at the "before-system-handler" or "after-system-handler" stage, use a composite authentication handler to call multiple handlers and aggregate the decisions.

  4. Each authentication handler can decide to ALLOW, DENY, or ABSTAIN the authentication.
    • If the authentication handler returns ALLOW, the client is allowed to connect to Diffusion Cloud or change principal. The authentication handler can also provide a list of roles to assign to the client session.
    • If the authentication handler returns DENY, the client is allowed to connect to the server or change principal.
    • If the authentication handler returns ABSTAIN, the decision is passed to the next authentication handler.
  5. If all authentication handlers respond with an ABSTAIN decision, the response defaults to DENY.

Where to register your custom authentication handlers

Your custom authentication handlers can be called before or after the system authentication handler, depending on whether they are registered as before-system-handler or after-system-handler. When deciding where to register your custom handlers, consider the following factors:

The system authentication handler stores a one-way hash derived from the password. For each authentication attempt, a hash of the provided password is calculated, which requires server CPU. If you are using a custom authentication handler to authenticate the majority of sessions, you might reduce the CPU load on the server by configuring the custom handler before the system authentication handler.

The system authentication handler and system authentication store are intended to be used to authenticate a small number of principals, for example, administrative users and control clients. If you have more than 100 principals, administering them through the System Users table and system authentication store can be difficult. To authenticate a large number of principals, instead use an external credentials repository and develop an authentication handler that accesses the repository.

If you have a large number of anonymous connections, you can reduce the calls the Diffusion Cloud makes to your custom authentication handlers by calling them after the system authentication handler is called. For the anonymous sessions, the authentication decision defined in the system authentication store is applied and the network round trip required to call the custom authentication handler is avoided.