OpenID Connect Identity Management

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

This page explains how to configure an OIDC provider for AIStor on 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.

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 AIStor deployment must have bidirectional network connectivity to the target OIDC service.

Ensure each user identity intended for use with AIStor has the appropriate claim configured such that AIStor can associate a policy to the authenticated user. An OpenID user with no assigned policy has no permission to access any action or resource on the AIStor cluster.

This procedure uses mc for performing operations on the 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 AIStor cluster.

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 AIStor console. All methods require starting/restarting the AIStor deployment to apply changes.

   Environment Variables

   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>"
   

   Configuration settings

   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 AIStor Deployment

   You must restart the 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 AIStor console supports the full workflow of authenticating to the provider, generating temporary credentials using the AIStor AssumeRoleWithWebIdentity Security Token Service (STS) endpoint, and logging the user into the 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 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 AIStor administrative API, such as PUT, GET, and DELETE operations.

   You can create access keys to support applications that must perform operations on 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 AIStor.

   See the AssumeRoleWithWebIdentity for reference documentation.

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.

Before configuring 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

  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

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="azure_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="azure_groups" \
  display_name="Microsoft Entra ID" \
  vendor="azure" \
  azure_tenant_id="{tenant-id}" \
  redirect_uri="https://minio.example.com/oauth_callback"

When a user authenticates with Microsoft Entra ID:

1. The user authenticates through the Microsoft Entra ID flow.
2. AIStor receives an access token and extracts the user’s object ID (oid claim).
3. Using the configured tenant ID, client ID, and client secret, AIStor authenticates to the Microsoft Graph API.
4. AIStor queries the Graph API to fetch all groups to which the user belongs.
5. These groups are added to the azure_groups claim for policy mapping.

AIStor lets you manage policies using human-readable Microsoft Entra ID group names. These APIs automatically translate between group names and their corresponding UUIDs (object IDs) using the Microsoft Graph API.

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

AIStor fetches user group memberships from Microsoft Entra ID at authentication time and refreshes them approximately every hour. The periodic refresh interval varies between 30-90 minutes to distribute load across the system.

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.

1. Retrieve your Microsoft Entra ID tenant ID

   The tenant ID is also known as the Directory ID.

2. Update your AIStor configuration

   Environment Variables

   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}"
   

   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.

   mc idp openid

   Update your OIDC configuration:

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

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 AIStor

   Run mc admin service restart to apply the configuration changes.