docs/source/includes/baremetal/steps-configure-openid-external-identity-management.rst

1. Set the OpenID Configuration Settings

   You can configure the OIDC (OpenID Connect) provider using either environment variables or server runtime configuration settings. Both methods require starting/restarting the MinIO deployment to apply changes. The following tabs provide a quick reference of all required and optional environment variables and configuration settings respectively:

   Environment Variables

   MinIO supports specifying the OIDC (OpenID Connect) provider settings using environment variables <minio-server-envvar-external-identity-management-openid>. The minio server process applies the specified settings on its next startup. 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 configuring an OIDC (OpenID Connect) provider for external identity management. 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 OIDC (OpenID Connect) provider discovery document.

   For complete documentation on these variables, see minio-server-envvar-external-identity-management-openid

   Configuration Settings

   MinIO supports specifying the OIDC (OpenID Connect) provider settings using configuration settings <identity_openid>. The minio server process applies the specified settings on its next startup. 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 an OIDC (OpenID Connect) provider for external identity management. The minimum required setting is identity_openid config_url <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>" 

   Replace the config_url with the URL endpoint of the OIDC (OpenID Connect) provider discovery document.

   For more complete documentation on these settings, see identity_openid.

2. Restart the MinIO Deployment

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

   mc admin service restart ALIAS

   Replace ALIAS with the alias <alias> of the deployment to restart.

3. Generate S3-Compatible Temporary Credentials using OIDC Credentials

   MinIO requires clients authenticate using AWS Signature Version 4 protocol <sig-v4-authenticating-requests.html> with support for the deprecated Signature Version 2 protocol. Specifically, clients must present a valid access key and secret key to access any S3 or MinIO administrative API, such as PUT, GET, and DELETE operations.

   Applications can generate temporary access credentials as-needed using the minio-sts-assumerolewithwebidentity Security Token Service (STS) API endpoint and the JSON Web Token (JWT) returned by the OIDC (OpenID Connect) provider.

   The application must provide a workflow for logging into the OIDC (OpenID Connect) provider and retrieving the JSON Web Token (JWT) associated to the authentication session. Defer to the provider documentation for obtaining and parsing the JWT token after successful authentication. MinIO provides an example Go application web-identity.go <minio/blob/master/docs/sts/web-identity.go> with an example of managing this workflow.

   Once the application retrieves the JWT token, use the AssumeRoleWithWebIdentity endpoint to generate the temporary credentials:

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

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

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

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

     Omit to use the policy associated to the OpenID user policy claim <minio-external-identity-management-openid-access-control>.

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

   See the minio-sts-assumerolewithwebidentity for reference documentation.