github.com/minio/minio@v0.0.0-20240328213742-3f72439b8a27/docs/sts/README.md (about) 1 # MinIO STS Quickstart Guide [](https://slack.min.io) 2 3 The MinIO Security Token Service (STS) is an endpoint service that enables clients to request temporary credentials for MinIO resources. Temporary credentials work almost identically to default admin credentials, with some differences: 4 5 - Temporary credentials are short-term, as the name implies. They can be configured to last for anywhere from a few minutes to several hours. After the credentials expire, MinIO no longer recognizes them or allows any kind of access from API requests made with them. 6 - Temporary credentials do not need to be stored with the application but are generated dynamically and provided to the application when requested. When (or even before) the temporary credentials expire, the application can request new credentials. 7 8 Following are advantages for using temporary credentials: 9 10 - Eliminates the need to embed long-term credentials with an application. 11 - Eliminates the need to provide access to buckets and objects without having to define static credentials. 12 - Temporary credentials have a limited lifetime, there is no need to rotate them or explicitly revoke them. Expired temporary credentials cannot be reused. 13 14 ## Identity Federation 15 16 | AuthN | Description | 17 | :---------------------- | ------------------------------------------ | 18 | [**WebIdentity**](https://github.com/minio/minio/blob/master/docs/sts/web-identity.md) | Let users request temporary credentials using any OpenID(OIDC) compatible web identity providers such as KeyCloak, Dex, Facebook, Google etc. | 19 | [**AD/LDAP**](https://github.com/minio/minio/blob/master/docs/sts/ldap.md) | Let AD/LDAP users request temporary credentials using AD/LDAP username and password. | 20 | [**AssumeRole**](https://github.com/minio/minio/blob/master/docs/sts/assume-role.md) | Let MinIO users request temporary credentials using user access and secret keys. | 21 22 ### Understanding JWT Claims 23 24 > NOTE: JWT claims are only meant for WebIdentity and ClientGrants. 25 > AssumeRole or LDAP users can skip the entire portion and directly visit one of the links below. 26 > 27 > - [**AssumeRole**](https://github.com/minio/minio/blob/master/docs/sts/assume-role.md) 28 > - [**AD/LDAP**](https://github.com/minio/minio/blob/master/docs/sts/ldap.md) 29 30 The id_token received is a signed JSON Web Token (JWT). Use a JWT decoder to decode the id_token to access the payload of the token that includes following JWT claims, `policy` claim is mandatory and should be present as part of your JWT claim. Without this claim the generated credentials will not have access to any resources on the server, using these credentials application would receive 'Access Denied' errors. 31 32 | Claim Name | Type | Claim Value | 33 |:----------:|:-------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| 34 | policy | _string_ or _[]string_ or _comma_separated_value_ | Canned policy name to be applied for STS credentials. (Mandatory) - This can be configured to any desired value such as `roles` or `groups` by setting the environment variable `MINIO_IDENTITY_OPENID_CLAIM_NAME` | 35 36 ## Get started 37 38 In this document we will explain in detail on how to configure all the prerequisites. 39 40 > NOTE: If you are interested in AssumeRole API only, skip to [here](https://github.com/minio/minio/blob/master/docs/sts/assume-role.md) 41 42 ### Prerequisites 43 44 - [Configuring keycloak](https://github.com/minio/minio/blob/master/docs/sts/keycloak.md) or [Configuring Casdoor](https://github.com/minio/minio/blob/master/docs/sts/casdoor.md) 45 - [Configuring etcd](https://github.com/minio/minio/blob/master/docs/sts/etcd.md) 46 47 ### Setup MinIO with Identity Provider 48 49 Make sure we have followed the previous step and configured each software independently, once done we can now proceed to use MinIO STS API and MinIO server to use these credentials to perform object API operations. 50 51 #### KeyCloak 52 53 ``` 54 export MINIO_ROOT_USER=minio 55 export MINIO_ROOT_PASSWORD=minio123 56 export MINIO_IDENTITY_OPENID_CONFIG_URL=http://localhost:8080/auth/realms/demo/.well-known/openid-configuration 57 export MINIO_IDENTITY_OPENID_CLIENT_ID="843351d4-1080-11ea-aa20-271ecba3924a" 58 minio server /mnt/data 59 ``` 60 61 #### Casdoor 62 63 ``` 64 export MINIO_ROOT_USER=minio 65 export MINIO_ROOT_PASSWORD=minio123 66 export MINIO_IDENTITY_OPENID_CONFIG_URL=http://CASDOOR_ENDPOINT/.well-known/openid-configuration 67 export MINIO_IDENTITY_OPENID_CLIENT_ID="843351d4-1080-11ea-aa20-271ecba3924a" 68 minio server /mnt/data 69 ``` 70 71 ### Using WebIdentiy API 72 73 On another terminal run `web-identity.go` a sample client application which obtains JWT id_tokens from an identity provider, in our case its Keycloak. Uses the returned id_token response to get new temporary credentials from the MinIO server using the STS API call `AssumeRoleWithWebIdentity`. 74 75 ``` 76 $ go run docs/sts/web-identity.go -cid account -csec 072e7f00-4289-469c-9ab2-bbe843c7f5a8 -config-ep "http://localhost:8080/auth/realms/demo/.well-known/openid-configuration" -port 8888 77 2018/12/26 17:49:36 listening on http://localhost:8888/ 78 ``` 79 80 This will open the login page of keycloak, upon successful login, STS credentials along with any buckets discovered using the credentials will be printed on the screen, for example: 81 82 ``` 83 { 84 "buckets": [ 85 "bucket-x" 86 ], 87 "credentials": { 88 "AccessKeyID": "6N2BALX7ELO827DXS3GK", 89 "SecretAccessKey": "23JKqAD+um8ObHqzfIh+bfqwG9V8qs9tFY6MqeFR+xxx", 90 "SessionToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiI2TjJCQUxYN0VMTzgyN0RYUzNHSyIsImFjciI6IjAiLCJhdWQiOiJhY2NvdW50IiwiYXV0aF90aW1lIjoxNTY5OTEwNTUyLCJhenAiOiJhY2NvdW50IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJleHAiOjE1Njk5MTQ1NTQsImlhdCI6MTU2OTkxMDk1NCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgxL2F1dGgvcmVhbG1zL2RlbW8iLCJqdGkiOiJkOTk4YTBlZS01NDk2LTQ4OWYtYWJlMi00ZWE5MjJiZDlhYWYiLCJuYmYiOjAsInBvbGljeSI6InJlYWR3cml0ZSIsInByZWZlcnJlZF91c2VybmFtZSI6Im5ld3VzZXIxIiwic2Vzc2lvbl9zdGF0ZSI6IjJiYTAyYTI2LWE5MTUtNDUxNC04M2M1LWE0YjgwYjc4ZTgxNyIsInN1YiI6IjY4ZmMzODVhLTA5MjItNGQyMS04N2U5LTZkZTdhYjA3Njc2NSIsInR5cCI6IklEIn0._UG_-ZHgwdRnsp0gFdwChb7VlbPs-Gr_RNUz9EV7TggCD59qjCFAKjNrVHfOSVkKvYEMe0PvwfRKjnJl3A_mBA"", 91 "SignerType": 1 92 } 93 } 94 ``` 95 96 > NOTE: You can use the `-cscopes` parameter to restrict the requested scopes, for example to `"openid,policy_role_attribute"`, being `policy_role_attribute` a client_scope / client_mapper that maps a role attribute called policy to a `policy` claim returned by Keycloak. 97 98 These credentials can now be used to perform MinIO API operations. 99 100 ### Using MinIO Console 101 102 - Open MinIO URL on the browser, lets say <http://localhost:9000/> 103 - Click on `Login with SSO` 104 - User will be redirected to the Keycloak user login page, upon successful login the user will be redirected to MinIO page and logged in automatically, 105 the user should see now the buckets and objects they have access to. 106 107 ## Explore Further 108 109 - [MinIO Admin Complete Guide](https://min.io/docs/minio/linux/reference/minio-mc-admin.html) 110 - [The MinIO documentation website](https://min.io/docs/minio/linux/index.html)