github.com/nginxinc/kubernetes-ingress@v1.12.5/examples-of-custom-resources/oidc/README.md (about)

     1  # OIDC
     2  
     3  In this example, we deploy a web application, configure load balancing for it via a VirtualServer, and protect the application using an OpenID Connect policy and [Keycloak](https://www.keycloak.org/).
     4  
     5  ## Prerequisites
     6  
     7  1. Follow the [installation](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) instructions to deploy the Ingress Controller. This example requires that the HTTPS port of the Ingress Controller is `443`.
     8  1. Save the public IP address of the Ingress Controller into `/etc/hosts` of your machine:
     9      ```
    10      ...
    11  
    12      XXX.YYY.ZZZ.III webapp.example.com
    13      XXX.YYY.ZZZ.III keycloak.example.com
    14      ```
    15      Here `webapp.example.com` is the domain for the web application and `keycloak.example.com` is the domain for Keycloak.
    16  
    17  ## Step 1 - Deploy a TLS Secret
    18  
    19  Create a secret with the TLS certificate and key that will be used for TLS termination of the web application and Keycloak:
    20  ```
    21  $ kubectl apply -f tls-secret.yaml
    22  ```
    23  
    24  ## Step 2 - Deploy a Web Application
    25  
    26  Create the application deployment and service:
    27  ```
    28  $ kubectl apply -f webapp.yaml
    29  ```
    30  
    31  ## Step 3 - Deploy Keycloak
    32  
    33  1. Create the Keycloak deployment and service:
    34      ```
    35      $ kubectl apply -f keycloak.yaml
    36      ```
    37  1. Create a VirtualServer resource for Keycloak:
    38      ```
    39      $ kubectl apply -f virtual-server-idp.yaml
    40      ```
    41  
    42  ## Step 4 - Configure Keycloak
    43  
    44  To set up Keycloak:
    45  1. Follow the steps in the "Configuring Keycloak" section of the documentation [here](https://docs.nginx.com/nginx/deployment-guides/single-sign-on/keycloak/#configuring-keycloak):
    46      1. To connect to Keycloak, use `https://keycloak.example.com`.
    47      1. Make sure to save the client secret for NGINX-Plus client to the `SECRET` shell variable:
    48          ```
    49          SECRET=value
    50          ```
    51  1. Alternatively, execute the commands [here](./keycloak_setup.md).
    52  
    53  
    54  ## Step 5 - Deploy the Client Secret
    55  
    56  1. Encode the secret, obtained in the previous step:
    57      ```
    58      $ echo -n $SECRET | base64
    59      ```
    60  
    61  1. Edit `client-secret.yaml`, replacing `<insert-secret-here> ` with the encoded secret.
    62  
    63  1. Create a secret with the name `oidc-secret` that will be used by the OIDC policy:
    64      ```
    65      $ kubectl apply -f client-secret.yaml
    66      ```
    67  
    68  ## Step 6 - Deploy the OIDC Policy
    69  
    70  Create a policy with the name `oidc-policy` that references the secret from the previous step:
    71  ```
    72  $ kubectl apply -f oidc.yaml
    73  ```
    74  
    75  ## Step 7 - Configure NGINX Plus Zone Synchronization and Resolver
    76  
    77  In this step we configure:
    78  * [Zone Synchronization](https://docs.nginx.com/nginx/admin-guide/high-availability/zone_sync/). For the OIDC feature to work when you have two or more replicas of the Ingress Controller, it is necessary to enable zone synchronization among the replicas.
    79  * The resolver, so that an NGINX Plus can discover the other Ingress Controller replicas and resolve the Keycloak endpoint.
    80  
    81  Steps:
    82  1. Deploy a headless service for the Ingress Controller.
    83      ```
    84      $ kubectl apply -f nginx-ingress-headless.yaml
    85      ```
    86  1. Get the cluster IP of the KubeDNS service:
    87      ```
    88      $ kubectl -n kube-system get svc kube-dns
    89      NAME       TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)         AGE
    90      kube-dns   ClusterIP   10.4.0.10    <none>        53/UDP,53/TCP   9d
    91      ```
    92  1. Edit the ConfigMap `nginx-config.yaml`, replacing the `<kube-dns-ip>` with the IP obtained in the previous step.
    93  1. Apply the ConfigMap:
    94     ```
    95     $ kubectl apply -f nginx-config.yaml
    96     ```
    97  
    98  ## Step 8 - Configure Load Balancing
    99  
   100  Create a VirtualServer resource for the web application:
   101  ```
   102  $ kubectl apply -f virtual-server.yaml
   103  ```
   104  
   105  Note that the VirtualServer references the policy `oidc-policy` created in Step 6.
   106  
   107  ## Step 9 - Test the Configuration
   108  
   109  1. Open a web browser and navigate to the URL of the web application: `https://webapp.example.com`. You will be redirected to Keycloak.
   110  1. Log in with the username and password for the user you created in Keycloak, `nginx-user` and `test`.
   111  ![keycloak](./keycloak.png)
   112  1. Once logged in, you will be redirected to the web application and get a response from it. Notice the field `User ID` in the response, this will match the ID for your user in Keycloak.
   113  ![webapp](./webapp.png)