reclaim.rst (9053B)
1 .. _reclaimID-Identity-Provider: 2 3 re:claimID 4 ---------- 5 6 .. note:: 7 8 re:claimID is under development; expect bugs and incompatible changes. See 9 :doc:`/status`. 10 11 The re:claimID Identity Provider (IdP) is a decentralized IdP service. 12 It allows its users to manage and authorize third parties to access 13 their identity attributes such as email or shipping addresses. 14 15 It basically mimics the concepts of centralized IdPs, such as those 16 offered by Google or Facebook. Like other IdPs, reclaimID features an 17 (optional) OpenID Connect 1.0-compliant protocol layer that can be used 18 for websites to integrate reclaimID as an Identity Provider with little 19 effort. 20 21 .. _Managing-Attributes: 22 23 Managing Attributes 24 ~~~~~~~~~~~~~~~~~~~ 25 26 Before adding attributes to an identity, you must first create an ego: 27 28 :: 29 30 $ gnunet-identity --create="user" 31 32 Henceforth, you can manage a new user profile of the user "user". 33 34 To add an email address to your user profile, simply use the 35 ``gnunet-reclaim`` command line tool:: 36 37 :: 38 39 $ gnunet-reclaim -e "user" -a "email" -V "username@example.gnunet" 40 41 All of your attributes can be listed using the ``gnunet-reclaim`` 42 command line tool as well: 43 44 :: 45 46 $ gnunet-reclaim -e "user" -D 47 48 Currently, and by default, attribute values are interpreted as plain 49 text. In the future there might be more value types such as X.509 50 certificate credentials. 51 52 .. _Managing-Credentials: 53 54 Managing Credentials 55 ~~~~~~~~~~~~~~~~~~~~ 56 57 Attribute values may reference a claim in a third party attested 58 credential. Such a credential can have a variety of formats such as 59 JSON-Web-Tokens or X.509 certificates. Currently, reclaimID only 60 supports JSON-Web-Token credentials. 61 62 To add a credential to your user profile, invoke the ``gnunet-reclaim`` 63 command line tool as follows: 64 65 :: 66 67 $ gnunet-reclaim -e "user"\ 68 --credential-name="email"\ 69 --credential-type="JWT"\ 70 --value="ey..." 71 72 All of your credentials can be listed using the ``gnunet-reclaim`` 73 command line tool as well: 74 75 :: 76 77 $ gnunet-reclaim -e "user" --credentials 78 79 In order to add an attribe backed by a credential, specify the attribute 80 value as the claim name in the credential to reference along with the 81 credential ID: 82 83 :: 84 85 $ gnunet-reclaim -e "user"\ 86 --add="email"\ 87 --value="verified_email"\ 88 --credential-id="<CREDENTIAL_ID>" 89 90 .. _Sharing-Attributes-with-Third-Parties: 91 92 Sharing Attributes with Third Parties 93 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 94 95 If you want to allow a third party such as a website or friend to access 96 to your attributes (or a subset thereof) execute: 97 98 :: 99 100 $ TICKET=$(gnunet-reclaim -e "user"\ 101 -r "$RP_KEY"\ 102 -i "attribute1,attribute2,...") 103 104 The command will return a \"ticket\" string. You must give $TICKET to 105 the requesting third party. 106 107 $RP_KEY is the public key of the third party and 108 \"attribute1,attribute2,\...\" is a comma-separated list of attribute 109 names, such as \"email,name,\...\", that you want to share. 110 111 The third party may retrieve the key in string format for use in the 112 above call using \"gnunet-identity\": 113 114 .. code-block:: shell 115 116 $ RP_KEY=$(gnunet-identity -d | grep "relyingparty" | awk '{print $3}') 117 118 The third party can then retrieve your shared identity attributes using: 119 120 .. code-block:: shell 121 122 $ gnunet-reclaim -e "relyingparty" -C "ticket" 123 124 Where \"relyingparty\" is the name for the identity behind $RP_KEY that 125 the requesting party is using. This will retrieve and list the shared 126 identity attributes. The above command will also work if the user is 127 currently offline since the attributes are retrieved from GNS. Further, 128 $TICKET can be re-used later to retrieve up-to-date attributes in case 129 \"friend\" has changed the value(s). For instance, because his email 130 address changed. 131 132 To list all given authorizations (tickets) you can execute: 133 134 .. code-block:: shell 135 136 $ gnunet-reclaim -e "user" -T 137 138 .. _Revoking-Authorizations-of-Third-Parties: 139 140 Revoking Authorizations of Third Parties 141 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 142 143 If you want to revoke the access of a third party to your attributes you 144 can execute: 145 146 :: 147 148 $ gnunet-reclaim -e "user" -R $TICKET 149 150 This will prevent the third party from accessing the attribute in the 151 future. Please note that if the third party has previously accessed the 152 attribute, there is not way in which the system could have prevented the 153 thiry party from storing the data. As such, only access to updated data 154 in the future can be revoked. This behaviour is \_exactly the same\_ as 155 with other IdPs. 156 157 .. _OpenID-Connect: 158 159 OpenID Connect 160 ~~~~~~~~~~~~~~ 161 162 There is an 163 `https://openid.net/specs/openid-connect-core-1_0.html <OpenID Connect>`__ 164 API for use with re:claimID. However, its use is quite complicated to 165 setup. 166 167 :: 168 169 https://api.reclaim/openid/authorize 170 http://localhost:7776/openid/token 171 http://localhost:7776/openid/userinfo 172 http://localhost:7776/openid/login 173 174 The token endpoint is protected using HTTP basic authentication. You can 175 authenticate using any username and the password configured under: 176 177 :: 178 179 $ gnunet-config -s reclaim-rest-plugin -o OIDC_CLIENT_SECRET 180 181 The authorize endpoint is protected using a Cookie which can be obtained 182 through a request against the login endpoint. This functionality is 183 meant to be used in the context of the OpenID Connect authorization flow 184 to collect user consent interactively. Without a Cookie, the authorize 185 endpoint redirects to a URI configured under: 186 187 :: 188 189 $ gnunet-config -s reclaim-rest-plugin -o ADDRESS 190 191 The token endpoint is protected using OAuth2 and expects the grant which 192 is retrieved from the authorization endpoint according to the standard. 193 194 The userinfo endpoint is protected using OAuth2 and expects a bearer 195 access token which is retrieved from a token request. 196 197 In order to make use of OpenID Connect flows as a user, you need to 198 install the browser plugin: 199 200 - `Firefox Add-on <https://addons.mozilla.org/addon/reclaimid/>`__ 201 202 - `Chrome Web 203 Store <https://chrome.google.com/webstore/detail/reclaimid/jiogompmdejcnacmlnjhnaicgkefcfll>`__ 204 205 In order to create and register an OpenID Connect client as a relying 206 party, you need to execute the following steps: 207 208 :: 209 210 $ gnunet-identity -C <client_name> 211 $ gnunet-namestore -z <client_name> -a -n "@" -t RECLAIM_OIDC_REDIRECT -V <redirect_uri> -e 1d -p 212 $ gnunet-namestore -z <client_name> -a -n "@" -t RECLAIM_OIDC_CLIENT -V "My OIDC Client" -e 1d -p 213 214 The \"client_id\" for use in OpenID Connect is the public key of the 215 client as displayed using: 216 217 .. code-block:: shell 218 219 $ gnunet-identity -d grep "relyingparty" | awk '{print $3}' 220 221 The RECLAIM_OIDC_REDIRECT record contains your website redirect URI. You 222 may use any globally unique DNS or GNS URI. The RECLAIM_OIDC_CLIENT 223 record represents the client description which whill be displayed to 224 users in an authorization request. 225 226 Any website or relying party must use the authorization endpoint 227 https://api.reclaim/openid/authorize in its authorization redirects, 228 e.g. 229 230 .. code-block:: html 231 232 <a href="https://api.reclaim/openid/authorize?client_id=<PKEY>\ 233 &scope=openid email\ 234 &redirect_uri=<redirect_uri>\ 235 &nonce=<random>">Login</a> 236 237 This will direct the user's browser onto his local reclaimID instance. 238 After giving consent, you will be provided with the OpenID Connect 239 authorization code according to the specifications at your provided 240 redirect URI. 241 242 The ID Tokens issues by the token endpoints are signed using HS512 with 243 the shared secret configured under: 244 245 :: 246 247 $ gnunet-config -s reclaim-rest-plugin -o JWT_SECRET 248 249 The authorization code flow optionally supports `Proof Key for Code 250 Exchange <https://tools.ietf.org/html/rfc7636>`__. If PKCE is used, the 251 client does not need to authenticate against the token endpoint. 252 253 .. _Providing-Third-Party-Attestation: 254 255 Providing Third Party Attestation 256 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 257 258 If you are running an identity provider (IdP) service you may be able to 259 support providing credentials for re:claimID users. IdPs can issue JWT 260 credentials as long as they support OpenID Connect and `OpenID Connect 261 Discovery <https://openid.net/specs/openid-connect-discovery-1_0.html>`__. 262 263 In order to allow users to import attributes through the re:claimID user 264 interface, you need to register the following public OAuth2/OIDC client: 265 266 - client_id: reclaimid 267 268 - client_secret: none 269 270 - redirect_uri: https://ui.reclaim (The URI of the re:claimID 271 webextension) 272 273 - grant_type: authorization_code with PKCE 274 (`RFC7636 <https://tools.ietf.org/html/rfc7636>`__) 275 276 - scopes: all you want to offer. 277 278 - id_token: JWT 279 280 When your users add an attribute with name \"email\" which supports 281 webfinger discovery they will be prompted with the option to retrieve 282 the OpenID Connect ID Token through the user interface. 283 284 285 286