github.com/minio/minio@v0.0.0-20240328213742-3f72439b8a27/docs/sts/keycloak.md (about)

     1  # Keycloak Quickstart Guide [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io)
     2  
     3  Keycloak is an open source Identity and Access Management solution aimed at modern applications and services, this document covers configuring Keycloak identity provider support with MinIO.
     4  
     5  ## Prerequisites
     6  
     7  Configure and install keycloak server by following [Keycloak Installation Guide](https://www.keycloak.org/docs/latest/server_installation/#installing-the-software).
     8  For a quick installation, docker-compose reference configs are also available on the [Keycloak GitHub](https://github.com/keycloak/keycloak-containers/tree/main/docker-compose-examples).
     9  
    10  ### Configure Keycloak Realm
    11  
    12  - Go to Clients
    13    - Click on account
    14      - Settings
    15      - Change `Access Type` to `confidential`.
    16      - Save
    17    - Click on credentials tab
    18      - Copy the `Secret` to clipboard.
    19      - This value is needed for `MINIO_IDENTITY_OPENID_CLIENT_SECRET` for MinIO.
    20  
    21  - Go to Users
    22    - Click on the user
    23    - Attribute, add a new attribute `Key` is `policy`, `Value` is name of the `policy` on MinIO (ex: `readwrite`)
    24    - Add and Save
    25  
    26  - Go to Clients
    27    - Click on `account`
    28    - Settings, set `Valid Redirect URIs` to `*`, expand `Advanced Settings` and set `Access Token Lifespan` to `1 Hours`
    29    - Save
    30  
    31  - Go to Clients
    32    - Click on `account`
    33    - Mappers
    34    - Create
    35      - `Name` with any text
    36      - `Mapper Type` is `User Attribute`
    37      - `User Attribute` is `policy`
    38      - `Token Claim Name` is `policy`
    39      - `Claim JSON Type` is `string`
    40    - Save
    41  
    42  - Open <http://localhost:8080/auth/realms/{your-realm-name}/.well-known/openid-configuration> to verify OpenID discovery document, verify it has `authorization_endpoint` and `jwks_uri`
    43  
    44  ### Enable Keycloak Admin REST API support
    45  
    46  Before being able to authenticate against the Admin REST API using a client_id and a client_secret you need to make sure the client is configured as it follows:
    47  
    48  - `account` client_id is a confidential client that belongs to the realm `{realm}`
    49  - `account` client_id is has **Service Accounts Enabled** option enabled.
    50  - `account` client_id has a custom "Audience" mapper, in the Mappers section.
    51    - Included Client Audience: security-admin-console
    52  
    53  #### Adding 'admin' Role
    54  
    55  - Go to Roles
    56    - Add new Role `admin` with Description `${role_admin}`.
    57    - Add this Role into compositive role named `default-roles-{realm}` - `{realm}` should be replaced with whatever realm you created from `prerequisites` section. This role is automatically trusted in the 'Service Accounts' tab.
    58  
    59  - Check that `account` client_id has the role 'admin' assigned in the "Service Account Roles" tab.
    60  
    61  After that, you will be able to obtain an id_token for the Admin REST API using client_id and client_secret:
    62  
    63  ```
    64  curl \
    65    -d "client_id=<YOUR_CLIENT_ID>" \
    66    -d "client_secret=<YOUR_CLIENT_SECRET>" \
    67    -d "grant_type=client_credentials" \
    68    "http://localhost:8080/auth/realms/{realm}/protocol/openid-connect/token"
    69  ```
    70  
    71  The result will be a JSON document. To invoke the API you need to extract the value of the access_token property. You can then invoke the API by including the value in the Authorization header of requests to the API.
    72  
    73  The following example shows how to get the details of the user with `{userid}` from `{realm}` realm:
    74  
    75  ```
    76  curl \
    77    -H "Authorization: Bearer eyJhbGciOiJSUz..." \
    78    "http://localhost:8080/auth/admin/realms/{realm}/users/{userid}"
    79  ```
    80  
    81  ### Configure MinIO
    82  
    83  ```
    84  export MINIO_ROOT_USER=minio
    85  export MINIO_ROOT_PASSWORD=minio123
    86  minio server /mnt/export
    87  ```
    88  
    89  Here are all the available options to configure OpenID connect
    90  
    91  ```
    92  mc admin config set myminio/ identity_openid
    93  
    94  KEY:
    95  identity_openid  enable OpenID SSO support
    96  
    97  ARGS:
    98  config_url*   (url)       openid discovery document e.g. "https://accounts.google.com/.well-known/openid-configuration"
    99  client_id     (string)    unique public identifier for apps e.g. "292085223830.apps.googleusercontent.com"
   100  claim_name    (string)    JWT canned policy claim name, defaults to "policy"
   101  claim_prefix  (string)    JWT claim namespace prefix e.g. "customer1/"
   102  scopes        (csv)       Comma separated list of OpenID scopes for server, defaults to advertised scopes from discovery document e.g. "email,admin"
   103  comment       (sentence)  optionally add a comment to this setting
   104  ```
   105  
   106  and ENV based options
   107  
   108  ```
   109  mc admin config set myminio/ identity_openid --env
   110  
   111  KEY:
   112  identity_openid  enable OpenID SSO support
   113  
   114  ARGS:
   115  MINIO_IDENTITY_OPENID_CONFIG_URL*   (url)       openid discovery document e.g. "https://accounts.google.com/.well-known/openid-configuration"
   116  MINIO_IDENTITY_OPENID_CLIENT_ID     (string)    unique public identifier for apps e.g. "292085223830.apps.googleusercontent.com"
   117  MINIO_IDENTITY_OPENID_CLAIM_NAME    (string)    JWT canned policy claim name, defaults to "policy"
   118  MINIO_IDENTITY_OPENID_CLAIM_PREFIX  (string)    JWT claim namespace prefix e.g. "customer1/"
   119  MINIO_IDENTITY_OPENID_SCOPES        (csv)       Comma separated list of OpenID scopes for server, defaults to advertised scopes from discovery document e.g. "email,admin"
   120  MINIO_IDENTITY_OPENID_COMMENT       (sentence)  optionally add a comment to this setting
   121  ```
   122  
   123  Set `identity_openid` config with `config_url`, `client_id` and restart MinIO
   124  
   125  ```
   126  ~ mc admin config set myminio identity_openid config_url="http://localhost:8080/auth/realms/{your-realm-name}/.well-known/openid-configuration" client_id="account"
   127  ```
   128  
   129  > NOTE: You can configure the `scopes` parameter to restrict the OpenID scopes requested by minio to the IdP, for example, `"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
   130  
   131  Once successfully set restart the MinIO instance.
   132  
   133  ```
   134  mc admin service restart myminio
   135  ```
   136  
   137  ### Using WebIdentiy API
   138  
   139  Client ID can be found by clicking any of the clients listed [here](http://localhost:8080/auth/admin/master/console/#/realms/minio/clients). If you have followed the above steps docs, the default Client ID will be `account`.
   140  
   141  ```
   142  $ go run docs/sts/web-identity.go -cid account -csec 072e7f00-4289-469c-9ab2-bbe843c7f5a8  -config-ep "http://localhost:8080/auth/realms/minio/.well-known/openid-configuration" -port 8888
   143  2018/12/26 17:49:36 listening on http://localhost:8888/
   144  ```
   145  
   146  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:
   147  
   148  ```
   149  {
   150    "buckets": [
   151      "bucket-x"
   152    ],
   153    "credentials": {
   154      "AccessKeyID": "6N2BALX7ELO827DXS3GK",
   155      "SecretAccessKey": "23JKqAD+um8ObHqzfIh+bfqwG9V8qs9tFY6MqeFR+xxx",
   156      "SessionToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiI2TjJCQUxYN0VMTzgyN0RYUzNHSyIsImFjciI6IjAiLCJhdWQiOiJhY2NvdW50IiwiYXV0aF90aW1lIjoxNTY5OTEwNTUyLCJhenAiOiJhY2NvdW50IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJleHAiOjE1Njk5MTQ1NTQsImlhdCI6MTU2OTkxMDk1NCwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgxL2F1dGgvcmVhbG1zL2RlbW8iLCJqdGkiOiJkOTk4YTBlZS01NDk2LTQ4OWYtYWJlMi00ZWE5MjJiZDlhYWYiLCJuYmYiOjAsInBvbGljeSI6InJlYWR3cml0ZSIsInByZWZlcnJlZF91c2VybmFtZSI6Im5ld3VzZXIxIiwic2Vzc2lvbl9zdGF0ZSI6IjJiYTAyYTI2LWE5MTUtNDUxNC04M2M1LWE0YjgwYjc4ZTgxNyIsInN1YiI6IjY4ZmMzODVhLTA5MjItNGQyMS04N2U5LTZkZTdhYjA3Njc2NSIsInR5cCI6IklEIn0._UG_-ZHgwdRnsp0gFdwChb7VlbPs-Gr_RNUz9EV7TggCD59qjCFAKjNrVHfOSVkKvYEMe0PvwfRKjnJl3A_mBA"",
   157      "SignerType": 1
   158    }
   159  }
   160  ```
   161  
   162  > 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.
   163  
   164  These credentials can now be used to perform MinIO API operations.
   165  
   166  ### Using MinIO Console
   167  
   168  - Open MinIO URL on the browser, lets say <http://localhost:9000/>
   169  - Click on `Login with SSO`
   170  - 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,
   171    the user should see now the buckets and objects they have access to.
   172  
   173  ## Explore Further
   174  
   175  - [MinIO STS Quickstart Guide](https://min.io/docs/minio/linux/developers/security-token-service.html)
   176  - [The MinIO documentation website](https://min.io/docs/minio/linux/index.html)