Skip to content
Snippets Groups Projects
Commit 61c6fe90 authored by Rohith's avatar Rohith
Browse files

- updating the README

parent aa2903b4
No related branches found
No related tags found
No related merge requests found
Show whitespace changes
Inline Side-by-side
Showing
with 16 additions and 16 deletions
README.md
+ 16
− 16
View file @ 61c6fe90
...@@ -130,7 +130,7 @@ b) Add a Valid Redirect URIs of *http://127.0.0.1:3000/oauth/callback*. ...@@ -130,7 +130,7 @@ b) Add a Valid Redirect URIs of *http://127.0.0.1:3000/oauth/callback*.
c) Grab the client id and client secret. c) Grab the client id and client secret.
d) Create the various roles under the client or existing clients for authorization purposes. d) Create the various roles under the client or existing clients for authorization purposes.
**The default config** ##### **- The default config**
```YAML ```YAML
discovery_url: https://keycloak.example.com/auth/realms/<REALM_NAME> discovery_url: https://keycloak.example.com/auth/realms/<REALM_NAME>
...@@ -170,8 +170,8 @@ bin/keycloak-proxy \ ...@@ -170,8 +170,8 @@ bin/keycloak-proxy \
--resource="uri=/backend|roles=test1" --resource="uri=/backend|roles=test1"
``` ```
#### **Google OpenID** #### **- Google OAuth**
---
Although the role extensions do require a Keycloak IDP or at the very least a IDP that produces a token which contains roles, there's nothing stopping you from using it against any OpenID providers, such as Google. Go to the Google Developers Console and create a new application *(via "Enable and Manage APIs -> Credentials)*. Once you've created the application, take the client id, secret and make sure you've added the callback url to the application scope *(using the default this would be http://127.0.0.1:3000/oauth/callback)* Although the role extensions do require a Keycloak IDP or at the very least a IDP that produces a token which contains roles, there's nothing stopping you from using it against any OpenID providers, such as Google. Go to the Google Developers Console and create a new application *(via "Enable and Manage APIs -> Credentials)*. Once you've created the application, take the client id, secret and make sure you've added the callback url to the application scope *(using the default this would be http://127.0.0.1:3000/oauth/callback)*
``` shell ``` shell
...@@ -191,8 +191,8 @@ DEBU[0002] resource access permitted: / access=permitted bearer ...@@ -191,8 +191,8 @@ DEBU[0002] resource access permitted: / access=permitted bearer
DEBU[0002] resource access permitted: /favicon.ico access=permitted bearer=false expires=57m51.144004098s resource=/ username=gambol99@gmail.com DEBU[0002] resource access permitted: /favicon.ico access=permitted bearer=false expires=57m51.144004098s resource=/ username=gambol99@gmail.com
2016-02-06 13:59:01.856716 I | http: proxy error: dial tcp 127.0.0.1:8081: getsockopt: connection refused 2016-02-06 13:59:01.856716 I | http: proxy error: dial tcp 127.0.0.1:8081: getsockopt: connection refused
``` ```
---
#### **Upstream Headers** #### **- Upstream Headers**
On protected resources the upstream endpoint will receive a number of headers added by the proxy; On protected resources the upstream endpoint will receive a number of headers added by the proxy;
...@@ -211,17 +211,17 @@ cx.Request.Header.Add("X-Forwarded-For", <CLIENT_IP>) ...@@ -211,17 +211,17 @@ cx.Request.Header.Add("X-Forwarded-For", <CLIENT_IP>)
cx.Request.Header.Add("X-Forwarded-Proto", <CLIENT_PROTO>) cx.Request.Header.Add("X-Forwarded-Proto", <CLIENT_PROTO>)
``` ```
#### **Encryption Key** #### **- Encryption Key**
In order to remain stateless and not have to rely on a central cache to persist the 'refresh_tokens', the refresh token is encrypted and added as a cookie using *crypto/aes*. In order to remain stateless and not have to rely on a central cache to persist the 'refresh_tokens', the refresh token is encrypted and added as a cookie using *crypto/aes*.
Naturally the key must be the same if your running behind a load balancer etc. The key length should either 16 or 32 bytes depending or whether you want AES-128 or AES-256. Naturally the key must be the same if your running behind a load balancer etc. The key length should either 16 or 32 bytes depending or whether you want AES-128 or AES-256.
#### **Claim Matching** #### **- Claim Matching**
The proxy supports adding a variable list of claim matches against the presented tokens for additional access control. So for example you can match the 'iss' or 'aud' to the token or custom attributes; The proxy supports adding a variable list of claim matches against the presented tokens for additional access control. So for example you can match the 'iss' or 'aud' to the token or custom attributes;
note each of the matches are regex's. Examples, --claim 'aud=sso.*' --claim iss=https://.*' note each of the matches are regex's. Examples, --claim 'aud=sso.*' --claim iss=https://.*'
#### **Custom Pages** #### **- Custom Pages**
By default the proxy will immediately redirect you for authentication and hand back 403 for access denied. Most users will probably want to present the user with a more friendly By default the proxy will immediately redirect you for authentication and hand back 403 for access denied. Most users will probably want to present the user with a more friendly
sign-in and access denied page. You can pass the command line options (or via config file) paths to the files i.e. --signin-pag=PATH. The sign-in page will have a 'redirect' sign-in and access denied page. You can pass the command line options (or via config file) paths to the files i.e. --signin-pag=PATH. The sign-in page will have a 'redirect'
...@@ -236,7 +236,7 @@ passed into the scope hold the oauth redirection url. If you wish pass additiona ...@@ -236,7 +236,7 @@ passed into the scope hold the oauth redirection url. If you wish pass additiona
</html> </html>
``` ```
#### **White-listed URL's** #### **- White-listed URL's**
Depending on how the application urls are laid out, you might want protect the root / url but have exceptions on a list of paths, i.e. /health etc. Although you should probably Depending on how the application urls are laid out, you might want protect the root / url but have exceptions on a list of paths, i.e. /health etc. Although you should probably
fix this by fixing up the paths, you can add excepts to the protected resources. (Note: it's an array, so the order is important) fix this by fixing up the paths, you can add excepts to the protected resources. (Note: it's an array, so the order is important)
...@@ -261,20 +261,20 @@ Or on the command line ...@@ -261,20 +261,20 @@ Or on the command line
--resource "uri=/admin|roles=admin,superuser|methods=POST,DELETE --resource "uri=/admin|roles=admin,superuser|methods=POST,DELETE
``` ```
#### **Mutual TLS** #### **- Mutual TLS**
The proxy support enforcing mutual TLS for the clients by simply adding the --tls-ca-certificate command line option or config file option. All clients connecting must present a ceritificate The proxy support enforcing mutual TLS for the clients by simply adding the --tls-ca-certificate command line option or config file option. All clients connecting must present a ceritificate
which was signed by the CA being used. which was signed by the CA being used.
#### **Tokens && Stores** #### **- Tokens && Stores**
Refresh tokens are either be stored as an encrypted cookie or placed (encrypted) in a shared / local store. At present, redis and boltdb are the only two methods supported. To enable a local boltdb store. --store-url boltdb:///PATH or relative path boltdb://PATH. For redis the option is redis://HOST:PORT. In both cases the refresh token is encrypted before placing into the store Refresh tokens are either be stored as an encrypted cookie or placed (encrypted) in a shared / local store. At present, redis and boltdb are the only two methods supported. To enable a local boltdb store. --store-url boltdb:///PATH or relative path boltdb://PATH. For redis the option is redis://HOST:PORT. In both cases the refresh token is encrypted before placing into the store
#### **Refresh & Offline Tokens** #### **- Refresh & Offline Tokens**
Assuming access response responds with a refresh token and the --enable-refresh-token is true, the proxy will automatically refresh the access token for you. The tokens themselves are kept either as an encrypted (--encryption-key=KEY) cookie (cookie name: kc-state). Alternatively you can place the refresh token (still requires encryption key) in a local boltdb file or shared redis. Naturally the encryption key has to be the same on all instances and boltdb is for single instance only developments. Assuming access response responds with a refresh token and the --enable-refresh-token is true, the proxy will automatically refresh the access token for you. The tokens themselves are kept either as an encrypted (--encryption-key=KEY) cookie (cookie name: kc-state). Alternatively you can place the refresh token (still requires encryption key) in a local boltdb file or shared redis. Naturally the encryption key has to be the same on all instances and boltdb is for single instance only developments.
#### **Cross Origin Resource Sharing (CORS)** #### **- Cross Origin Resource Sharing (CORS)**
You are permitted to add CORS following headers into the /oauth uri namespace You are permitted to add CORS following headers into the /oauth uri namespace
...@@ -305,12 +305,12 @@ or via the command line arguments ...@@ -305,12 +305,12 @@ or via the command line arguments
--cors-exposes-headers [--cors-exposes-headers option] set the expose cors headers access control (Access-Control-Expose-Headers) --cors-exposes-headers [--cors-exposes-headers option] set the expose cors headers access control (Access-Control-Expose-Headers)
``` ```
#### **Endpoints** #### **- Endpoints**
* **/oauth/authorize** is authentication endpoint which will generate the openid redirect to the provider * **/oauth/authorize** is authentication endpoint which will generate the openid redirect to the provider
* **/oauth/callback** is provider openid callback endpoint * **/oauth/callback** is provider openid callback endpoint
* **/oauth/expired** is a helper endpoint to check if a access token has expired, 200 for ok and, 401 for no token and 401 for expired * **/oauth/expired** is a helper endpoint to check if a access token has expired, 200 for ok and, 401 for no token and 401 for expired
* **/oauth/token** is a helper endpoint which will display the current access token for you
* **/oauth/health** is the health checking endpoint for the proxy * **/oauth/health** is the health checking endpoint for the proxy
* **/oauth/logout** provides a convenient endpoint to log the user out, it will always attempt to perform a back channel logout of offline tokens
* **/oauth/login** provides a relay endpoint to login via grant_type=password i.e. POST /oauth/login?username=USERNAME&password=PASSWORD * **/oauth/login** provides a relay endpoint to login via grant_type=password i.e. POST /oauth/login?username=USERNAME&password=PASSWORD
* **/oauth/logout** provides a convenient endpoint to log the user out, it will always attempt to perform a back channel logout of offline tokens
* **/oauth/token** is a helper endpoint which will display the current access token for you
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment