api.fabaccess-api/auth.capnp

@0xb9cffd29ac983e9f;

using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");

using import "utils.capnp".L10NString;

struct AuthSupported {
    mechs @0 :List(Mechanism);
    cbtypes @1 :List(Text);
    upgrades @2 :List(Text);
}

struct Mechanism {
    name @0 :Text;
    additionalInfo @1 :AnyPointer;
    # Additional Info for OpenID / OAUTH2
}

struct Response(Successful) {
    enum Reason {
        aborted @0;
        # This authentication exchange was aborted by either side.

        badMechanism @1;
        # The server does not support this mechanism in this context.

        unwilling @2;
        # Generic "I'm sorry dave, I can't do that" response. MAY be set for any reason, all reasons
        # or no reason at all. This code will for example be used if a client is being rate limited.
        # A server SHOULD set the `action` and `description` fields as appropiate.
        # This code SHOULD only be sent if no other value is more fitting.

        invalidCredentials @3;
        # The exchange was valid, but the provided credentials are invalid. This may mean that the
        # authcid is not known to the server or that the password/certificate/key/ticket/etc is not
        # correct.

        unauthorized @4;
        # The given authcid is not authorized to act as the requested authzid.  This MAY also be
        # returned for the cases `authzid == NULL` or `authzid == authcid`, for example because
        # login is disabled for that authcid.

        failed @5;
        # A generic failed result. A server sending this result MUST set the `action` field to
        # indicate whether this is a temporary or permanent failure and SHOULD set `description` to
        # a human-readable error message.
    }
    enum Action {
        # In case of a unsuccessful outcome, how should a client proceed?

        unset @0;
        # The server doesn't know either. A client SHOULD treat this either as as `retry` or as
        # `wait`.

        retry @1;
        # A client SHOULD try again, depending on the `Error` after prompting the user for their
        # credentials once more.

        wait @2;
        # The client SHOULD wait and retry after a grace period. A client MUST wait at least 500ms
        # and SHOULD implement exponential backoff up to no less than 64s.
        # This MAY mean that whatever failure happened was temporary or the server is applying
        # rate-limiting to the connection.

        permanent @3;
        # The issue appears to the server as being permanent. Another try is very likely to return
        # the exact same result. In most cases the user should notify the responsible system
        # administrator. A client SHOULD NOT try to authenticate to the server again until the user
        # manually indicates a retry.
    }

    union {
        error :group {
            # Some kind of error happened. This in the first entry in the union because it is the
            # default set value meaning if a server fails to set any of the values, indicating some
            # pretty severe server bugs, it is parsed as an "aborted" error.

            reason @0 :Reason;
            action @1 :Action;
            description @2 :L10NString;
            # A human-readable error description that is designed to be shown to the user in case of
            # failure. Clients MAY NOT display this message if they understand the error e.g. for
            # the error/action "invalidCredentials/retry".
        }
        challenge @3 :Data;
        # The data provided so far is not enough to authenticate the user. The data MAY be a
        # NULL-ptr or a non-NULL list ptr of zero bytes which clients MUST pass to their SASL
        # implementation as "no data" and "some data of zero length" respectively.
        successful :group {
            # The exchange was successful and a new session has been created for the authzid that
            # was established by the SASL exchange.

            session @4 :Successful;
            # The session that was created. It grants access to all capabilities the connecting
            # party has permissions for.

            additionalData @5 :Data;
            # SASL may send additional data with the successful result. This MAY be a NULL-ptr or a
            # non-NULL list ptr of zero bytes which clients MUST pass to their SASL implementation
            # as "no additional data" and "some additional data of zero length" respectively.
        }
        continue :group {
            # The current authentication exchange was successful, but the client needs to perform 
            # a second round of authentication (e.g.  2FA) to continue.

            tasks @6 :List(Mechanism);
            # List of mechanisms now available to the client. Authentication by those MUST NOT
            # establish a new security layer or set a new authorization id.

            additionalData @7 :Data;
            # SASL may send additional data with the continue result. This MAY be a NULL-ptr or a
            # non-NULL list ptr of zero bytes which clients MUST pass to their SASL implementation
            # as "no additional data" and "some additional data of zero length" respectively.
        }
    }
}

interface Authentication(Successful) {
    mechanisms @3 () -> ( mechanisms :List(Mechanism) );
    # Return the list of available mechanisms

    step @0 ( data :Data ) -> Response(Successful);
    # Respond to a challenge with more data. A client MUST NOT call this after having received an
    # "successful" response.

    abort @1 () -> ();
    # Abort the current exchange. This will invalidate the Authentication making all further calls
    # to `step` return an error response. A client MUST NOT call this function after
    # having received an "successful" response.
    # A server will indicate that they have aborted an authentication exchange by replying with an
    # "aborted" Error to the next `step` call. A server SHOULD directly terminate the underlying stream
    # after sending this response. The server MAY after a short grace period terminate the stream
    # without sending a response if no call to `step` was received by the client.

    nextTask @2 ( mechanism :Text, initialData :Data ) -> Response(Successful);
    # Call this after a continue was returned
}