Skip to main content
Version: latest

Enable SSO with Microsoft Entra ID

Single Sign-On (SSO) is an authentication method that enables users to log in to multiple applications and websites with one set of credentials. SSO uses Secure Socket Layer (SSL) certificates to establish and maintain trust between the Service Provider (SP) and an Identity Provider (IDP).

OpenID Connect (OIDC) lets developers authenticate users across websites and apps without owning and managing password files. This technology allows Palette to verify the identity of the person currently using the browser or application.

In October 2023, Microsoft renamed Azure Active Directory to Microsoft Entra ID. For the purposes of this guide, please consider Microsoft Entra ID and Azure Active Directory to be synonymous. Microsoft Entra ID securely manages anything to do with the user's information, access, and the trust relationships between parties in a flow. It authenticates the user's identity, grants and revokes access to resources, and issues tokens.

This document will guide you on deploying and enabling SSO with Microsoft Entra based on OIDC for integration with Palette and Kubernetes clusters.

tip

If you want to enable OIDC at the Kubernetes cluster level, refer to the Enable OIDC in Kubernetes Clusters section.

Enable OIDC SSO in Palette​

Use the following steps to enable OIDC SSO in Palette with Microsoft Entra ID.

Prerequisites​

  • Palette or Palette VerteX version 4.0.X or greater.

  • For Microsoft Entra ID to work correctly with Palette, you must enable HTTPS and configure TLS.

  • A Microsoft Entra ID subscription. You will need an account with one of the following roles: Global Administrator, Cloud Application Administrator, or Application Administrator. Alternatively, you may be the owner of the service principal.

  • If you want to use the same Microsoft Entra ID application for OIDC-based SSO in your Kubernetes cluster itself, you need to install kubelogin on your local workstation to handle retrieval of access tokens for your cluster.

  • Palette requires the following claims to be present in the OIDC token:

    Claim NameDefault ValueDescription
    EmailemailThe user's email address.
    First Namegiven_nameThe user's first name.
    Last Namefamily_nameThe user's last name.
    Spectro TeamgroupsThe user's group memberships in the Identity Provider.

    Change the claim names in your IdP if they are different from the default values. If the OIDC token does not contain these claims, toggle the Use userinfo endpoint option in the OIDC configuration to allow Palette to fetch the missing claims from the user information endpoint.

Configure Microsoft Entra ID with Palette​

  1. Log in to Palette as a Tenant Admin.

  2. Navigate to the left Main Menu and select Tenant Settings. From the Tenant Menu, select SSO, then Configure, and lastly, click on the OIDC tab.

  3. Copy the Callback URL to your clipboard. This URL will be used in the next step to configure Microsoft Entra ID.

  4. In a separate browser tab, log in to the Microsoft Entra ID Admin console and open the App registration blade.

  5. Click on New registration and assign a name to the new registration. In this guide, the example app registration is named palette_oidc.

  6. Next, select Web, paste the Palette Callback URL value from your clipboard into the Redirect URL (optional) field, and click Register.

    Azure application creation screen

  7. From the app overview page, navigate to the left Main Menu and select Certificates & secrets. In the following screen, click on New client secret.

  8. Add a description for the secret and select an expiration period. Click on Add to create the secret.

    warning

    We recommend you store the secret value in a secure location, such as a password manager. You will need this value later when you configure Palette.

  9. From the application overview page, navigate to the left Main Menu and select Token configuration.

  10. Select the Add optional claim button. Choose Token type as ID, and add the claims email and preferred_username. When finished, click the Add button.

    info

    If you are using Entra v2 ID tokens, add the claim family_name and given_name to your token configuration. Entra v1 ID tokens already include these claims by default.

    Add a claim button

  11. In addition to allowing individual user authentication, Palette provides group claim functionality, allowing an OIDC identity provider, like Microsoft Entra ID, to identify the user's Entra ID group membership within Palette. To enable group membership, select the Add groups claim button. Then select Security groups and Group ID for each property: ID, Access and SAML.

    Groups and individuals can be assigned a group membership in Azure

    When completed, the Token Configuration page will look similar to the image below.

    A view of the token configuration screen

  12. From the application overview page, navigate to the left Main Menu and select the Overview tab. From the Overview selection, save the following fields for the next steps you will complete in Palette.

    FieldDescription
    Application (client) IDThe Application ID is also known as the client ID. This is a unique identifier for your Azure application.
    Object IDThe Object ID is the unique identifier for the application in Azure AD.
    Directory (tenant) IDThe Directory ID is the unique identifier for your Azure AD tenant.
    Secret ValueThe Secret Value is the value of the client secret you created in the previous steps.
    Additional Redirect URLs

    You can also add additional redirect URLs if needed. For example, to enable integration with the Kubernetes Dashboard, add the following redirect URI to the list of redirect URIs in the Azure AD application:

    URLType of Access
    http://localhost:8000UsUseing kubectl with the kube-login plugin from a workstation
    https://<fqdn_of_k8s_dashboard>/oauth/callbackUse OIDC to authenticate and log in to the Kubernetes Dashboard

Configure Microsoft Entra ID with Users and Groups​

  1. Navigate to the Microsoft Entra ID Groups page. You can use existing groups or create new ones. In this guide, we will create four new groups for testing purposes.

  2. Select New Group and assign a name to the new group. Repeat this step to create the remaining groups. Use the following names for the groups:

    • palette_tenant_admins
    • palette_default_project_admins
    • k8s_cluster_admins
    • k8s_cluster-editor

  3. Record each group's name and Object ID for future steps. You will use this information in future steps to configure Palette.

Add & Edit Entra ID Users for Testing​

  1. Open the Users page in Microsoft Entra ID. You will create three test users in Microsoft Entra ID for testing purposes.

  2. Click on New User and assign a name to the new user. Repeat this step to create the remaining users. Use the following information for the users:

    • Create the new user Defaultprojectadmin with the following inputs: - User principal name example: defaultprojectadmin@SpectroCloud500.onmicrosoft.com

    • Display name example: defaultprojectadmin - Browse to Properties, Edit First Name: DefaultProject - Browse to Properties, Edit Last Name: Admin - Browse to Properties, add Email: defaultprojectadmin@SpectroCloud500.onmicrosoft.com

    • Add this account to the Entra ID group Palette_default_project_admins

    • Create the new user Test User with the following inputs:

      • User principal name example: testuser@SpectroCloud500.onmicrosoft.com
      • Display name example: Test User
      • Browse to Properties, Edit First Name: Test
      • Browse to Properties, Edit Last Name: User
      • Browse to Properties, add Email: testuser@SpectroCloud500.onmicrosoft.com
      • Do not add this account to any groups

    • Create an external user with your corporate/personal email account: - User principal name example: your corporate email address

      • Display name example: Your First Name and Last Name - Browse to Properties, Edit First Name - Browse to Properties, Edit Last Name - Browse to Properties, add your corporate email address - Add this account to the Entra ID Group palette_tenant_admins

  3. Add your Entra ID admin account, the account you used to create the App in Microsoft Entra ID, to the following groups: palette_tenant_admins and k8s_cluster_admins.

Configure Palette SSO​

  1. At this point, you should have at least four Entra ID user objects, including the admin account in Entra ID. Your Palette tenant will need information from Microsoft to complete the OIDC setup. Navigate back to the Palette browser tab .

  2. From the left Main Menu select Users and Teams. Next, choose Teams and then select Create New Team.

  3. Create four Palette teams, with each team named after the Entra ID Group ID you created in the previous steps. Use the table below as an example reference.

    Palette Team Name is the Entra Group IDEntra ID Group Name
    e3ac07cc-bd12-4edc-92a4-983d783153bapalette_tenant_admins
    88f61c49-1dd1-40c3-a820-68a513a38725palette_default_project_admins
    3f33c3a5-e0af-4ef6-9671-c7545fe264f3k8s_cluster_admins
    c4606295-e8b0-4df0-891b-de4428d7e54fk8s_cluster-editor

  4. Assign the following Roles to each Palette team. For example purposes, the same Entra Group ID values used in the table above are used in the table below.

    Palette Team NameRoleEntra ID Group Name
    e3ac07cc-bd12-4edc-92a4-983d783153baTenant Adminpalette_tenant_admins
    88f61c49-1dd1-40c3-a820-68a513a38725Project Adminpalette_default_project_admins
    3f33c3a5-e0af-4ef6-9671-c7545fe264f3No role assignedk8s_cluster_admins
    c4606295-e8b0-4df0-891b-de4428d7e54fNo role assignedk8s_cluster-editor

    Refer to the images below to ensure you have the correct settings.

    Example of IDs

    Example of IDs with Palette roles attached to a team

