Skip to main content
Version: 3.18 (latest)

Configure an external identity provider

Big picture​

Configure an external identity provider (IdP), create a user, and log in to Calico Enterprise Manager UI.

(If you are just starting out, the quickest way to allow user access is to configure the default, token authentication.)

Concepts​

The Calico Enterprise authentication method is configured through the Authentication API resource named, tigera-secure.

When configuring your cluster, you may be asked for the following inputs:

  • Client Id: Id for exchanging data that are shared between the IdP and an application.
  • Client Secret: Secret associated with the client id used by server applications for exchanging tokens.
  • Issuer URL: URL where the IdP can be reached, based on the conventions of OAuth and OIDC.
  • Claims: Every time your IdP issues a token for a valid user, these claims add metadata about the user. Calico Enterprise uses this to determine the username.

Before you begin​

Supported identity providers

  • OIDC authentication: User identity is managed outside of the cluster by an OIDC authorization server.
  • Google OIDC authentication: User identity is managed by Google OIDC. Choose this option if you want to use GSuite groups.
  • OpenShift authentication: User identity is provided by the OpenShift OAuth server.
  • LDAP authentication: User identify is provided using the LDAP server.

Required

How to​

Configure an external identity provider for user authentication​

  1. Apply the Authentication CR to your cluster to let the operator configure your login. The following example uses the email claim. The email field from the JWT (created by your IdP), is used as the username for binding privileges.

    apiVersion: operator.tigera.io/v1
    kind: Authentication
    metadata:
      name: tigera-secure
    spec:
       # This indicates where the Manager UI can be accessed from the browser. Include the port only if the manager UI is not running on port 443.
      managerDomain: https://<domain-of-manager-ui>
      oidc:
        issuerURL: <your-idp-issuer>
        usernameClaim: email

  2. Apply the secret to your cluster with your OIDC credentials. To get the values, consult the documentation of your provider.

    apiVersion: v1
    kind: Secret
    metadata:
      name: tigera-oidc-credentials
      namespace: tigera-operator
    data:
      clientID: <your-base64-clientid>
      clientSecret: <your-base64-clientid-secret>

Grant user login privileges​

note

For OpenShift users, replace kubectl with oc in the following commands, or apply cluster roles from the OpenShift console: User Management, users.

For admin users, apply this cluster role.

kubectl create clusterrolebinding <user>-tigera-network-admin --user=<user> --clusterrole=tigera-network-admin

For basic users with view-only permissions, apply this role.

kubectl create clusterrolebinding <user>-tigera-ui-user --user=<user> --clusterrole=tigera-ui-user

Or use the groups flag to assign cluster role to a group of users.

kubectl create clusterrolebinding all-developers-tigera-ui-user --group=<group> --clusterrole=tigera-ui-user

(Optional) Allow Calico Enterprise URIs in your IdP​

Most IdPs require redirect URIs to be allowed to redirect users at the end of the OAuth flow to the Calico Enterprise Manager or to Kibana. Consult your IdP documentation for authorizing your domain for the respective origins and destinations.

Authorized redirect URIs

  • https://<host><port>/dex/callback

Troubleshooting​

  • ManagerDomain localhost and 127.0.0.1 are not the same. If you configure localhost:9443 as your managerDomain, while navigating to https://127.0.0.1:9443, the OIDC security checks will deny you access.
  • Omit the port from managerURL if it is listening on the standard port (:443) for HTTPS.
  • When your usernameClaim is not email and usernamePrefix is omitted, we have implemented a default prefix identical to how Kubernetes has for their kube-apiserver, see the oidc-username-claim documentation. For example, if the managerDomain in your Authentication spec is https://example.com, and the username claim maps to jane, the (cluster) role binding should be bound to: https://example.com/dex#jane
  • When you encounter problems while configuring your IdP, we encourage you to use the network tab of the browser dev tools to inspect requests with error codes and to decode authorization headers of the HTTP requests.
  • If you would like to bring a self-signed certificate for your IdP and are using OIDC, you can do so by adding the field rootCA to secret tigera-oidc-credentials. The value for this field should contain the certificate in PEM format.
  • If logging into Kibana fails with a cookie not present error, update the browser settings to allow third-party cookies, as Calico Enterprise Manager UI uses Kibana's cookies during login.
  • If you need to configure LDAP with a DN that has spaces, use double quotes to escape them. For example: cn="example common name",ou="example org unit",DC=example,DC=org.

Additional resources​