ceph/doc/radosgw/keycloak.rst

   1 .. _radosgw_keycloak:
   2
   3 =================================
   4 Integrating Keycloak with RadosGW
   5 =================================
   6
   7 If Keycloak is set up as an OpenID Connect Identity Provider, it can be used by
   8 mobile apps and web apps to authenticate their users. By using the web token
   9 returned by the authentication process, a mobile app or web app can call
  10 AssumeRoleWithWebIdentity, receive a set of temporary S3 credentials, and use
  11 those credentials to make S3 calls.
  12
  13 Setting up Keycloak
  14 ===================
  15
  16 Documentation for installing and operating Keycloak can be found here:
  17 https://www.keycloak.org/guides.
  18
  19 Configuring Keycloak to talk to RGW
  20 ===================================
  21
  22 To configure Keycloak to talk to RGW, add the following configurables::
  23
  24   [client.radosgw.gateway]
  25   rgw sts key = {sts key for encrypting/ decrypting the session token}
  26   rgw s3 auth use sts = true
  27
  28 Fetching a web token with Keycloak
  29 ==================================
  30
  31 Several examples of apps authenticating with Keycloak can be found here:
  32 https://github.com/keycloak/keycloak-quickstarts/blob/latest/docs/getting-started.md.
  33
  34 Here you might consider the example of the app-profile-jee-jsp app (in the link
  35 above). To fetch the access token (web token) for such an application using the
  36 grant type 'client_credentials', one can use client id and client secret as
  37 follows::
  38
  39     KC_REALM=demo
  40     KC_CLIENT=<client id>
  41     KC_CLIENT_SECRET=<client secret>
  42     KC_SERVER=<host>:8080
  43     KC_CONTEXT=auth
  44
  45     # Request Tokens for credentials
  46     KC_RESPONSE=$( \
  47     curl -k -v -X POST \
  48     -H "Content-Type: application/x-www-form-urlencoded" \
  49     -d "scope=openid" \
  50     -d "grant_type=client_credentials" \
  51     -d "client_id=$KC_CLIENT" \
  52     -d "client_secret=$KC_CLIENT_SECRET" \
  53     "http://$KC_SERVER/$KC_CONTEXT/realms/$KC_REALM/protocol/openid-connect/token" \
  54     | jq .
  55     )
  56
  57     KC_ACCESS_TOKEN=$(echo $KC_RESPONSE| jq -r .access_token)
  58
  59 It is also possible to fetch an access token for a particular user with the
  60 grant type 'password'. To fetch such an access token, use client id, client
  61 secret, username, and password as follows::
  62
  63     KC_REALM=demo
  64     KC_USERNAME=<username>
  65     KC_PASSWORD=<userpassword>
  66     KC_CLIENT=<client id>
  67     KC_CLIENT_SECRET=<client secret>
  68     KC_SERVER=<host>:8080
  69     KC_CONTEXT=auth
  70
  71    # Request Tokens for credentials
  72     KC_RESPONSE=$( \
  73     curl -k -v -X POST \
  74     -H "Content-Type: application/x-www-form-urlencoded" \
  75     -d "scope=openid" \
  76     -d "grant_type=password" \
  77     -d "client_id=$KC_CLIENT" \
  78     -d "client_secret=$KC_CLIENT_SECRET" \
  79     -d "username=$KC_USERNAME" \
  80     -d "password=$KC_PASSWORD" \
  81     "http://$KC_SERVER/$KC_CONTEXT/realms/$KC_REALM/protocol/openid-connect/token" \
  82     | jq .
  83     )
  84
  85     KC_ACCESS_TOKEN=$(echo $KC_RESPONSE| jq -r .access_token)
  86
  87 ``KC_ACCESS_TOKEN`` can be used to invoke ``AssumeRoleWithWebIdentity``: see
  88 :doc:`STS`.
  89
  90 Adding tags to a user in Keycloak
  91 =================================
  92
  93 To create a user in Keycloak and add tags to it as its attributes, follow these
  94 steps:
  95
  96 #. Add a user:
  97
  98    .. image:: ../images/keycloak-adduser.png
  99       :align: center
 100
 101 #. Add user details:
 102
 103    .. image:: ../images/keycloak-userdetails.png
 104       :align: center
 105
 106 #. Add user credentials:
 107
 108    .. image:: ../images/keycloak-usercredentials.png
 109       :align: center
 110
 111 #. Add tags to the 'attributes' tab of the user:
 112
 113    .. image:: ../images/keycloak-usertags.png
 114       :align: center
 115
 116 #. Add a protocol mapper that maps the user attribute to a client:
 117
 118    .. image:: ../images/keycloak-userclientmapper.png
 119       :align: center
 120
 121 After these steps have been completed, the tag 'Department' will appear in the
 122 JWT (web token), under the 'https://aws.amazon.com/tags' namespace.
 123
 124 Tags can be verified by performing token introspection on a JWT. To introspect
 125 a token, use ``client id`` and ``client secret`` as follows::
 126
 127     KC_REALM=demo
 128     KC_CLIENT=<client id>
 129     KC_CLIENT_SECRET=<client secret>
 130     KC_SERVER=<host>:8080
 131     KC_CONTEXT=auth
 132
 133     curl -k -v \
 134     -X POST \
 135     -u "$KC_CLIENT:$KC_CLIENT_SECRET" \
 136     -d "token=$KC_ACCESS_TOKEN" \
 137     "http://$KC_SERVER/$KC_CONTEXT/realms/$KC_REALM/protocol/openid-connect/token/introspect" \
 138     | jq .