Palette SSO OIDC Configuration​

  1. Navigate to left Main Menu, select Tenant Settings. Next, click on SSO and select the OIDC tab.

  2. You will now configure the OIDC settings in Palette. Use the table below as a reference and populate the fields with the information you saved from the previous steps.

    FieldDescription
    Issuer URLRefer to the Find your app's OpenID configuration document URI guide to learn how to determine your issuer URL. If you are using Entra v2 tokens with the endpoint https://login.microsoftonline.com/{tenant-ID}/v2.0, ensure you added the claims family_name and given_name to the token configuration.
    Client IDThe application ID from Entra ID
    Client SecretThe application secret you created
    Default TeamsLeave it blank if you don't want users without group claims to be assigned to a default group. If you do, enter the desired default group name. If you use this option, be careful with how much access you assign to the group
    ScopesAdd openid, profile and email.
    EmailUse email as the default value

  3. Leave other fields with the default values and click Enable. If all required values are provided, you will receive a message stating that OIDC is configured successfully.

    Example of Palette with populated input fields

You have now successfully configured OIDC SSO in Palette. Next, validate the configuration by logging in to Palette with an Entra ID user account.

Validate​

  1. Log out of Palette. To log out, click on User Menu in the top right corner of the screen and select Sign Out.

  2. The Palette login screen now displays a Sign in button and no longer presents a username and password field. If this is your first time logging in with SSO, you will be redirected to the Entra ID login page. Depending on your organization's SSO settings, this could be a simple login form or require MFA (Multi-Factor Authentication). Make sure you log in as a user who is a member of the palette-tenant-admins group in Entra ID. Once authenticated, you will automatically be redirected back to Palette and logged into Palette as that user.

  3. Navigate to the left Main Menu and ensure the Tenant Settings option is available. If the Tenant Settings option is not available, then you are not logged in as a user who is a member of the palette-tenant-admins group in Entra ID.

    tip

    Below the Sign In button, there is a link titled SSO issues? --> Use your password. The link can be used to bypass SSO and log in with a local Palette account in case there is an issue with SSO and you need to access Palette without SSO.

Enable OIDC in Kubernetes Clusters With Entra ID​

Kubelogin is a kubectl plugin for Kubernetes OIDC authentication. When you use kubectl, kubelogin opens up your browser, starts a session, and redirects you to your IDP's login site. Upon a succesfull login, you receive an authentication token that is used to grant you access to the cluster.

Use the following steps to enable OIDC in Kubernetes clusters with Microsoft Entra ID.

Prerequisites​

  • Palette or Palette VerteX version 4.0.X or greater.

  • For Microsoft Entra ID to work correctly with Palette, you must enable HTTPS and configure TLS.

  • OIDC configured in Palette with Microsoft Entra ID. Refer to the Enable OIDC SSO in Palette section for detailed guidance on how to configure OIDC in Palette.

  • Install kubelogin your local workstation.

Create Cluster Profile With RoleBindings​

