Authorization Plugin

The MinIO AIStor Access Management Plugin provides a REST interface for offloading authorization through a webhook service.

MinIO AIStor sends the request and credential details for every API call to the configured external HTTP(S) endpoint and looks for a response of ALLOW or DENY. MinIO AIStor can therefore delegate the access management to the external system instead of relying on S3 policy based access control.

Open Policy Agent is a common choice for the endpoint. It works with any credential type: OpenID or LDAP STS credentials, built-in users, and access keys alike.

The endpoint receives every request header, so use HTTPS

The request body carries the whole conditions map, which includes every header the client sent. That means the Authorization header, X-Amz-Security-Token, and on SSE-C requests the object encryption key in X-Amz-Server-Side-Encryption-Customer-Key. Your MINIO_POLICY_PLUGIN_AUTH_TOKEN travels as an Authorization header on the same request.

AIStor accepts both http:// and https:// and does not warn you about a plaintext endpoint. Use HTTPS for any endpoint that is not on the loopback interface.

What the endpoint decides, and what it does not

When the plugin is configured, AIStor consults it before anything else, so the endpoint answers for every authenticated identity. That includes the root user, whose usual bypass is not reached. An endpoint that does not explicitly allow the owner locks the root user out of the deployment, so grant it deliberately.

If the endpoint cannot be reached, or answers with anything AIStor cannot parse, the request is denied. The decision is not cached, so the endpoint’s availability and latency become the deployment’s availability and latency for authorization.

Two paths still decide on their own and never reach the endpoint:

  • Anonymous requests, which carry no credentials, are decided by the bucket policy.
  • Internal AIStor Tables access is refused before authorization runs.

If your credentials carry an inline session policy, the endpoint has to apply it. AIStor does not evaluate the session policy separately once the plugin is in the path.

Every authenticated request calls the endpoint
This is not a login-time check. Each authenticated API call triggers one request to the plugin, so the endpoint sits in the latency path of every operation. Size and place it accordingly, and measure before putting it in front of a latency-sensitive workload.

Configuration settings

You can configure the MinIO AIStor External Access Management Plugin using the following environment variables or configuration settings.

Authorizing through a webhook Authentication happens as usual. For authorization, AIStor POSTs the request and credential details of every API call to the URL set in MINIO_POLICY_PLUGIN_URL and expects an answer of ALLOW or DENY. The webhook replaces policy evaluation rather than supplementing it, and it answers for every identity including the root user. AUTHORIZATION WEBHOOK asked for every API call, and for every identity CLIENT Request signed or STS AISTOR SERVER your deployment 1 · Authenticate any configured identity provider 2 · Authorize the webhook answers, root included YOUR SERVICE outside it POST request and credentials answer ALLOW or DENY MINIO_POLICY_PLUGIN_URL Allowed · the operation runs Denied · the request returns 403 AIStor denies anything a policy does not explicitly allow, so a user with no policy can perform no operation at all.
The webhook answers the second step, for every API call rather than once at login. It replaces policy evaluation rather than supplementing it.

Authentication and authorization flow

The login flow for an application is as follows:

  1. The client includes authentication information as part of performing the API call

  2. The configured Identity Manager authenticates the client

  3. MinIO AIStor makes a POST call to the configured access management plugin URL which includes the context of the API call and authentication data

  4. On successful authorization, the access manager returns a 200 OK response with a JSON body of either result true or "result" : { "allow" : true }:

If the access manager rejects the authorization request, MinIO AIStor automatically blocks and denies the API call.

Request body example

The following JSON resembles the request body sent as part of the POST to the configured access manager webhook.

{
   "input": {
      "account": "minio",
      "groups": null,
      "action": "s3:ListBucket",
      "bucket": "test",
      "conditions": {
         "Authorization": [
         "AWS4-HMAC-SHA256 Credential=minio/20220507/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=62012db6c47d697620cf6c68f0f45f6e34894589a53ab1faf6dc94338468c78a"
         ],
         "CurrentTime": [ "2022-05-07T18:31:41Z" ],
         "Delimiter": [ "/" ],
         "EpochTime": [
         "1651948301"
         ],
         "Prefix": [ "" ],
         "Referer": [ "" ],
         "SecureTransport": [ "false" ],
         "SourceIp": [ "127.0.0.1" ],
         "User-Agent": [ "MinIO AIStor (linux; amd64) minio-go/v7.0.24 mc/DEVELOPMENT.2022-04-20T23-07-53Z" ],
         "UserAgent": [ "MinIO AIStor (linux; amd64) minio-go/v7.0.24 mc/DEVELOPMENT.2022-04-20T23-07-53Z" ],
         "X-Amz-Content-Sha256": [ "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" ],
         "X-Amz-Date": [ "20220507T183141Z" ],
         "authType": [ "REST-HEADER" ],
         "principaltype": [ "Account" ],
         "signatureversion": [ "AWS4-HMAC-SHA256" ],
         "userid": [ "minio" ],
         "username": [ "minio" ],
         "versionid": [ "" ]
      },
      "owner": true,
      "object": "",
      "claims": {},
      "denyOnly": false
   }
}

Response body example

MinIO AIStor requires the response body from the Access Management service meet one of the two following formats:

{ "result" : true }

{ "result" : { "allow" : true } }