rustfs/docs/operations/authing-oidc-integration.md

Authing OIDC Integration Runbook

This runbook helps operators connect the RustFS Console to Authing through standard OpenID Connect. The examples use the default RustFS provider id, default.

1. Integration Model

RustFS expects a standards-compliant OpenID Connect provider, not an Authing-specific plugin. The Authing application must provide:

• issuer metadata through .well-known/openid-configuration
• authorization endpoint
• token endpoint
• JWKS or another verifiable ID token signature path
• authorization-code flow that returns an id_token

The RustFS browser login flow is:

1. The user opens the RustFS OIDC authorize endpoint.
2. RustFS creates state, nonce, and a PKCE S256 challenge.
3. The browser is redirected to Authing.
4. Authing redirects back to RustFS with code and state.
5. RustFS exchanges the code with client_id, client_secret, and the PKCE verifier.
6. RustFS validates the ID token signature, issuer, audience, expiry, and nonce.
7. RustFS reads identity and authorization claims from the ID token.
8. RustFS maps claim values to RustFS policy names and issues one-hour STS credentials for the Console.

2. Required Values

Collect these values before deployment:

Value	Example	Notes
Public RustFS browser origin	https://rustfs.example.com	The scheme and authority users open in the browser.
Provider id	default	This runbook uses the default provider.
RustFS callback URL	https://rustfs.example.com/rustfs/admin/v3/oidc/callback/default	Register this exact URL in Authing.
Authing application domain	https://example.authing.cn	Use the value shown in the Authing application.
Authing issuer	https://example.authing.cn/oidc	Copy the issuer from Authing; do not guess the path.
Authing App ID	<AUTHING_APP_ID>	RustFS client_id.
Authing App Secret	<AUTHING_APP_SECRET>	RustFS client_secret.
RustFS scopes	openid,profile,email,roles	openid is required; include roles when Authing emits role claims.

Authing deployments can use different issuer paths, such as /oidc or /oauth/oidc. Always copy the issuer from the Authing console and verify that discovery returns the same issuer value.

3. Authing Configuration

3.1 Create the Application

1. Open the Authing console.
2. Create a self-hosted application named RustFS Console.
3. Record the App ID, App Secret, application domain, issuer, and discovery URL.

3.2 Configure OIDC

Use these protocol settings:

Setting	Value
Protocol	OpenID Connect
Grant type	Authorization Code
Response type	code
Token endpoint authentication	client_secret_post
PKCE	Allow or require S256
ID token signing algorithm	RS256 recommended

RustFS sends the client secret in the request body. Do not configure Authing to reject client_secret_post.

3.3 Register the Redirect URL

Add this exact callback URL in Authing:

https://rustfs.example.com/rustfs/admin/v3/oidc/callback/default

The scheme, host, port, path, and provider id must match the RustFS configuration.

3.4 Map Roles to RustFS Policies

RustFS does not call Authing authorization APIs. It reads roles or groups from the ID token and maps each value to a RustFS policy name.

Recommended policy names:

Authing claim value	RustFS policy	Purpose
consoleAdmin	consoleAdmin	Full Console, admin, KMS, and S3 access.
readwrite	readwrite	S3 read/write access.
readonly	readonly	S3 read-only access.
writeonly	writeonly	S3 write-only access.
diagnostics	diagnostics	Diagnostic admin access.

For initial validation, assign a test user the consoleAdmin role and confirm that the ID token contains:

{
  "roles": ["consoleAdmin"]
}

claim_prefix only prepends a fixed string. It does not perform arbitrary role mapping. Keep Authing role values equal to RustFS policy names unless you already created policies with a fixed prefix.

4. RustFS Configuration

4.1 Environment Variables

Set the OIDC provider and the public browser origin:

export RUSTFS_BROWSER_REDIRECT_URL="https://rustfs.example.com"

export RUSTFS_IDENTITY_OPENID_ENABLE=on
export RUSTFS_IDENTITY_OPENID_CONFIG_URL="<AUTHING_ISSUER>"
export RUSTFS_IDENTITY_OPENID_CLIENT_ID="<AUTHING_APP_ID>"
export RUSTFS_IDENTITY_OPENID_CLIENT_SECRET="<AUTHING_APP_SECRET>"
export RUSTFS_IDENTITY_OPENID_SCOPES="openid,profile,email,roles"
export RUSTFS_IDENTITY_OPENID_REDIRECT_URI="https://rustfs.example.com/rustfs/admin/v3/oidc/callback/default"
export RUSTFS_IDENTITY_OPENID_REDIRECT_URI_DYNAMIC=off
export RUSTFS_IDENTITY_OPENID_DISPLAY_NAME="Authing"
export RUSTFS_IDENTITY_OPENID_EMAIL_CLAIM="email"
export RUSTFS_IDENTITY_OPENID_USERNAME_CLAIM="preferred_username"
export RUSTFS_IDENTITY_OPENID_ROLES_CLAIM="roles"

For short-lived connectivity testing only, you may temporarily add:

