diff options
author | jospaeth <spaethj@in.tum.de> | 2020-08-28 12:27:32 +0200 |
---|---|---|
committer | jospaeth <spaethj@in.tum.de> | 2020-08-28 12:27:32 +0200 |
commit | 5f7d255ae5221c447367c4ac7a157ddcd27bcd57 (patch) | |
tree | 22fae70a54ad97c15a59f62e4c8bb9498a0d2e53 /doc/handbook/chapters/user.texi | |
parent | 62d6be2695969cd430351b503b033057a1b50f47 (diff) | |
parent | bbf9540c93da3c6b950920ee7eaae479c95403c5 (diff) | |
download | gnunet-5f7d255ae5221c447367c4ac7a157ddcd27bcd57.tar.gz gnunet-5f7d255ae5221c447367c4ac7a157ddcd27bcd57.zip |
Merge branch 'master' into spaeth/escrow_plugins
Diffstat (limited to 'doc/handbook/chapters/user.texi')
-rw-r--r-- | doc/handbook/chapters/user.texi | 95 |
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 | ||
1991 | The reclaimID Identity Provider (IdP) is a decentralized IdP service. | 1991 | The re:claimID Identity Provider (IdP) is a decentralized IdP service. |
1992 | It allows its users to manage and authorize third parties to access | 1992 | It allows its users to manage and authorize third parties to access |
1993 | their identity attributes such as email or shipping addresses. | 1993 | their identity attributes such as email or shipping addresses. |
1994 | 1994 | ||
1995 | It basically mimics the concepts of centralized IdPs, such as those | 1995 | It basically mimics the concepts of centralized IdPs, such as those |
1996 | offered by Google or Facebook. | 1996 | offered by Google or Facebook. |
1997 | Like other IdPs, reclaimID features an (optional) OpenID-Connect | 1997 | Like other IdPs, reclaimID features an (optional) OpenID Connect |
1998 | 1.0-compliant protocol layer that can be used for websites to | 1998 | 1.0-compliant protocol layer that can be used for websites to |
1999 | integrate reclaimID as an Identity Provider with little effort. | 1999 | integrate 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 | |||
2038 | If you want to allow a third party such as a website or friend to access to your attributes (or a subset thereof) execute: | 2038 | If 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 | ||
2044 | Where "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 | |||
2046 | The command will return a "ticket" string. | 2044 | The command will return a "ticket" string. |
2047 | You must give this "ticket" to the requesting third party. | 2045 | You 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 | |||
2049 | The third party may retrieve the key in string format for use in the above | ||
2050 | call using "gnunet-identity": | ||
2051 | |||
2052 | @example | ||
2053 | $ RP_KEY=$(gnunet-identity -d grep "relyingparty" | awk '@{print $3@}') | ||
2054 | @end example | ||
2048 | 2055 | ||
2049 | The third party can then retrieve your shared identity attributes using: | 2056 | The 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 | ||
2055 | Where "friend" is the name for "user" that the requesting party is using. | 2062 | Where "relyingparty" is the name for the identity behind $RP_KEY that the |
2063 | requesting party is using. | ||
2056 | This will retrieve and list the shared identity attributes. | 2064 | This will retrieve and list the shared identity attributes. |
2057 | The above command will also work if the user is currently offline since the attributes are retrieved from GNS. | 2065 | The above command will also work if the user is currently offline since the attributes are retrieved from GNS. |
2058 | Further, 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. | 2066 | Further, $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 | ||
2060 | To list all given authorizations (tickets) you can execute: | 2068 | To 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 | ||
2069 | If you want to revoke the access of a third party to your attributes you can execute: | 2076 | If 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 | ||
2075 | This will prevent the third party from accessing the attribute in the future. | 2082 | This 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 | ||
2083 | There is an OpenID Connect API for use with reclaimID. | 2090 | There is an @uref{OpenID Connect, https://openid.net/specs/openid-connect-core-1_0.html} API for use with re:claimID. |
2084 | However, its use is quite complicated to setup. | 2091 | However, its use is quite complicated to setup. |
2085 | As a proof-of-concept, you can look at https://gitlab.com/reclaimid. | ||
2086 | |||
2087 | In the PoC and by convention for reclaimID, the OpenID Connect Endpoints are | ||
2088 | found at: | ||
2089 | 2092 | ||
2090 | @example | 2093 | @example |
2091 | http://api.reclaim/openid/authorize | 2094 | https://api.reclaim/openid/authorize |
2092 | http://api.reclaim/openid/token | 2095 | http://localhost:7776/openid/token |
2093 | http://api.reclaim/openid/userinfo | 2096 | http://localhost:7776/openid/userinfo |
2094 | http://api.reclaim/openid/login | 2097 | http://localhost:7776/openid/login |
2095 | @end example | 2098 | @end example |
2096 | 2099 | ||
2097 | The token endpoint is protected using HTTP basic authentication. | 2100 | The token endpoint is protected using HTTP basic authentication. |
2098 | You can authenticate using any username and the password configured under: | 2101 | You 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 | ||
2104 | The authorize endpoint is protected using a Cookie which can be obtained through | 2107 | The authorize endpoint is protected using a Cookie which can be obtained through |
2105 | a request against the login endpoint. | 2108 | a request against the login endpoint. |
2106 | This flow is meant to be used in the context of the OpenID Connect authorization | 2109 | This functionality is meant to be used in the context of the OpenID Connect authorization |
2107 | flow to collect user consent interactively. | 2110 | flow to collect user consent interactively. |
2108 | Without a Cookie, the authorize endpoint redirects to a URI configured under: | 2111 | Without 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 | ||
2114 | Our PoC includes a user interface (https://gitlab.com/reclaimid) which | ||
2115 | integrates this process is an OpenID Connect compatible fashion. | ||
2116 | |||
2117 | The token endpoint is protected using OAuth2 and expects the grant | 2117 | The token endpoint is protected using OAuth2 and expects the grant |
2118 | which is retrieved from the authorization endpoint according to the standard. | 2118 | which is retrieved from the authorization endpoint according to the standard. |
2119 | 2119 | ||
2120 | The userinfo endpoint is protected using OAuth2 and expects a bearer access | 2120 | The userinfo endpoint is protected using OAuth2 and expects a bearer access |
2121 | token which is retrieved from a token request. | 2121 | token which is retrieved from a token request. |
2122 | 2122 | ||
2123 | In order to create and register a client you need to execute the following | 2123 | In order to make use of OpenID Connect flows as a user, you need to install |
2124 | steps: | 2124 | the 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 | |||
2131 | In order to create and register an OpenID Connect client as a relying party, | ||
2132 | you 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 | ||
2132 | The client_id will be the public key of the client. | 2140 | The "client_id" for use in OpenID Connect is the public key of the client as |
2133 | As a redirect URI, you may use any globally unique DNS or GNS URI. | 2141 | displayed using: |
2134 | The 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 | |||
2146 | The RECLAIM_OIDC_REDIRECT record contains your website redirect URI. | ||
2147 | You may use any globally unique DNS or GNS URI. | ||
2148 | The RECLAIM_OIDC_CLIENT record represents the client description which whill | ||
2149 | be displayed to users in an authorization request. | ||
2135 | 2150 | ||
2136 | Any website or relying party must use the endpoint | 2151 | Any website or relying party must use the authorization endpoint |
2137 | https://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. | |||
2146 | This will direct the user's browser onto his local reclaimID instance. | 2161 | This will direct the user's browser onto his local reclaimID instance. |
2147 | After giving consent, you will be provided with the OpenID Connect authorization | 2162 | After giving consent, you will be provided with the OpenID Connect authorization |
2148 | code according to the specifications at your provided redirect URI. | 2163 | code according to the specifications at your provided redirect URI. |
2149 | The example code for the PoC website can be found at https://gitlab.com/reclaimid/demo. | 2164 | |
2165 | The ID Tokens issues by the token endpoints are signed using HS512 with the | ||
2166 | shared secret configured under: | ||
2167 | |||
2168 | @example | ||
2169 | $ gnunet-config -s reclaim-rest-plugin -o JWT_SECRET | ||
2170 | @end example | ||
2171 | |||
2172 | The authorization code flow optionally supports @uref{https://tools.ietf.org/html/rfc7636, Proof Key for Code Exchange}. | ||
2173 | If PKCE is used, the client does not need to authenticate against the token | ||
2174 | endpoint. | ||
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 |