OpenID Connect Identity Management

MinIO AIStor supports using an OpenID Connect (OIDC) identity provider (IDP) such as Okta, Keycloak, Dex, Google, or Facebook for external management of user identities.

Configure MinIO AIStor to use an OIDC provider, on both Kubernetes and bare-metal infrastructures.

See OpenID Connect Access Management for how to set up appropriate access controls for OIDC-managed identities.

This procedure is generic for OIDC-compatible providers. Refer to the documentation for the OIDC provider of your choice for specific information.

Prerequisites

OpenID-Connect (OIDC) provider

This procedure assumes an existing OIDC provider such as Okta, KeyCloak, Dex, Google, or Facebook. Instructions on configuring these services are out of scope for this procedure.

The MinIO AIStor deployment must have bidirectional network connectivity to the target OIDC service.

MinIO AIStor associates a policy with an authenticated OIDC user in one of two ways. Configure exactly one of them:

• Set role_policy to a comma-separated list of policy names. MinIO AIStor derives a RoleArn for the provider, and applies those policies to authentication requests that present that RoleArn. This flow needs no per-user claim.
• Set claim_name, and configure that claim on each user identity. The provider issues the claim, and MinIO AIStor assigns the policies that the claim names to that user. Those policies must already exist in MinIO AIStor.

Setting both role_policy and claim_name is a configuration error, and MinIO AIStor reports it rather than starting with the provider enabled.

An OpenID user with no assigned policy has no permission to access any action or resource on the MinIO AIStor cluster.

Access to MinIO AIStor Cluster

This procedure uses mc for performing operations on the MinIO AIStor cluster. Install mc on a machine with network access to the cluster. See the mc Installation Quickstart for instructions on downloading and installing mc.

This procedure assumes a configured alias for the MinIO AIStor cluster.

Configure MinIO AIStor for an OIDC provider

1. Provide the OIDC configuration settings.

   You can configure the provider using either environment variables or server runtime configuration settings. You can also create the configuration in the Console UI. All methods require starting/restarting the MinIO AIStor deployment to apply changes.

   Environment VariablesConfiguration settings

   For distributed deployments, specify these settings across all nodes in the deployment using the same values consistently.

   The following example code sets all environment variables related to an OIDC configuration. The minimum required variable is MINIO_IDENTITY_OPENID_CONFIG_URL:

   export MINIO_IDENTITY_OPENID_CONFIG_URL="https://openid-provider.example.net/.well-known/openid-configuration"
   export MINIO_IDENTITY_OPENID_CLIENT_ID="<string>"
   export MINIO_IDENTITY_OPENID_CLIENT_SECRET="<string>"
   export MINIO_IDENTITY_OPENID_CLAIM_NAME="<string>"
   export MINIO_IDENTITY_OPENID_CLAIM_PREFIX="<string>"
   export MINIO_IDENTITY_OPENID_SCOPES="<string>"
   export MINIO_IDENTITY_OPENID_REDIRECT_URI="<string>"
   export MINIO_IDENTITY_OPENID_COMMENT="<string>"

   Replace the MINIO_IDENTITY_OPENID_CONFIG_URL with the URL endpoint of the provider discovery document.

   For complete documentation of these variables, see OpenID Identity Management Settings.

   To configure additional named OIDC providers, append the configuration name to each environment variable. The name is case-sensitive and must be consistent across all variables. By convention, use uppercase (for example, _PARTNERS):

   export MINIO_IDENTITY_OPENID_CONFIG_URL_PARTNERS="https://partners-idp.example.net/.well-known/openid-configuration"
   export MINIO_IDENTITY_OPENID_CLIENT_ID_PARTNERS="<string>"
   export MINIO_IDENTITY_OPENID_CLIENT_SECRET_PARTNERS="<string>"

   For distributed deployments, the mc admin config command applies the configuration to all nodes in the deployment.

   The following example code sets all configuration settings related to configuring a provider for external identity management. The minimum required setting is identity_openid config_url:

   mc admin config set ALIAS identity_openid \
     config_url="https://openid-provider.example.net/.well-known/openid-configuration" \
     client_id="<string>" \
     client_secret="<string>" \
     claim_name="<string>" \
     claim_prefix="<string>" \
     scopes="<string>" \
     redirect_uri="<string>" \
     comment="<string>"

   Replace the config_url value with the URL endpoint of the provider discovery document.

   For more complete documentation on these settings, see identity_openid.

