.. _mds-api: Confluent Metadata API Reference ================================ The Confluent Metadata API has many endpoints, conceptually grouped as follows: **Authentication** Authenticates users against LDAP and returns user bearer tokens that can be used with the other MDS endpoints and components in |cp| (when configured to do so). **Authorization** Authorizes users to perform specific actions. Clients are not expected to use these endpoints, which are used by |cp| components (such as Connect and |ksqldb|) to authorize user actions. **Role Based Access Control** * Role binding CRUD * Role binding summaries (used by Confluent CLI) * High-level role binding management and rollups (used by |c3|) **Centralized ACL Control** * With :ref:`authorization-acl-with-mds` |cp| provides the option to store ACLs in |ak| instead of |zk| * ACL CRUD for legacy |ak|-managed and centralized MDS-based ACLs **Audit Log Configuration** Configuration governing which events get logged, and where those audit log events are sent. Works in conjunction with the Cluster Registry to push configuration changes to Kafka clusters. **Cluster Registry** Tracking and naming CP components / clusters. * Manually populated and updated by Admins. * Leveraged by the Audit Log configuration. * Leveraged by RBAC APIs to allow for RoleBinding calls to use "nice names" for clusters instead of cluster IDs. .. note:: In all the RBAC CRUD APIs where you used to have to specify cluster IDs, if you have registered clusters with Cluster Registry, you can use the ``clusterName`` instead. However, you must adhere to the following restrictions: - Use ``clusterName`` or ``clusters``, but not both. - When you use ``clusters``, ``kafka-cluster`` is always required, because other clusters types do not have unique IDs. Access Restrictions ------------------- Some endpoints can be called by any authenticated user, while others can only be called by "admins". Additionally, many of the endpoints in the API involve two users: the user who is calling the endpoint (the "calling" principal) and the user that the API call is about (the "target" principal). Example: User "alice", who has the UserAdmin role, and is identified by her HTTP Basic authentication credentials or a bearer token, calls the CRUD endpoint to modify role bindings about user "bob". To document what access restrictions each endpoint has, use the following legend, which lists access in order from least restrictive to most restrictive: LDAP Any authenticated LDAP user Admins+User Admins or users requesting information about themselves Admins+ResourceOwners Admins or users with ResourceOwner role Admins+AclUsers Admins or the user having the required ACL permissions Admins Admins only, which can be UserAdmin, SystemAdmin, broker super.user, or SecurityAdmin as "Read" Overview of Responses --------------------- **Valid Responses** - 200: Successful call with a return body. - 204: Successful call with no return body. **Errors** - 400: Invalid request. JSON parsing error, or otherwise incorrect request. - 401: Not Authenticated. You need to pass valid HTTP Basic authentication credentials or a user bearer token. - 403: Not Authorized. Valid request, but you aren't authorized to perform the requested action. - 404: Invalid URL. If you get this error from the authenticate endpoint, it means bearer token authentication needs to be enabled in the configuration (``confluent.metadata.server.authentication.method=BEARER``) - 405: Method Not Allowed. Using the wrong HTTP method on a valid endpoint (for example, GET instead of POST). - 409: Conflict. Adding a new resource or updating an existing resource that would result in a conflict with existing state. - This error can be thrown by Audit Logs and Cluster Registry APIs. - 415: Invalid Content Type. Usually, a consequence of "application/json" as request body header. - 500: Server Error. Special Resource Types ---------------------- Cluster and KsqlCluster are special ResourceTypes because they grant resource-scoped roles like ResourceOwner and DeveloperManage limited access to cluster-level operations (for example, Describe Configs on |ak| clusters). These special resource types only accept LITERAL patterns with the values ``kafka-cluster`` and ``ksql-cluster``, respectively. Exploring the API ----------------- The Metadata Service ships with an OpenAPI spec that you can explore and interact with using an embedded Swagger UI. To enable the embedded Swagger UI, specify the following property in the broker's configuration when configuring the Metadata Service: ``confluent.metadata.server.openapi.enable=true``. This will make the Swagger UI available on the broker as ``http://:/security/openapi/swagger-ui/index.html``. .. note:: Specify the same port that MDS is listening on as the Swagger UI port (the default is ``8090``). .. warning:: The Swagger UI and the Open API spec file are provided for development and test purposes only: - **Do not enable in production environments.** - **The Swagger UI works only with HTTP.** Private RBAC UI Endpoints ------------------------- These endpoints were developed specifically to power the |c3| UI. As such, they only focus on those use cases and have only been tested in the context of |c3|. These endpoints have not been tested, nor has their usability been evaluated with respect to manual API calls. API Endpoints ------------- .. openapi:: ../../.hidden/metadata-service/rbac-api-server/src/main/resources/WEB-INF/openapi/mds-spec-1_0.yaml :group: :examples: Related Content --------------- - .. include:: ../../includes/kb/rbac-mds.rst