This section describes how to enable Entra ID SSO authentication to access a Kubernetes cluster.

  1. Log in to Palette as a Tenant Admin.

  2. Navigate to the left Main Menu and select Profiles.

  3. Create a new Cluster Profile of the type Full. Select an OS, and proceed to the Kubernetes selection step.

  4. Choose the Kubernetes layer and click on Values to modify the pack YAML values.

  5. Navigate to the kubeadminconfig.apiServer.extraArgs section of the pack layer. Modify the following parameters:

    ParameterDescription
    oidc-username-claimThe claim to use as the user name. This is the claim that will be used to identify the user in Kubernetes
    oidc-groups-claimThe claim to use as the user's group membership. This is the claim that will be used to identify the user's group membership in Kubernetes
    oidc-issuer-urlThe URL of the OIDC provider
    oidc-client-idThe client ID for the OIDC provider. This is the client ID that will be used to authenticate to the OIDC provider
    kubeadminconfig:
      apiServer:
        extraArgs:
          oidc-groups-claim: "groups"
          oidc-username-claim: "email"
          oidc-issuer-url: "https://sts.windows.net/************"
          oidc-client-id: "**************"

  6. Next, find the clientConfig section and modify the following parameters with the values you saved when you created the Azure Entra ID application.

    ParameterDescription
    oidc-issuer-urlThe URL of the OIDC provider
    oidc-client-idThe client ID for the OIDC provider. This is the client ID that will be used to authenticate to the OIDC provider
    oidc-client-secretThe client secret for the OIDC provider. This is the client secret that will be used to authenticate to the OIDC provider
    oidc-extra-scopeThe scope tags
    clientConfig:
      oidc-issuer-url: "{{ .spectro.pack.kubernetes.kubeadmconfig.apiServer.extraArgs.oidc-issuer-url }}"
      oidc-client-id: "{{ .spectro.pack.kubernetes.kubeadmconfig.apiServer.extraArgs.oidc-client-id }}"
      oidc-client-secret: "**************************"
      oidc-extra-scope: "profile,email"

  7. Complete the remaining steps to create the cluster profile. Once you have specified the container network interface and the storage container interface, select Add New Pack to add the RBAC addon pack.

  8. Select the Spectro RBAC from the Public Repo or the Palette Registry.

  9. Select the latest version and click on the Values button to modify the pack YAML values.

  10. Navigate to the clusterRoleBindings section of the pack layer. For Entra ID integration with RBAC, edit your RBAC pack values to match the YAML snippet below. Alternatively, copy and paste the entire block to your RBAC pack and modify you inputs where appropriate. Replace all the name fields that start with the value INSERT with the Entra groups' ID you created in Azure.

    pack:
      spectrocloud.com/install-priority: "0"
    charts:
      spectro-rbac:
        # Specify one or more ClusterRoleBinding
        # Note that the _name_ attribute is optional
        clusterRoleBindings:
          - role: cluster-admin
            name: bind-cluster-admin-role-to-cluster-admin
            subjects:
              #- type: User
              #name: user5
              - type: Group
                # For "name", input the - Entra ID Group ID name and add a comment on what the - Entra ID displayname is that corresponds to the - Entra ID Group Name
                # Example: - Entra ID Group Object Id "70d19fd6-####-####-####-##c6c915e301" is tied to the - Entra ID Security Group with the display name of "cluster-admin-role".
                # name: "- Entra ID GROUP ID NAME"
                name: "INSERT - Entra ID GROUP ID For Cluster Admins"
          - role: admin
            name: bind-admin-role-to-admin
            subjects:
              #- type: User
              #name: user5
              - type: Group
                # For "name", input the - Entra ID Group ID name and add a comment on what the - Entra ID displayname is that corresponds to the - Entra ID Group Name
                # Example: - Entra ID Group Object Id "064f2e40-####-####-####-##b9f7927976" is tied to the - Entra ID Security Group with the display name of "admin-role".
                # name: "- Entra ID GROUP ID NAME"
                name: "INSERT - Entra ID GROUP ID For Admins"
          - role: view
            name: bind-view-role-to-view
            subjects:
              #- type: User
              #name: user6
              - type: Group
                # For "name", input the - Entra ID Group ID name and add a comment on what the - Entra ID displayname is that corresponds to the - Entra ID Group Name
                # Example: - Entra ID Group Object Id "732edc96--####-####-####-##851dee3380" is tied to the - Entra ID Security Group with the display name of "view-role".
                # name: "- Entra ID GROUP ID NAME"
                name: "INSERT - Entra ID GROUP ID For Viewers"
              #- type: ServiceAccount
              #name: group6
              #namespace: foo
          - role: edit
            name: bind-edit-role-to-edit
            subjects:
              #- type: User
              #name: user6
              - type: Group
                # For "name", input the - Entra ID Group ID name and add a comment on what the - Entra ID displayname is that corresponds to the - Entra ID Group Name
                # Example: - Entra ID Group Object Id "21b55c08-6-####-####-####-##a3e2245ad7" is tied to the - Entra ID Security Group with the display name of "edit-role".
                # name: "- Entra ID GROUP ID NAME"
                name: "INSERT - Entra ID GROUP ID For Edit"
              #- type: ServiceAccount
              #name: group6
              #namespace: foo
        #namespaces:
        # Specify one or more RoleBindings
        #- namespace: team1
        #createNamespace: true
        #roleBindings:
        #- role: admin
        #name: special-override-name-admin-role
        #kind: ClusterRole
        #subjects:
        #- type: User
        #name: user3
        #- type: Group
        #name: team1namespaceadmin
        #- role: view
        #kind: ClusterRole
        #subjects:
        #- type: User
        #name: user4
        #- type: Group
        #name: team1namespaceview
        #- namespace: team2
        #createNamespace: true
        #roleBindings:
        #- role: admin
        #name: special
        #kind: ClusterRole
        #subjects:
        #- type: User
        #name: user1
        #- type: Group
        #name: group1

    You are matching the out-of-the-box Kubernetes roles cluster-admin, admin, view, and edit to the Entra ID groups you created in the previous steps. Members of the Entra ID group will be assigned the corresponding Kubernetes role. For example, members of the Entra ID group k8s_cluster_admins will be assigned the Kubernetes role cluster-admin. You can change the YAML and use roleBindings to assign roles to specific namespaces versus using a clusterRoleBinding to assign roles to the entire cluster.

  11. Click on Confirm & Create to proceed with the cluster profile creation. Click on Next to proceed to the Review step.

  12. Review the cluster profile settings and click on Finish Configuration to create the cluster profile.

