Model access control

Introduced 2.9

You can use the Security plugin with ML Commons to manage access to specific models for non-admin users. For example, one department in an organization might want to restrict users in other departments from accessing their models.

To accomplish this, users are assigned one or more backend roles. Rather than assign individual roles to individual users during user configuration, backend roles provide a way to map a set of users to a role by assigning the backend role to users when they log in. For example, users may be assigned an IT backend role that includes the ml_full_access role and have full access to all ML Commons features. Alternatively, other users may be assigned an HR backend role that includes the ml_readonly_access role and be limited to read-only access to machine learning (ML) features. Given this flexibility, backend roles can provide finer-grained access to models and make it easier to assign multiple users to a role rather than mapping a user and role individually.

ML Commons roles

The ML Commons plugin has two reserved roles:

  • ml_full_access: Grants full access to all ML features, including starting new ML tasks and reading or deleting models.
  • ml_readonly_access: Grants read-only access to ML tasks, trained models, and statistics relevant to the model’s cluster. Does not grant permissions to start or delete ML tasks or models.

Model groups

For access control, models are organized into model groups—collections of versions of a particular model. Like users, model groups can be assigned one or more backend roles. All versions of the same model share the same model name and have the same backend role or roles.

You are considered a model owner when you create a new model group. You remain the owner of the model and all its versions even if another user registers a model to this model group. When a model owner creates a model group, the owner can specify one of the following access modes for this model group:

  • public: All users who have access to the cluster can access this model group.
  • private: Only the model owner or an admin user can access this model group.
  • restricted: The owner, an admin user, or any user who shares one of the model group’s backend roles can access any model in this model group. When creating a restricted model group, the owner must attach one or more of the owner’s backend roles to the model.

An admin can access all model groups in the cluster regardless of their access mode.

Model access control prerequisites

Before using model access control, you must satisfy the following prerequisites:

  1. Enable the Security plugin on your cluster. For more information, see Security in OpenSearch.
  2. For restricted model groups, ensure that an admin has assigned backend roles to users.
  3. Enable model access control on your cluster.

If any of the prerequisites are not met, all models in the cluster are public and can be accessed by any user who has access to the cluster.

Assigning backend roles to users

Create the appropriate backend roles and assign those roles to users. Backend roles usually come from an LDAP server or SAML provider, but if you use the internal user database, you can use the REST API to add them manually.

Only admin users can assign backend roles to users.

When assigning backend roles, consider the following example of two users: alice and bob.

The following request assigns the user alice the analyst backend role:

  1. PUT _plugins/_security/api/internalusers/alice
  2. {
  3.   "password": "alice",
  4.   "backend_roles": [
  5.     "analyst"
  6.   ],
  7.   "attributes": {}
  8. }

The next request assigns the user bob the human-resources backend role:

  1. PUT _plugins/_security/api/internalusers/bob
  2. {
  3.   "password": "bob",
  4.   "backend_roles": [
  5.     "human-resources"
  6.   ],
  7.   "attributes": {}
  8. }

Finally, the last request assigns both alice and bob the role that gives them full access to ML Commons:

  1. PUT _plugins/_security/api/rolesmapping/ml_full_access
  2. {
  3.   "backend_roles": [],
  4.   "hosts": [],
  5.   "users": [
  6.     "alice",
  7.     "bob"
  8.   ]
  9. }

If alice creates a model group and assigns it the analyst backend role, bob cannot access this model.

Enabling model access control

You can enable model access control dynamically as follows:

  1. PUT _cluster/settings
  2. {
  3.   "transient": {
  4.     "plugins.ml_commons.model_access_control_enabled": "true"
  5.   }
  6. }

copy

Model access control API

Model access control is achieved through the Model Group APIs. These APIs include the register, search, update, and delete model group operations.

For information about APIs related to model access control, see Model Group APIs.

Hidden models

Introduced 2.12

To hide model details from end users, including the cluster admin, you can register a hidden model. If a model is hidden, the non-superadmin users don’t have permission to call any Model APIs except for the Predict API on the model.

Only superadmin users can register a hidden model. A hidden model can be one of the OpenSearch-provided pretrained models, your own custom model, or an externally hosted model. To register a hidden model, you first need to authenticate with an admin certificate:

  1. curl -k --cert ./kirk.pem --key ./kirk-key.pem -XGET 'https://localhost:9200/.opendistro_security/_search'

All models created by a superadmin user are automatically registered as hidden. To register a hidden model, send a request to the _register endpoint:

  1. curl -k --cert ./kirk.pem --key ./kirk-key.pem -X POST 'https://localhost:9200/_plugins/_ml/models/_register' -H 'Content-Type: application/json' -d '
  2. {
  3.     "name": "OPENSEARCH_ASSISTANT_MODEL",
  4.     "function_name": "remote",
  5.     "description": "OpenSearch Assistant Model",
  6.     "connector": {
  7.         "name": "Bedrock Claude Connector",
  8.         "description": "The connector to Bedrock Claude",
  9.         "version": 1,
  10.         "protocol": "aws_sigv4",
  11.         "parameters": {
  12.           "region": "us-east-1",
  13.           "service_name": "bedrock"
  14.         },
  15.         "credential": {
  16.             "access_key": "<YOUR_ACCESS_KEY>",
  17.             "secret_key": "<YOUR_SECRET_KEY>",
  18.             "session_token": "<YOUR_SESSION_TOKEN>"
  19.         },
  20.         "actions": [
  21.            {
  22.             "action_type": "predict",
  23.             "method": "POST",
  24.             "headers": {
  25.                 "content-type": "application/json"
  26.             },
  27.             "url": "https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-v2/invoke",
  28.             "request_body": "{\"prompt\":\"\\n\\nHuman: ${parameters.inputs}\\n\\nAssistant:\",\"max_tokens_to_sample\":300,\"temperature\":0.5,\"top_k\":250,\"top_p\":1,\"stop_sequences\":[\"\\\\n\\\\nHuman:\"]}"
  29.           }
  30.        ]
  31.     }
  32. }'

copy

Once a hidden model is registered, only a superadmin can invoke operations on the model, including the deploy, undeploy, delete, and get API operations. For example, to deploy a hidden model, send the following request. In this request, q7wLt4sBaDRBsUkl9BJV is the model ID:

  1. curl -k --cert ./kirk.pem --key ./kirk-key.pem -X POST 'https://localhost:9200/_plugins/_ml/models/q7wLt4sBaDRBsUkl9BJV/_deploy'

copy

The model_id of a hidden model is the model name. A hidden model includes an is_hidden parameter that is set to true. You cannot change a hidden model’s is_hidden parameter.

Admin users can change access to a model by updating its backend roles.