2. Restart the MinIO AIStor Deployment

   You must restart the MinIO AIStor deployment to apply the configuration changes. Run the mc admin service restart command to restart the deployment.

   mc admin service restart ALIAS

   Replace ALIAS with the alias of the deployment to restart.

3. Use the console to log in with OIDC credentials

   The Console UI supports the full workflow of authenticating to the provider, generating temporary credentials using the MinIO AIStor AssumeRoleWithWebIdentity Security Token Service (STS) endpoint, and logging the user into the MinIO AIStor deployment.

   Go to the root URL for the deployment, for example https://minio.example.net:9000.

   After you log in, you can perform any action for which your account is authorized.

4. Generate credentials for application authentication

   Clients should authenticate using AWS Signature Version 4 protocol, although MinIO AIStor maintains backward compatibility to support the deprecated Signature Version 2 protocol. Clients must present a valid access key and secret key to access any S3 or MinIO AIStor administrative API, such as PUT, GET, and DELETE operations.

   You can create access keys to support applications that must perform operations on MinIO AIStor. Access keys are long-lived credentials that inherit their permissions from the parent user.

   Alternatively, applications can generate temporary access credentials as needed with the AssumeRoleWithWebIdentity Security Token Service (STS) API endpoint and OIDC user credentials.

   The application must provide a workflow for logging into the provider and retrieving the JSON Web Token (JWT) associated with the authentication session. Refer to the provider documentation for obtaining and parsing the JWT token after successful authentication. See the example Go application web-identity.go for this workflow.

   Call the AssumeRoleWithWebIdentity endpoint with the JWT to generate the temporary credentials:

   POST https://aistor.example.net?Action=AssumeRoleWithWebIdentity
   &WebIdentityToken=TOKEN
   &Version=2011-06-15
   &DurationSeconds=86400
   &Policy=Policy

   • Replace TOKEN with the JWT token returned in the previous step.

   • Replace DurationSeconds with the duration in seconds until the temporary credentials expire. The example specifies a period of 86400 seconds, or 24 hours.

   • Replace Policy with an inline URL-encoded JSON policy that further restricts the permissions associated to the temporary credentials.

     Omit to use the policy associated with the OIDC user policy claim.

   The API response consists of an XML document containing the access key, secret key, session token, and expiration. Applications can use the access key and secret key to access and perform operations on MinIO AIStor.

   See the AssumeRoleWithWebIdentity for reference documentation.

   STS credentials always expire

   STS credentials derived from an OIDC identity always carry a bounded expiration. AIStor rejects a token that lacks a usable expiration (exp) claim, and it rejects any requested DurationSeconds value outside the supported range of 15 minutes to 365 days. When the token supplies a valid exp, the credential lifetime is bounded by that expiration and the configured STS duration limits.

   See AssumeRoleWithWebIdentity for reference documentation.

Microsoft Entra ID

MinIO AIStor supports Microsoft Entra ID (formerly Azure AD) as an OIDC provider with enhanced integration for fetching user group memberships using the Microsoft Graph API.

Prerequisites for Microsoft Entra ID

Before configuring MinIO AIStor for Microsoft Entra ID, you must:

• Register an application in Microsoft Entra ID

  Note the Application (client) ID and Directory (tenant) ID

• Create a client secret

  Copy the secret value as you cannot retrieve it later.

• Configure API permissions

  MinIO AIStor requires the following read permissions:

  • User.Read.All - grants access to user profiles and group memberships
  • Group.Read.All - grants access to group information

Configure MinIO AIStor for Microsoft Entra ID

