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