gnunet-handbook

The GNUnet Handbook
Log | Files | Refs

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