export RUSTFS_IDENTITY_OPENID_ROLE_POLICY="consoleAdmin"

Do not keep role_policy=consoleAdmin in production unless every Authing user for this client should receive full Console access.

Restart RustFS after changing OIDC settings.

4.2 Admin Config

If the deployment manages OIDC through compatible admin configuration commands, set the provider like this:

mc admin config set rustfs identity_openid \
  enable=on \
  config_url="<AUTHING_ISSUER>" \
  client_id="<AUTHING_APP_ID>" \
  client_secret="<AUTHING_APP_SECRET>" \
  scopes="openid,profile,email,roles" \
  redirect_uri="https://rustfs.example.com/rustfs/admin/v3/oidc/callback/default" \
  redirect_uri_dynamic=off \
  display_name="Authing" \
  email_claim="email" \
  username_claim="preferred_username" \
  roles_claim="roles"

mc admin service restart rustfs

RUSTFS_BROWSER_REDIRECT_URL is a process environment variable, not an identity_openid provider key. Configure it in the RustFS service environment even when the provider itself is stored through admin config.

4.3 Redirect URL Priority

RustFS builds browser-facing URLs with this priority:

1. Provider redirect_uri, when configured, is used for the OIDC callback URL sent to Authing.
2. RUSTFS_BROWSER_REDIRECT_URL, when configured, is used as the public origin for OIDC callback generation when no provider redirect_uri exists, and for Console success redirects and logout fallback redirects.
3. Request headers are used only when provider dynamic redirects are enabled and no browser redirect URL is configured.

For reverse-proxy or load-balancer deployments, set RUSTFS_BROWSER_REDIRECT_URL to avoid depending on Host and X-Forwarded-Proto for Console redirects. OIDC authorize and callback requests must still reach the same RustFS node because in-flight OIDC state is local to the node.

5. Validation

5.1 Validate Authing Discovery

AUTHING_ISSUER="<AUTHING_ISSUER>"

curl -fsS "$AUTHING_ISSUER/.well-known/openid-configuration" | jq '{
  issuer,
  authorization_endpoint,
  token_endpoint,
  jwks_uri,
  id_token_signing_alg_values_supported,
  code_challenge_methods_supported,
  token_endpoint_auth_methods_supported,
  scopes_supported
}'

Check that:

• issuer exactly matches RUSTFS_IDENTITY_OPENID_CONFIG_URL
• authorization_endpoint, token_endpoint, and jwks_uri are present
• code_challenge_methods_supported includes S256
• token_endpoint_auth_methods_supported includes client_secret_post
• scopes_supported includes openid, profile, email, and any role scope you need

5.2 Validate RustFS Provider Visibility

curl -fsS "https://rustfs.example.com/rustfs/admin/v3/oidc/providers" | jq

The response should include the Authing provider unless hide_from_ui is enabled.

5.3 Test Browser Login

Open:

https://rustfs.example.com/rustfs/admin/v3/oidc/authorize/default

Expected flow:

1. Browser redirects to Authing.
2. The user signs in.
3. Authing redirects to /rustfs/admin/v3/oidc/callback/default?code=...&state=....
4. RustFS validates the ID token and issues STS credentials.
5. The browser lands on the RustFS Console and can use the expected permissions.

6. Troubleshooting

Symptom	Common cause	Fix
/oidc/providers does not show Authing	OIDC provider did not load, or RustFS was not restarted	Check environment variables and restart RustFS.
Authing reports redirect mismatch	Callback URL differs between Authing and RustFS	Use the exact /rustfs/admin/v3/oidc/callback/default URL.
RustFS reports missing code or state	Proxy dropped the query string	Preserve the full callback URL and query string.
Token exchange fails	Wrong client secret or unsupported token auth method	Confirm client_secret_post is allowed.
RustFS reports no id_token	Missing openid scope or non-OIDC OAuth flow	Include openid and use OIDC authorization code flow.
ID token verification fails	Issuer, audience, signing algorithm, or JWKS mismatch	Compare discovery metadata with RustFS config; prefer RS256.
Login succeeds but access is denied	No matching RustFS policy claim	Ensure roles or groups is in the ID token and equals a RustFS policy name.
Console redirects to an internal host	Missing RUSTFS_BROWSER_REDIRECT_URL or incorrect proxy headers	Set RUSTFS_BROWSER_REDIRECT_URL to the public browser origin.
Invalid or expired OIDC state	Callback reached a different RustFS node	Configure load-balancer session affinity for authorize and callback requests.

7. Production Checklist

• RustFS and Authing use HTTPS.
• Authing redirect URL is exact, not a broad wildcard.
• RUSTFS_BROWSER_REDIRECT_URL is set to the public RustFS browser origin.
• RUSTFS_IDENTITY_OPENID_REDIRECT_URI matches the registered Authing callback URL.
• Authing emits role or group claims in the ID token.
• Claim values match RustFS policy names.
• role_policy=consoleAdmin is not used as a permanent production shortcut.
• The load balancer preserves query strings.
• OIDC authorize and callback requests have session affinity to the same RustFS node.