You now have a cluster profile that will use Entra ID SSO authentication to access a Kubernetes cluster. You can now create a cluster using this profile. You will be redirected to the Entra ID login page when you log in to the cluster. Depending on your organization's SSO settings, this could be a simple login form or require MFA (Multi-Factor Authentication).

Validate​

You can validate the Entra ID SSO integration by deploying a Kubernetes cluster with the cluster profile you created in the previous steps. Once the cluster is deployed, you can log in to the cluster by using kubectl with the kubelogin plugin from a workstation that has kubelogin installed.

  1. Log in to Palette as a user who is a member of one of the Entra ID groups you created in the previous steps.

  2. Navigate to the left Main Menu and select Clusters.

  3. Deploy a cluster using the cluster profile you created in the previous steps. Check out the tutorial Deploy a Cluster for detailed guidance on how to deploy a cluster.

  4. Once the cluster is deployed, select the cluster from the cluster list view to access the cluster details page.

  5. Download the kubeconfig file for the cluster.

  6. Configure kubectl to use the kubeconfig file you downloaded in the previous step. Refer to the Configure kubectl documentation for detailed guidance on how to configure kubectl.

  7. Issue a kubectl command to access the cluster. For example, you can issue the following command to view the nodes in the cluster.

    kubectl get pods --all-namespaces

  8. You will be redirected to the Entra ID login page. Depending on your organization's SSO settings, this could be a simple login form or require Multi-Factor Authentication.

  9. Once you have successfully authenticated, you will be redirected back to the terminal and the kubectl command will be issued.

A list of pods in the cluster will be displayed if everything is configured correctly. If you are not able to access the cluster, check the kubeconfig file to ensure the OIDC configuration is correct. Also, make sure you have kubelogin installed on your workstation. Refer to the Configure kubectl documentation for detailed guidance on how to configure kubectl.

Resources​