github.com/minio/minio@v0.0.0-20240328213742-3f72439b8a27/docs/sts/web-identity.md (about) 1 # AssumeRoleWithWebIdentity [](https://slack.min.io) 2 3 ## Introduction 4 5 MinIO supports the standard AssumeRoleWithWebIdentity STS API to enable integration with OIDC/OpenID based identity provider environments. This allows the generation of temporary credentials with pre-defined access policies for applications/users to interact with MinIO object storage. 6 7 Calling AssumeRoleWithWebIdentity does not require the use of MinIO root or IAM credentials. Therefore, you can distribute an application (for example, on mobile devices) that requests temporary security credentials without including MinIO long lasting credentials in the application. Instead, the identity of the caller is validated by using a JWT id_token from the web identity provider. The temporary security credentials returned by this API consists of an access key, a secret key, and a security token. Applications can use these temporary security credentials to sign calls to MinIO API operations. 8 9 By default, the temporary security credentials created by AssumeRoleWithWebIdentity last for one hour. However, the optional DurationSeconds parameter can be used to specify the validity duration of the generated credentials. This value varies from 900 seconds (15 minutes) up to the maximum session duration of 365 days. 10 11 ## Configuring OpenID Identity Provider on MinIO 12 13 Configuration can be performed via MinIO's standard configuration API (i.e. using `mc admin config set/get` commands) or equivalently via environment variables. For brevity we show only environment variables here: 14 15 ``` 16 $ mc admin config set myminio identity_openid --env 17 KEY: 18 identity_openid[:name] enable OpenID SSO support 19 20 ARGS: 21 MINIO_IDENTITY_OPENID_ENABLE* (on|off) enable identity_openid target, default is 'off' 22 MINIO_IDENTITY_OPENID_DISPLAY_NAME (string) Friendly display name for this Provider/App 23 MINIO_IDENTITY_OPENID_CONFIG_URL* (url) openid discovery document e.g. "https://accounts.google.com/.well-known/openid-configuration" 24 MINIO_IDENTITY_OPENID_CLIENT_ID* (string) unique public identifier for apps e.g. "292085223830.apps.googleusercontent.com" 25 MINIO_IDENTITY_OPENID_CLIENT_SECRET* (string) secret for the unique public identifier for apps 26 MINIO_IDENTITY_OPENID_ROLE_POLICY (string) Set the IAM access policies applicable to this client application and IDP e.g. "app-bucket-write,app-bucket-list" 27 MINIO_IDENTITY_OPENID_CLAIM_NAME (string) JWT canned policy claim name (default: 'policy') 28 MINIO_IDENTITY_OPENID_SCOPES (csv) Comma separated list of OpenID scopes for server, defaults to advertised scopes from discovery document e.g. "email,admin" 29 MINIO_IDENTITY_OPENID_VENDOR (string) Specify vendor type for vendor specific behavior to checking validity of temporary credentials and service accounts on MinIO 30 MINIO_IDENTITY_OPENID_CLAIM_USERINFO (on|off) Enable fetching claims from UserInfo Endpoint for authenticated user 31 MINIO_IDENTITY_OPENID_KEYCLOAK_REALM (string) Specify Keycloak 'realm' name, only honored if vendor was set to 'keycloak' as value, if no realm is specified 'master' is default 32 MINIO_IDENTITY_OPENID_KEYCLOAK_ADMIN_URL (string) Specify Keycloak 'admin' REST API endpoint e.g. http://localhost:8080/auth/admin/ 33 MINIO_IDENTITY_OPENID_REDIRECT_URI_DYNAMIC (on|off) Enable 'Host' header based dynamic redirect URI (default: 'off') 34 MINIO_IDENTITY_OPENID_CLAIM_PREFIX (string) [DEPRECATED use 'claim_name'] JWT claim namespace prefix e.g. "customer1/" 35 MINIO_IDENTITY_OPENID_REDIRECT_URI (string) [DEPRECATED use env 'MINIO_BROWSER_REDIRECT_URL'] Configure custom redirect_uri for OpenID login flow callback 36 MINIO_IDENTITY_OPENID_COMMENT (sentence) optionally add a comment to this setting 37 ``` 38 39 ### Access Control Configuration Variables 40 41 Either `MINIO_IDENTITY_OPENID_ROLE_POLICY` (recommended) or `MINIO_IDENTITY_OPENID_CLAIM_NAME` must be specified but not both. See the section Access Control Policies to understand the differences between the two. 42 43 **NOTE**: When configuring multiple OpenID based authentication providers on a MinIO cluster, any number of Role Policy based providers may be configured, and at most one JWT Claim based provider may be configured. 44 45 <details><summary>Example 1: Two role policy providers</summary> 46 47 Sample environment variables: 48 49 ``` 50 MINIO_IDENTITY_OPENID_DISPLAY_NAME="my first openid" 51 MINIO_IDENTITY_OPENID_CONFIG_URL=http://myopenid.com/.well-known/openid-configuration 52 MINIO_IDENTITY_OPENID_CLIENT_ID="minio-client-app" 53 MINIO_IDENTITY_OPENID_CLIENT_SECRET="minio-client-app-secret" 54 MINIO_IDENTITY_OPENID_SCOPES="openid,groups" 55 MINIO_IDENTITY_OPENID_REDIRECT_URI="http://127.0.0.1:10000/oauth_callback" 56 MINIO_IDENTITY_OPENID_ROLE_POLICY="consoleAdmin" 57 58 MINIO_IDENTITY_OPENID_DISPLAY_NAME_APP2="another oidc" 59 MINIO_IDENTITY_OPENID_CONFIG_URL_APP2="http://anotheroidc.com/.well-known/openid-configuration" 60 MINIO_IDENTITY_OPENID_CLIENT_ID_APP2="minio-client-app-2" 61 MINIO_IDENTITY_OPENID_CLIENT_SECRET_APP2="minio-client-app-secret-2" 62 MINIO_IDENTITY_OPENID_SCOPES_APP2="openid,groups" 63 MINIO_IDENTITY_OPENID_REDIRECT_URI_APP2="http://127.0.0.1:10000/oauth_callback" 64 MINIO_IDENTITY_OPENID_ROLE_POLICY_APP2="readwrite" 65 66 ``` 67 </details> 68 69 <details><summary>Example 2: Single claim based provider</summary> 70 71 Sample environment variables: 72 73 ``` 74 MINIO_IDENTITY_OPENID_DISPLAY_NAME="my openid" 75 MINIO_IDENTITY_OPENID_CONFIG_URL=http://myopenid.com/.well-known/openid-configuration 76 MINIO_IDENTITY_OPENID_CLIENT_ID="minio-client-app" 77 MINIO_IDENTITY_OPENID_CLIENT_SECRET="minio-client-app-secret" 78 MINIO_IDENTITY_OPENID_SCOPES="openid,groups" 79 MINIO_IDENTITY_OPENID_REDIRECT_URI="http://127.0.0.1:10000/oauth_callback" 80 MINIO_IDENTITY_OPENID_CLAIM_NAME="groups" 81 ``` 82 </details> 83 84 ### Redirection from OpenID Provider 85 86 To login to MinIO, the user first loads the MinIO console on their browser, and selects the OpenID Provider they wish to use (the `MINIO_IDENTITY_OPENID_DISPLAY_NAME` value is shown here). The user is then redirected to the OpenID provider's login page and performs necessary login actions (e.g. entering credentials, responding to MFA authentication challenges, etc). After successful login, the user is redirected back to the MinIO console. This redirect URL is specified as a parameter by MinIO when the user is redirected to the OpenID Provider in the beginning. For some setups, extra configuration may be required for this step to work correctly. 87 88 For a simple setup where the user/client app accesses MinIO directly (i.e. with no intervening proxies/load-balancers), and each MinIO server (if there are more than one) has a unique domain name, this redirection should work automatically with no further configuration. For example, if the MinIO service is being accessed by the browser at the URL `https://minio-node-1.example.org`, the redirect URL will be `https://minio-node-1.example.org/oauth_callback` and all is well. 89 90 For deployments with a load-balancer (LB), it is required that the LB is configured to send requests from the same user/client-app to the same backend MinIO server (at least for the initial login request and subsequent redirection, as the OpenID auth flow's state parameter is currently local to the MinIO server). For this setup, set the `MINIO_BROWSER_REDIRECT_URL` parameter to the publicly/client-accessible endpoint for the MinIO Console. For example `MINIO_BROWSER_REDIRECT_URL=https://console.minio.example.org`. This will ensure that the redirect URL is set to `https://console.minio.example.org/oauth_callback` and the login process should work correctly. 91 92 For deployments employing DNS round-robin on a single domain to all the MinIO servers, it is possible that after redirection the browser may land on a different MinIO server. For example, the domain `console.minio.example.org` may resolve to `console-X.minio.example.org`, where `X` is `1`, `2`, `3` or `4`. For the login to work, if the user first landed on `console-1.minio.example.org`, they must be redirected back to the same place after logging in at the OpenID provider's web-page. To ensure this, set the `MINIO_IDENTITY_OPENID_REDIRECT_URI_DYNAMIC=on` parameter - this lets MinIO set the redirect URL based on the "Host" header of the (initial login) request. 93 94 The **deprecated** parameter `MINIO_IDENTITY_OPENID_REDIRECT_URI` works similar to the `MINIO_BROWSER_REDIRECT_URL` but needs to include the `/oauth_callback` suffix. Please do not use it, as it is sufficient to the set the `MINIO_BROWSER_REDIRECT_URL` parameter (which is required anyway for most load-balancer based setups to work correctly). This deprecated parameter **will be removed** in a future release. 95 96 ## Specifying Access Control with IAM Policies 97 98 The STS API authenticates the user by verifying the JWT provided in the request. However access to object storage resources are controlled via named IAM policies defined in the MinIO instance. Once authenticated via the STS API, the MinIO server applies one or more IAM policies to the generated credentials. MinIO's AssumeRoleWithWebIdentity implementation supports specifying IAM policies in two ways: 99 100 1. Role Policy (Recommended): When specified as part of the OpenID provider configuration, all users authenticating via this provider are authorized to (only) use the specified role policy. The policy to associate with such users is specified via the `role_policy` configuration parameter or the `MINIO_IDENTITY_OPENID_ROLE_POLICY` environment variable. The value is a comma-separated list of IAM access policy names already defined in the server. In this situation, the server prints a role ARN at startup that must be specified as a `RoleArn` API request parameter in the STS AssumeRoleWithWebIdentity API call. When using Role Policies, multiple OpenID providers and/or client applications (with unique client IDs) may be configured with independent role policies. Each configuration is assigned a unique RoleARN by the MinIO server and this is used to select the policies to apply to temporary credentials generated in the AssumeRoleWithWebIdentity call. 101 102 2. `id_token` claims: When the role policy is not configured, MinIO looks for a specific claim in the `id_token` (JWT) returned by the OpenID provider in the STS request. The default claim is `policy` and can be overridden by the `claim_name` configuration parameter or the `MINIO_IDENTITY_OPENID_CLAIM_NAME` environment variable. The claim value can be a string (comma-separated list) or an array of IAM access policy names defined in the server. A `RoleArn` API request parameter *must not* be specified in the STS AssumeRoleWithWebIdentity API call. 103 104 ## API Request Parameters 105 106 ### WebIdentityToken 107 108 The OAuth 2.0 id_token that is provided by the web identity provider. Application must get this token by authenticating the user who is using your application with a web identity provider before the application makes an AssumeRoleWithWebIdentity call. 109 110 | Params | Value | 111 | :-- | :-- | 112 | *Type* | *String* | 113 | *Length Constraints* | *Minimum length of 4. Maximum length of 2048.* | 114 | *Required* | *Yes* | 115 116 ### WebIdentityAccessToken (MinIO Extension) 117 118 There are situations when identity provider does not provide user claims in `id_token` instead it needs to be retrieved from UserInfo endpoint, this extension is only useful in this scenario. This is rare so use it accordingly depending on your Identity provider implementation. `access_token` is available as part of the OIDC authentication flow similar to `id_token`. 119 120 | Params | Value | 121 | :-- | :-- | 122 | *Type* | *String* | 123 | *Required* | *No* | 124 125 ### RoleArn 126 127 The role ARN to use. This must be specified if and only if the web identity provider is configured with a role policy. 128 129 | Params | Value | 130 | :-- | :-- | 131 | *Type* | *String* | 132 | *Required* | *No* | 133 134 ### Version 135 136 Indicates STS API version information, the only supported value is '2011-06-15'. This value is borrowed from AWS STS API documentation for compatibility reasons. 137 138 | Params | Value | 139 | :-- | :-- | 140 | *Type* | *String* | 141 | *Required* | *Yes* | 142 143 ### DurationSeconds 144 145 The duration, in seconds. The value can range from 900 seconds (15 minutes) up to 365 days. If value is higher than this setting, then operation fails. By default, the value is set to 3600 seconds. If no *DurationSeconds* is specified expiry seconds is obtained from *WebIdentityToken*. 146 147 | Params | Value | 148 | :-- | :-- | 149 | *Type* | *Integer* | 150 | *Valid Range* | *Minimum value of 900. Maximum value of 31536000.* | 151 | *Required* | *No* | 152 153 ### Policy 154 155 An IAM policy in JSON format that you want to use as an inline session policy. This parameter is optional. Passing policies to this operation returns new temporary credentials. The resulting session's permissions are the intersection of the canned policy name and the policy set here. You cannot use this policy to grant more permissions than those allowed by the canned policy name being assumed. 156 157 | Params | Value | 158 | :-- | :-- | 159 | *Type* | *String* | 160 | *Valid Range* | *Minimum length of 1. Maximum length of 2048.* | 161 | *Required* | *No* | 162 163 ### Response Elements 164 165 XML response for this API is similar to [AWS STS AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html#API_AssumeRoleWithWebIdentity_ResponseElements) 166 167 ### Errors 168 169 XML error response for this API is similar to [AWS STS AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html#API_AssumeRoleWithWebIdentity_Errors) 170 171 ## Sample `POST` Request 172 173 ``` 174 http://minio.cluster:9000?Action=AssumeRoleWithWebIdentity&DurationSeconds=3600&WebIdentityToken=eyJ4NXQiOiJOVEF4Wm1NeE5ETXlaRGczTVRVMVpHTTBNekV6T0RKaFpXSTRORE5sWkRVMU9HRmtOakZpTVEiLCJraWQiOiJOVEF4Wm1NeE5ETXlaRGczTVRVMVpHTTBNekV6T0RKaFpXSTRORE5sWkRVMU9HRmtOakZpTVEiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiYXpwIjoiUG9FZ1hQNnVWTzQ1SXNFTlJuZ0RYajVBdTVZYSIsImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImV4cCI6MTU0MTgwOTU4MiwiaWF0IjoxNTQxODA1OTgyLCJqdGkiOiI2Y2YyMGIwZS1lNGZmLTQzZmQtYTdiYS1kYTc3YTE3YzM2MzYifQ.Jm29jPliRvrK6Os34nSK3rhzIYLFjE__zdVGNng3uGKXGKzP3We_i6NPnhA0szJXMOKglXzUF1UgSz8MctbaxFS8XDusQPVe4LkB_45hwBm6TmBxzui911nt-1RbBLN_jZIlvl2lPrbTUH5hSn9kEkph6seWanTNQpz9tNEoVa6R_OX3kpJqxe8tLQUWw453A1JTwFNhdHa6-f1K8_Q_eEZ_4gOYINQ9t_fhTibdbkXZkJQFLop-Jwoybi9s4nwQU_dATocgcufq5eCeNItQeleT-23lGxIz0X7CiJrJynYLdd-ER0F77SumqEb5iCxhxuf4H7dovwd1kAmyKzLxpw&Version=2011-06-15 175 ``` 176 177 ## Sample Response 178 179 ``` 180 <?xml version="1.0" encoding="UTF-8"?> 181 <AssumeRoleWithWebIdentityResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/"> 182 <AssumeRoleWithWebIdentityResult> 183 <AssumedRoleUser> 184 <Arn/> 185 <AssumeRoleId/> 186 </AssumedRoleUser> 187 <Credentials> 188 <AccessKeyId>Y4RJU1RNFGK48LGO9I2S</AccessKeyId> 189 <SecretAccessKey>sYLRKS1Z7hSjluf6gEbb9066hnx315wHTiACPAjg</SecretAccessKey> 190 <Expiration>2019-08-08T20:26:12Z</Expiration> 191 <SessionToken>eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJZNFJKVTFSTkZHSzQ4TEdPOUkyUyIsImF1ZCI6IlBvRWdYUDZ1Vk80NUlzRU5SbmdEWGo1QXU1WWEiLCJhenAiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiZXhwIjoxNTQxODExMDcxLCJpYXQiOjE1NDE4MDc0NzEsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIiwianRpIjoiYTBiMjc2MjktZWUxYS00M2JmLTg3MzktZjMzNzRhNGNkYmMwIn0.ewHqKVFTaP-j_kgZrcOEKroNUjk10GEp8bqQjxBbYVovV0nHO985VnRESFbcT6XMDDKHZiWqN2vi_ETX_u3Q-w</SessionToken> 192 </Credentials> 193 </AssumeRoleWithWebIdentityResult> 194 <ResponseMetadata/> 195 </AssumeRoleWithWebIdentityResponse> 196 ``` 197 198 ## Using WebIdentity API 199 200 ``` 201 export MINIO_ROOT_USER=minio 202 export MINIO_ROOT_PASSWORD=minio123 203 export MINIO_IDENTITY_OPENID_CONFIG_URL=https://accounts.google.com/.well-known/openid-configuration 204 export MINIO_IDENTITY_OPENID_CLIENT_ID="843351d4-1080-11ea-aa20-271ecba3924a" 205 # Optional: Allow to specify the requested OpenID scopes (OpenID only requires the `openid` scope) 206 #export MINIO_IDENTITY_OPENID_SCOPES="openid,profile,email" 207 minio server /mnt/export 208 ``` 209 210 or using `mc` 211 212 ``` 213 mc admin config get myminio identity_openid 214 identity_openid config_url=https://accounts.google.com/.well-known/openid-configuration client_id=843351d4-1080-11ea-aa20-271ecba3924a 215 ``` 216 217 Testing with an example 218 > Visit [Google Developer Console](https://console.cloud.google.com) under Project, APIs, Credentials to get your OAuth2 client credentials. Add `http://localhost:8080/oauth2/callback` as a valid OAuth2 Redirect URL. 219 220 ``` 221 $ go run web-identity.go -cid 204367807228-ok7601k6gj1pgge7m09h7d79co8p35xx.apps.googleusercontent.com -csec XsT_PgPdT1nO9DD45rMLJw7G 222 2018/12/26 17:49:36 listening on http://localhost:8080/ 223 ``` 224 225 > NOTE: for a reasonable test outcome, make sure the assumed user has at least permission/policy to list all buckets. That policy would look like below: 226 227 ``` 228 { 229 "version": "2012-10-17", 230 "statement": [ 231 { 232 "effect": "Allow", 233 "action": [ 234 "s3:ListAllMyBuckets" 235 ], 236 "resource": [ 237 "arn:aws:s3:::*" 238 ] 239 } 240 ] 241 } 242 ``` 243 244 ## Authorization Flow 245 246 - Visit <http://localhost:8080>, login will direct the user to the Google OAuth2 Auth URL to obtain a permission grant. 247 - The redirection URI (callback handler) receives the OAuth2 callback, verifies the state parameter, and obtains a Token. 248 - Using the id_token the callback handler further talks to Google OAuth2 Token URL to obtain an JWT id_token. 249 - Once obtained the JWT id_token is further sent to STS endpoint i.e MinIO to retrieve temporary credentials. 250 - Temporary credentials are displayed on the browser upon successful retrieval. 251 252 ## Using MinIO Console 253 254 To support WebIdentity based login for MinIO Console, set openid configuration and restart MinIO 255 256 ``` 257 mc admin config set myminio identity_openid config_url="<CONFIG_URL>" client_id="<client_identifier>" 258 ``` 259 260 ``` 261 mc admin service restart myminio 262 ``` 263 264 Sample URLs for Keycloak are 265 266 `config_url` - `http://localhost:8080/auth/realms/demo/.well-known/openid-configuration` 267 268 JWT token returned by the Identity Provider should include a custom claim for the policy, this is required to create a STS user in MinIO. The name of the custom claim could be either `policy` or `<NAMESPACE_PREFIX>policy`. If there is no namespace then `claim_prefix` can be ignored. For example if the custom claim name is `https://min.io/policy` then, `claim_prefix` should be set as `https://min.io/`. 269 270 - Open MinIO Console and click `Login with SSO` 271 - The user will be redirected to the Identity Provider login page 272 - Upon successful login on Identity Provider page the user will be automatically logged into MinIO Console. 273 274 ## Explore Further 275 276 - [MinIO Admin Complete Guide](https://min.io/docs/minio/linux/reference/minio-mc-admin.html) 277 - [The MinIO documentation website](https://min.io/docs/minio/linux/index.html)