export MINIO_IDENTITY_OPENID_CONFIG_URL="https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration"
export MINIO_IDENTITY_OPENID_CLIENT_ID="{application-client-id}"
export MINIO_IDENTITY_OPENID_CLIENT_SECRET="{client-secret}"
export MINIO_IDENTITY_OPENID_CLAIM_NAME="groups"
export MINIO_IDENTITY_OPENID_DISPLAY_NAME="Microsoft Entra ID"
export MINIO_IDENTITY_OPENID_VENDOR="azure"
export MINIO_IDENTITY_OPENID_AZURE_TENANT_ID="{tenant-id}"
export MINIO_IDENTITY_OPENID_REDIRECT_URI="https://minio.example.com/oauth_callback"

mc idp openid add ALIAS \
  config_url="https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration" \
  client_id="{application-client-id}" \
  client_secret="{client-secret}" \
  claim_name="groups" \
  display_name="Microsoft Entra ID" \
  vendor="azure" \
  azure_tenant_id="{tenant-id}" \
  redirect_uri="https://minio.example.com/oauth_callback"

How Microsoft Entra ID authentication works

When a user authenticates with Microsoft Entra ID:

1. The user authenticates through the Microsoft Entra ID flow.
2. MinIO AIStor reads the user’s object ID from the oid claim of the ID token.
3. Using the configured tenant ID, client ID, and client secret, MinIO AIStor authenticates to the Microsoft Graph API.
4. MinIO AIStor queries the Graph API to fetch every group and directory role the user belongs to, including nested groups.
5. These groups are added to the groups claim for policy mapping.

Mapping Microsoft Entra ID groups to policies

Name each policy after the object ID of the group it applies to:

mc admin policy create ALIAS <group-object-id> policy.json

When users authenticate, they receive permissions from all policies matching their Microsoft Entra ID group memberships.

MinIO AIStor also has admin APIs that translate between group names and object IDs using the Microsoft Graph API. If you use them, give each mapped group a unique display name: when two groups share a name, the APIs use the first group that Graph returns.

Group membership changes

MinIO AIStor reads group memberships from Microsoft Graph each time a user signs in. Temporary credentials keep the policies they were issued with until they expire, so a change in Microsoft Entra ID applies at the user’s next sign-in.

Migrating from azure_use_group_id

If you configured Microsoft Entra ID prior to AIStor Server RELEASE.2025-12-20T04-58-37Z, you must update your configuration to use the new azure_tenant_id setting. Starting with that release, MinIO AIStor fills the groups claim instead of azure_groups, so a configuration that still sets the claim name to azure_groups doesn’t issue credentials.

1. Retrieve your Microsoft Entra ID tenant ID

   The tenant ID is also known as the Directory ID.

2. Update your MinIO AIStor configuration

   Environment Variablesmc idp openid

   Remove the deprecated setting and add the new one:

   # Remove the following deprecated setting
   # export MINIO_IDENTITY_OPENID_AZURE_USE_GROUP_ID="on"
   
   # Add the new required setting
   export MINIO_IDENTITY_OPENID_AZURE_TENANT_ID="{tenant-id}"
   
   # Use the groups claim
   export MINIO_IDENTITY_OPENID_CLAIM_NAME="groups"

   For Kubernetes deployments, see Environment Variable Configuration for instructions on setting environment variables in the ObjectStore object.

   For Linux deployments, modify the /etc/default/minio environment file. See your platform’s installation guide for details: Ubuntu or Red Hat.

   Update your OIDC configuration:

   mc idp openid update ALIAS azure-config \
     azure_tenant_id="{tenant-id}" \
     claim_name="groups"

3. Ensure API permissions are configured

   The new integration requires Microsoft Graph API permissions. Verify your Microsoft Entra ID app registration has:

   • User.Read.All (Application permission)
   • Group.Read.All (Application permission)
   • Admin consent granted for these permissions

4. Restart MinIO AIStor

   Run mc admin service restart to apply the configuration changes.