aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorMartin Schanzenbach <mschanzenbach@posteo.de>2020-08-18 13:35:24 +0200
committerMartin Schanzenbach <mschanzenbach@posteo.de>2020-08-18 13:35:24 +0200
commit2cd052cb8e4d2f2c3e5e9f1ed2a9b58f6af069bb (patch)
tree8c36af40d3cbb0b0392cc98c6f0e7690868590e9 /doc
parent2bce42e5b3630f3835f401e5eeed23a56b7bd875 (diff)
downloadgnunet-2cd052cb8e4d2f2c3e5e9f1ed2a9b58f6af069bb.tar.gz
gnunet-2cd052cb8e4d2f2c3e5e9f1ed2a9b58f6af069bb.zip
Update reclaimID handbook entry
Diffstat (limited to 'doc')
-rw-r--r--doc/handbook/chapters/user.texi95
1 files changed, 60 insertions, 35 deletions
diff --git a/doc/handbook/chapters/user.texi b/doc/handbook/chapters/user.texi
index 523f286d0..adc287e04 100644
--- a/doc/handbook/chapters/user.texi
+++ b/doc/handbook/chapters/user.texi
@@ -1988,13 +1988,13 @@ as a guide.
1988@node reclaimID Identity Provider 1988@node reclaimID Identity Provider
1989@section reclaimID Identity Provider 1989@section reclaimID Identity Provider
1990 1990
1991The reclaimID Identity Provider (IdP) is a decentralized IdP service. 1991The re:claimID Identity Provider (IdP) is a decentralized IdP service.
1992It allows its users to manage and authorize third parties to access 1992It allows its users to manage and authorize third parties to access
1993their identity attributes such as email or shipping addresses. 1993their identity attributes such as email or shipping addresses.
1994 1994
1995It basically mimics the concepts of centralized IdPs, such as those 1995It basically mimics the concepts of centralized IdPs, such as those
1996offered by Google or Facebook. 1996offered by Google or Facebook.
1997Like other IdPs, reclaimID features an (optional) OpenID-Connect 1997Like other IdPs, reclaimID features an (optional) OpenID Connect
19981.0-compliant protocol layer that can be used for websites to 19981.0-compliant protocol layer that can be used for websites to
1999integrate reclaimID as an Identity Provider with little effort. 1999integrate reclaimID as an Identity Provider with little effort.
2000 2000
@@ -2038,38 +2038,45 @@ In the future there might be more value types such as X.509 certificate credenti
2038If you want to allow a third party such as a website or friend to access to your attributes (or a subset thereof) execute: 2038If you want to allow a third party such as a website or friend to access to your attributes (or a subset thereof) execute:
2039 2039
2040@example 2040@example
2041$ gnunet-reclaim -e "user" -r "PKEY" -i "attribute1,attribute2,..." 2041$ TICKET=$(gnunet-reclaim -e "user" -r "$RP_KEY" -i "attribute1,attribute2,...")
2042@end example 2042@end example
2043 2043
2044Where "PKEY" is the public key of the third party and "attribute1,attribute2,..." is a comma-separated list of attribute names, such as "email,name,...", that you want to share.
2045
2046The command will return a "ticket" string. 2044The command will return a "ticket" string.
2047You must give this "ticket" to the requesting third party. 2045You must give $TICKET to the requesting third party.
2046
2047$RP_KEY is the public key of the third party and "attribute1,attribute2,..." is a comma-separated list of attribute names, such as "email,name,...", that you want to share.
2048
2049The third party may retrieve the key in string format for use in the above
2050call using "gnunet-identity":
2051
2052@example
2053$ RP_KEY=$(gnunet-identity -d grep "relyingparty" | awk '@{print $3@}')
2054@end example
2048 2055
2049The third party can then retrieve your shared identity attributes using: 2056The third party can then retrieve your shared identity attributes using:
2050 2057
2051@example 2058@example
2052$ gnunet-reclaim -e "friend" -C "ticket" 2059$ gnunet-reclaim -e "relyingparty" -C "ticket"
2053@end example 2060@end example
2054 2061
2055Where "friend" is the name for "user" that the requesting party is using. 2062Where "relyingparty" is the name for the identity behind $RP_KEY that the
2063requesting party is using.
2056This will retrieve and list the shared identity attributes. 2064This will retrieve and list the shared identity attributes.
2057The above command will also work if the user is currently offline since the attributes are retrieved from GNS. 2065The above command will also work if the user is currently offline since the attributes are retrieved from GNS.
2058Further, the "ticket" can be re-used later to retrieve up-to-date attributes in case "friend" has changed the value(s). For instance, because his email address changed. 2066Further, $TICKET can be re-used later to retrieve up-to-date attributes in case "friend" has changed the value(s). For instance, because his email address changed.
2059 2067
2060To list all given authorizations (tickets) you can execute: 2068To list all given authorizations (tickets) you can execute:
2061@example 2069@example
2062$ gnunet-reclaim -e "friend" -T (TODO there is only a C and REST API for this at this time) 2070$ gnunet-reclaim -e "user" -T
2063@end example 2071@end example
2064 2072
2065
2066@node Revoking Authorizations of Third Parties 2073@node Revoking Authorizations of Third Parties
2067@subsection Revoking Authorizations of Third Parties 2074@subsection Revoking Authorizations of Third Parties
2068 2075
2069If you want to revoke the access of a third party to your attributes you can execute: 2076If you want to revoke the access of a third party to your attributes you can execute:
2070 2077
2071@example 2078@example
2072$ gnunet-reclaim -e "user" -R "ticket" 2079$ gnunet-reclaim -e "user" -R $TICKET
2073@end example 2080@end example
2074 2081
2075This will prevent the third party from accessing the attribute in the future. 2082This will prevent the third party from accessing the attribute in the future.
@@ -2080,30 +2087,26 @@ This behaviour is _exactly the same_ as with other IdPs.
2080@node OpenID Connect 2087@node OpenID Connect
2081@subsection OpenID Connect 2088@subsection OpenID Connect
2082 2089
2083There is an OpenID Connect API for use with reclaimID. 2090There is an @uref{OpenID Connect, https://openid.net/specs/openid-connect-core-1_0.html} API for use with re:claimID.
2084However, its use is quite complicated to setup. 2091However, its use is quite complicated to setup.
2085As a proof-of-concept, you can look at https://gitlab.com/reclaimid.
2086
2087In the PoC and by convention for reclaimID, the OpenID Connect Endpoints are
2088found at:
2089 2092
2090@example 2093@example
2091http://api.reclaim/openid/authorize 2094https://api.reclaim/openid/authorize
2092http://api.reclaim/openid/token 2095http://localhost:7776/openid/token
2093http://api.reclaim/openid/userinfo 2096http://localhost:7776/openid/userinfo
2094http://api.reclaim/openid/login 2097http://localhost:7776/openid/login
2095@end example 2098@end example
2096 2099
2097The token endpoint is protected using HTTP basic authentication. 2100The token endpoint is protected using HTTP basic authentication.
2098You can authenticate using any username and the password configured under: 2101You can authenticate using any username and the password configured under:
2099 2102
2100@example 2103@example
2101$ gnunet-config -s reclaim-rest-plugin -o PSW 2104$ gnunet-config -s reclaim-rest-plugin -o OIDC_CLIENT_SECRET
2102@end example 2105@end example
2103 2106
2104The authorize endpoint is protected using a Cookie which can be obtained through 2107The authorize endpoint is protected using a Cookie which can be obtained through
2105a request against the login endpoint. 2108a request against the login endpoint.
2106This flow is meant to be used in the context of the OpenID Connect authorization 2109This functionality is meant to be used in the context of the OpenID Connect authorization
2107flow to collect user consent interactively. 2110flow to collect user consent interactively.
2108Without a Cookie, the authorize endpoint redirects to a URI configured under: 2111Without a Cookie, the authorize endpoint redirects to a URI configured under:
2109 2112
@@ -2111,17 +2114,22 @@ Without a Cookie, the authorize endpoint redirects to a URI configured under:
2111$ gnunet-config -s reclaim-rest-plugin -o ADDRESS 2114$ gnunet-config -s reclaim-rest-plugin -o ADDRESS
2112@end example 2115@end example
2113 2116
2114Our PoC includes a user interface (https://gitlab.com/reclaimid) which
2115integrates this process is an OpenID Connect compatible fashion.
2116
2117The token endpoint is protected using OAuth2 and expects the grant 2117The token endpoint is protected using OAuth2 and expects the grant
2118which is retrieved from the authorization endpoint according to the standard. 2118which is retrieved from the authorization endpoint according to the standard.
2119 2119
2120The userinfo endpoint is protected using OAuth2 and expects a bearer access 2120The userinfo endpoint is protected using OAuth2 and expects a bearer access
2121token which is retrieved from a token request. 2121token which is retrieved from a token request.
2122 2122
2123In order to create and register a client you need to execute the following 2123In order to make use of OpenID Connect flows as a user, you need to install
2124steps: 2124the browser plugin:
2125
2126@itemize @bullet
2127@item @uref{https://addons.mozilla.org/addon/reclaimid/, Firefox Add-on}
2128@item @uref{https://chrome.google.com/webstore/detail/reclaimid/jiogompmdejcnacmlnjhnaicgkefcfll, Chrome Web Store}
2129@end itemize
2130
2131In order to create and register an OpenID Connect client as a relying party,
2132you need to execute the following steps:
2125 2133
2126@example 2134@example
2127$ gnunet-identity -C <client_name> 2135$ gnunet-identity -C <client_name>
@@ -2129,16 +2137,23 @@ $ gnunet-namestore -z <client_name> -a -n "@@" -t RECLAIM_OIDC_REDIRECT -V <redi
2129$ gnunet-namestore -z <client_name> -a -n "@@" -t RECLAIM_OIDC_CLIENT -V "My OIDC Client" -e 1d -p 2137$ gnunet-namestore -z <client_name> -a -n "@@" -t RECLAIM_OIDC_CLIENT -V "My OIDC Client" -e 1d -p
2130@end example 2138@end example
2131 2139
2132The client_id will be the public key of the client. 2140The "client_id" for use in OpenID Connect is the public key of the client as
2133As a redirect URI, you may use any globally unique DNS or GNS URI. 2141displayed using:
2134The client description will be displayed to the user on authorization. 2142@example
2143$ gnunet-identity -d grep "relyingparty" | awk '@{print $3@}'
2144@end example
2145
2146The RECLAIM_OIDC_REDIRECT record contains your website redirect URI.
2147You may use any globally unique DNS or GNS URI.
2148The RECLAIM_OIDC_CLIENT record represents the client description which whill
2149be displayed to users in an authorization request.
2135 2150
2136Any website or relying party must use the endpoint 2151Any website or relying party must use the authorization endpoint
2137https://api.reclaim/openid/authorize in its authorization redirects, e.g. 2152@uref{https://api.reclaim/openid/authorize} in its authorization redirects, e.g.
2138 2153
2139@example 2154@example
2140<a href="https://api.reclaim/openid/authorize?client_id=<PKEY>\ 2155<a href="https://api.reclaim/openid/authorize?client_id=<PKEY>\
2141 &scope=email\ 2156 &scope=openid email\
2142 &redirect_uri=<redirect_uri>\ 2157 &redirect_uri=<redirect_uri>\
2143 &nonce=<random>">Login</a> 2158 &nonce=<random>">Login</a>
2144@end example 2159@end example
@@ -2146,7 +2161,17 @@ https://api.reclaim/openid/authorize in its authorization redirects, e.g.
2146This will direct the user's browser onto his local reclaimID instance. 2161This will direct the user's browser onto his local reclaimID instance.
2147After giving consent, you will be provided with the OpenID Connect authorization 2162After giving consent, you will be provided with the OpenID Connect authorization
2148code according to the specifications at your provided redirect URI. 2163code according to the specifications at your provided redirect URI.
2149The example code for the PoC website can be found at https://gitlab.com/reclaimid/demo. 2164
2165The ID Tokens issues by the token endpoints are signed using HS512 with the
2166shared secret configured under:
2167
2168@example
2169$ gnunet-config -s reclaim-rest-plugin -o JWT_SECRET
2170@end example
2171
2172The authorization code flow optionally supports @uref{https://tools.ietf.org/html/rfc7636, Proof Key for Code Exchange}.
2173If PKCE is used, the client does not need to authenticate against the token
2174endpoint.
2150 2175
2151@node Using the Virtual Public Network 2176@node Using the Virtual Public Network
2152@section Using the Virtual Public Network 2177@section Using the Virtual Public Network