OIDC authentication

Service Mesh Manager allows for authenticating towards an OIDC External Provider instead of relying on the kubeconfig based authentication. This is useful when your organization already has an existing OIDC Provider that is used for user authentication on the Kubernetes clusters.

Since Service Mesh Manager does not require the Kubernetes cluster to be relying on OIDC authentication, you (or the operator of the cluster) might need to set up additional Groups in the cluster (for details, see the Setting up user permissions).

If your organization uses a central authentication database which is not OIDC compliant, check out Dex. Dex can act as an OIDC provider and supports LDAP, GitHub, or any OAuth2 identity provider as a backend. For an example on setting up Service Mesh Manager to use GitHub authentication using Dex, see Using Dex for authentication.

Note: Even if OIDC is enabled in Service Mesh Manager, you can access Service Mesh Manager from the command line by running smm dashboard. This is a fallback authentication/access method in case the OIDC provider is down.

Prerequisites

Before starting to set up OIDC authentication, make sure that you have already:

Enable OIDC authentication

To enable the OIDC authentication, patch the ControlPlane resource with the following settings:

cat > oidc-enable.yaml <<EOF
spec:
  smm:
    auth:
      oidc:
        enabled: true
        client:
          id: ${OIDC_CLIENT_ID}
          issuerURL: https://${IDENTITY_PROVIDER_EXTERNAL_URL}
          secret: ${OIDC_CLIENT_SECRET}
EOF

Where:

  • ${OIDC_CLIENT_ID} is the client id obtained from the External OIDC Provider of your organization.
  • ${OIDC_CLIENT_SECRET} is the client secret obtained from the External OIDC Provider of your organization.
  • ${IDENTITY_PROVIDER_EXTERNAL_URL} is the URL of the External OIDC Provider of your organization.
  • If you are using Service Mesh Manager in Operator Mode, then the Istio deployment is updated automatically.
  • If you are using the imperative mode, run the smm operator reconcile command to apply the changes.

After this change, the dashboard will allow logging in using an External OIDC Provider:

Login using OIDC

Set up user and group mappings

After completing the previous step, the users will be able to authenticate via OIDC. However, Service Mesh Manager needs to map them to Kubernetes users. As Service Mesh Manager uses Kubernetes RBAC for access control, it relies on the same mapping as the Kubernetes API Server’s OIDC authentication backend.

You can use the following settings in the ControlPlane resource :

spec:
  smm:
    auth:
      oidc:
        username:
            claim:  # Claim to take the username from
            prefix: # Append this prefix to all usernames
        groups:
            claim:  # Claim to take the user's groups from
            prefix: # Append this prefix to all group names the user has
        requiredClaims:
            <CLAIM>: "<VALUE>"  # Only allow authentication if the given claim has the specified value

If the target cluster has OIDC enabled, the following table helps mapping the OIDC options of the API server to the settings of Service Mesh Manager:

API Server Setting Description ControlPlane setting
--oidc-issuer-url URL of the provider which allows the API server to discover public signing keys. Only URLs which use the https:// scheme are accepted. This URL should point to the level below .well-known/openid-configuration .spec.smm.auth.client.issuerURL
--oidc-client-id A client id that all tokens must be issued for. .spec.smm.auth.client.id
A client secret that all tokens must be issued for. .spec.smm.auth.client.secret
--oidc-username-claim JWT claim to use as the user name. By default sub, which is expected to be a unique identifier of the end user. .spec.smm.auth.username.claim
--oidc-username-prefix Prefix prepended to username claims to prevent clashes with existing names (such as system:users). For example, the value oidc: will create usernames like oidc:jane.doe. If this flag isn’t provided and –oidc-username-claim is a value other than email, the prefix defaults to the value of –oidc-issuer-url. Use the - value to disable all prefixing. .spec.smm.auth.username.prefix
--oidc-groups-claim JWT claim to use as the user’s group. If the claim is present, it must be an array of strings. .spec.smm.auth.groups.claim
--oidc-groups-prefix Prefix prepended to group claims to prevent clashes with existing names (such as system:groups). For example, the value oidc: will create group names like oidc:engineering and oidc:infra. .spec.smm.auth.groups.prefix
--oidc-required-claim A key=value pair that describes a required claim in the ID Token. If set, the claim is verified to be present in the ID Token with a matching value. .spec.smm.auth.requiredClaims
  • If you are using Service Mesh Manager in Operator Mode, then the Istio deployment is updated automatically.
  • If you are using the imperative mode, run the smm operator reconcile command to apply the changes.

Set up user permissions

Note: This step is only required if the target cluster does not already have OIDC authentication set up. If the Kubernetes cluster’s OIDC authentication settings are matching the ones set in the ControlPlane resource, no further action is needed.

By default, when using OIDC authentication, users and groups cannot modify the resources in the target cluster, so you need to create the ClusterRoleBinding right for these Groups or Users.

The groups a given user belongs to is shown in the right hand menu on the user interface:

Menu with group information

In this example, the username is oidc:test@example.org and the user belongs to only one group, called oidc:example-org:test.

If the Kubernetes Cluster is not using OIDC for authentication, create the relevant ClusterRoleBindings against these Groups and Users.

Using Dex for authentication