Protect your applications running on an IBM Cloud Kubernetes Service cluster with IBM Cloud App ID.

When you create an IBM Cloud Kubernetes Service cluster, a default Application Load Balancer (ALB) is created for you in the new cluster. The ALB is an Ingress controller, in practice.

As of 24 August 2020, you can now choose to deploy the Kubernetes Ingress controller as the default ALB for your cluster. Please see the announcement here for more information.

The ALB takes care of the routing of the incoming HTTP(S) requests to your applications that are deployed in your cluster. In many cases, you may want to authenticate and authorize the clients that send those incoming requests. This article will show you how to use the new IBM Cloud Kubernetes Service ALB OAuth Proxy Add-On to integrate the Kubernetes Ingress controller with IBM Cloud App ID to protect your applications. For more information about IBM Cloud App ID please see this YouTube channel.

How it works

The IBM Cloud Kubernetes Service ALB OAuth Proxy Add-On deploys and manages an OAuth2-Proxy deployment in your cluster for each and every IBM Cloud App ID service instance that you want to use. The OAuth2-Proxy provides the OIDC Relying Party (Client) function for the Kubernetes Ingress controller (ALB).

The following figure presents the interactions of the different system components during an OIDC Authorization Code Flow:

1. The User Agent sends a GET request to obtain the protected data from the Application.
2. The IBM Cloud Kubernetes Service ALB is configured to authenticate such a request. The ALB sends an Authentication request to the OAuth2-Proxy, which has been deployed by the ALB OAuth Proxy Add-on previously.
3. As there is no valid Access Token in the request, the OAuth2-Proxy sends a 401 Unauthorized response to the ALB.
4. The ALB redirects the User Agent to the URL, which will trigger the start of the authorization flow. The URL’s host part points to the ALB.
5. The User Agent sends a new request to the new URL. Due to the host of the URL, the request is routed to the ALB again.
6. The ALB is configured to send this kind of request to the OAuth2-Proxy.
7. The OAuth2-Proxy redirects the User Agent to the Authorization Endpoint of the IBM Cloud App ID Service.
8. The IBM Cloud App ID Service executes the authentication of the End-User behind the User Agent. The IBM Cloud App ID Service uses the services of the Identity Provider, which has been configured for this IBM Cloud App ID Service instance to authenticate the End-User.
9. If the authentication of the End-User is successful, the IBM Cloud App ID Service redirects the User Agent to the redirect URL, which has been registered in the IBM Cloud App ID Service instance. The host part of the redirect URL points to the ALB. The IBM Cloud App ID Service includes the Authorization Code into the redirection response.
10. The User Agent sends a new request with the Authorization Code to the callback URL.
11. The ALB is configured to route this kind of requests to the OAuth2-Proxy.
12. The OAuth2-Proxy sends the Authorization Code to the Token endpoint of the IBM Cloud App ID Service.
13. The IBM Cloud App ID Service responds with an Access Token, an ID Token, and (optionally) a Refresh Token.
14. The OAuth2-Proxy redirects the User Agent to the original request URL. As we use the OAuth2-Proxy in stateless mode, the redirection response contains the Access Token, the ID Token, and the Refresh Token in cookies.
15. The User Agent sends a new request to the original request URL, but this time, it includes the Access Token, the ID Token, and the Refresh Token in the request as cookies.
16. The ALB is configured to authenticate such a request, so the ALB sends an Authentication request to the OAuth2-Proxy.
17. The OAuth2-Proxy validates the tokens and it answers with a 202 Accepted response to the ALB.
18. The ALB routes the request to the backend Application. The request may contain the Access Token, or the ID Token based on the ALB configuration.

Usage

Prerequisites

Create an IBM Cloud App ID service instance and bind that to the cluster:

1. Navigate to IBM Cloud App ID in the service catalog.
2. Select a deployment region and the pricing plan.
3. Replace the auto-filled service name with your own unique name for the IBM Cloud App ID service instance. The service instance name must contain only alphanumeric characters or hyphens (-) and can’t contain spaces.
4. Click Create. The App ID management console will be displayed:

5. In the IBM Cloud App ID management console, navigate to Manage Authentication:

6. In the Identity providers tab, make sure that you have an Identity Provider selected. If no Identity Provider is selected, the user will not be authenticated but will be issued an access token for anonymous access to the app. Next, create a Cloud Directory user:
   • Click Edit on the Cloud Directory card.
   • In the left-hand navigation, click Users:

   • Click Create User. Give the details of your user in the dialog box, and save the user:

7. Navigate back to Manage Authentication, and select the Authentication settings tab:

8. In the Authentication settings tab, add redirect URLs for your app. A redirect URL is the callback endpoint of your app. To prevent phishing attacks, IBM Cloud App ID validates the request URL against the allowlist of redirect URLs. A redirect URL shall have the following form:

   https://<hostname>/oauth2-<your_App_ID_Service_name>/callback

9. Bind the IBM Cloud App ID service instance to your IBM Cloud Kubernetes Service cluster. Be sure to bind the service instance to the same Kubernetes namespace that your Ingress resources will be created:

   ibmcloud cluster service bind --cluster <cluster_name_or_ID> --namespace <namespace> --service <your_App_ID_service_name>

Usage of the ALB OAuth Proxy Add-on

1. Enable the ALB OAuth Proxy Add-on for your cluster:
   • In the IBM Cloud Kubernetes Service console, click your cluster and click the Add-ons tab. On the ALB OAuth Proxy card, click Install:

   • From the IBM Cloud CLI, run the following command:

     ibmcloud ks cluster addon enable alb-oauth-proxy --cluster <cluster_name_or_ID>

2. Verify that the ALB OAuth Proxy Add-On has a status of Addon Ready:

   ibmcloud cluster addon ls --cluster <cluster_name_or_ID>

3. In the Ingress resources for your app where you want to add IBM Cloud App ID authentication, add the following annotations to the metadata.annotations section:

   annotations:
     nginx.ingress.kubernetes.io/auth-url: https://$host/oauth2-<App_id_service_instance_name>
     nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2-<App_ID_service_instance_name>/start?rd=$escaped_request_uri

4. Verify that the IBM Cloud App ID authentication is enforced for your apps. Access your app’s URL in a web browser. If IBM Cloud App ID is correctly applied, you are redirected to an IBM Cloud App ID authentication log-in page. Log in with the user you created in the Cloud Directory above. After a successful authentication, you are redirected to your app and you can see the response of your app in the browser.

More information

For more information, check out our official documentation.

Learn more about the Kubernetes Ingress controller in the IBM Cloud Kubernetes Service:

• Announcing Managed Support of the Kubernetes Ingress Controller for the IBM Cloud Kubernetes Service
• Migration of IBM Ingress Resources to the Kubernetes Ingress Controller