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:
- Exposed the Service Mesh Manager dashboard on an external domain name
- The dashboard is registered as an application in the OIDC provider (meaning that the callback URL is set there, the application id and application secret key are available).
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:
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:
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
.