OpenID Connect Access Management

For identities managed by an external OpenID Connect (OIDC) compatible provider, AIStor can use either of two methods to assign policies to the authenticated user.

AIStor by default denies access to all actions or resources not explicitly allowed by a user’s assigned or inherited policies.

Authorization options with OIDC

OIDC integration in AIStor supports either of the following authorization methods:

  • The RolePolicy flow sets the assigned policies for an authenticated user in the AIStor configuration.

    This is the recommended method.

  • The JWT flow sets the assigned policies for an authenticated user as part of the OIDC configuration.

    You can set policies with this method for only one OIDC provider per deployment. If your deployment integrates multiple OIDC providers, all others must set policies with RolePolicy.

  • Users can create long-lived access keys.

    Access keys inherit their permissions from the parent user. The parent user can further restrict permissions when they create access keys. To create a new access key, a human user logs into the AIStor console with their OIDC credentials. They can then create an access key in the Access section of the navigation.

RolePolicy and RoleArn

With this flow, a client generates an STS credential with a given RoleArn. The client then receives the policy or policies associated with the RolePolicy configuration for the RoleArn.

You can use OIDC policy variables to create policies that programmatically manage what each individual user has access to.

The flow for an application using OIDC credentials with a RolePolicy claim flow looks like the following:

  1. Create an OIDC Configuration.

  2. Record the RoleArn assigned to the configuration either at time of creation or at AIStor start. Use this RoleArn with the AssumeRoleWithWebIdentity STS API.

  3. Create a RolePolicy to attach to the RoleArn. Use either the MINIO_IDENTITY_OPENID_ROLE_POLICY environment variable or the identity_openid role_policy configuration setting to define the list of policies.

  4. Users select the configured OIDC provider when logging in to AIStor.

  5. Users complete authentication to the configured OIDC provider and redirect back to AIStor.

    Only the Authorization Code flow is supported. The Implicit flow is not supported.

  6. AIStor verifies the RoleArn in the API call and checks for the RolePolicy to use. Any authentication request with the RoleArn receives the same policy access permissions.

  7. AIStor returns temporary credentials in the STS API response in the form of an access key, secret key, and session token. The credentials have permissions matching the policies specified in the RolePolicy.

  8. Applications use the temporary credentials returned by the STS endpoint to perform authenticated S3 operations on AIStor.

JSON Web Token Claim

Using JSON Web Tokens lets you assign policies individually. However, their use comes at the increased cost of managing multiple policies for separate claims.

The login flow for an application using OIDC credentials with a JSON Web Token claim flow looks like the following:

  1. Authenticate to the configured OIDC provider and retrieve a JSON Web Token (JWT).

    Only the Authorization Code flow is supported. The Implicit flow is not supported.

  2. Pass the JWT to the STS AssumeRoleWithWebIdentity API endpoint.

    AIStor verifies the JWT against the configured OIDC provider.

    If the JWT is valid, AIStor checks for a claim specifying a list of one or more policies to assign to the authenticated user. AIStor defaults to checking the policy claim.

  3. AIStor returns temporary credentials in the STS API response in the form of an access key, secret key, and session token. The credentials have permissions matching the policies specified in the JWT claim.

  4. Applications use the temporary credentials returned by the STS endpoint to perform authenticated S3 operations on AIStor.

AIStor provides an example Go application web-identity.go that handles the full login flow.

Identifying the JWT claim value

AIStor uses the JWT token returned as part of the OIDC authentication flow to identify the specific policies to assign to the authenticated user.

You can use a JWT Debugging tool to decode the returned JWT token and validate that the user attributes include the required claims.

See RFC 7519: JWT Claim for more information on JWT claims.

Refer to the documentation for your preferred OIDC provider for instructions on configuring user claims.

Creating policies to match claims

You can use either the AIStor console or the mc admin policy command to create policies that match one or more claim values.

OIDC Policy Variables

The following table contains a list of supported policy variables for use in authorizing OIDC-managed users.

Each variable corresponds to a claim returned as part of the authenticated user’s JWT token:

Variable Description
jwt:sub Returns the sub claim for the user.
jwt:iss Returns the Issuer Identifier claim from the ID token.
jwt:aud Returns the Audience claim from the ID token.
jwt:jti Returns the JWT ID claim from the client authentication information.
jwt:upn Returns the User Principal Name claim from the client authentication information.
jwt:name Returns the name claim for the user.
jwt:groups Returns the groups claim for the user.
jwt:given_name Returns the given_name claim for the user.
jwt:family_name Returns the family_name claim for the user.
jwt:middle_name Returns the middle_name claim for the user.
jwt:nickname Returns the nickname claim for the user.
jwt:preferred_username Returns the preferred_username claim for the user.
jwt:profile Returns the profile claim for the user.
jwt:picture Returns the picture claim for the user.
jwt:website Returns the website claim for the user.
jwt:email Returns the email claim for the user.
jwt:gender Returns the gender claim for the user.
jwt:birthdate Returns the birthdate claim for the user.
jwt:phone_number Returns the phone_number claim for the user.
jwt:address Returns the address claim for the user.
jwt:scope Returns the scope claim for the user.
jwt:client_id Returns the client_id claim for the user.

See the OpenID Connect Core 1.0 document for more information on these scopes. Your OIDC provider of choice may have more specific documentation.

For example, the following policy uses variables to substitute the authenticated user’s preferred_username as part of the Resource field such that the user can access only the prefixes that match their username:

{
"Version": "2012-10-17",
"Statement": [
      {
         "Action": ["s3:ListBucket"],
         "Effect": "Allow",
         "Resource": ["arn:aws:s3:::mybucket"],
         "Condition": {"StringLike": {"s3:prefix": ["${jwt:preferred_username}/*"]}}
      },
      {
         "Action": [
         "s3:GetObject",
         "s3:PutObject"
         ],
         "Effect": "Allow",
         "Resource": ["arn:aws:s3:::mybucket/${jwt:preferred_username}/*"]
      }
   ]
}

AIStor replaces the ${jwt:preferred_username} variable in the Resource field with the value of the preferred_username in the JWT token. AIStor then evaluates the policy and grants or revokes access to the requested actions and resource.

All rights reserved 2024-Present, MinIO, Inc.