跳到主要内容
版本：v2.5

Configure Azure AD

Microsoft Graph API​

Microsoft Graph API is now the flow through which you will set up Azure AD. The below sections will assist new users in configuring Azure AD with a new instance as well as assist existing Azure app owners in migrating to the new flow.

New User Setup​

If you have an instance of Active Directory (AD) hosted in Azure, you can configure Rancher to allow your users to log in using their AD accounts. Configuration of Azure AD external authentication requires you to make configurations in both Azure and Rancher.

Prerequisite: Have an instance of Azure AD configured.

Notes:

  • Azure AD integration only supports Service Provider initiated logins.
  • Most of this procedure takes place from the Microsoft Azure Portal.

Azure Active Directory Configuration Outline​

Configuring Rancher to allow your users to authenticate with their Azure AD accounts involves multiple procedures. Review the outline below before getting started.

Tip: Before you start, we recommend creating an empty text file. You can use this file to copy values from Azure that you'll paste into Rancher later.

1. Register Rancher with Azure​

Before enabling Azure AD within Rancher, you must register Rancher with Azure.

  1. Log in to Microsoft Azure as an administrative user. Configuration in future steps requires administrative access rights.

  2. Use search to open the App registrations service.

    Open App Registrations

  3. Click New registrations and complete the Create form.

    New App Registration

    3.1. Enter a Name (something like Rancher).

    3.2. From Supported account types, select "Accounts in this organizational directory only (AzureADTest only - Single tenant)" This corresponds to the legacy app registration options.

    Important: In the updated Azure portal, Redirect URIs are synonymous with Reply URLs. In order to use Azure AD with Rancher, you must whitelist Rancher with Azure (previously done through Reply URLs). Therefore, you must ensure to fill in the Redirect URI with your Rancher server URL, to include the verification path as listed below.

    3.3. In the Redirect URI section, make sure Web is selected from the dropdown and enter the URL of your Rancher Server in the text box next to the dropdown. This Rancher server URL should be appended with the verification path: <MY_RANCHER_URL>/verify-auth-azure.

    Tip: You can find your personalized Azure Redirect URI (reply URL) in Rancher on the Azure AD Authentication page (Global View > Authentication > Web).

    3.4. Click Register.

Important: It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.

2. Create a new client secret​

From the Azure portal, create a client secret. Rancher will use this key to authenticate with Azure AD.

  1. Use search to open App registrations services. Then open the entry for Rancher that you created in the last procedure.

    Open Rancher Registration

  2. From the navigation pane on left, click Certificates and Secrets.

  3. Click New client secret. Create new client secret

    • 3.1. Enter a Description (something like Rancher).
    • 3.2. Select duration for the key from the options under Expires. This drop-down sets the expiration date for the key. Shorter durations are more secure, but require you to create a new key after expiration.
    • 3.3. Click Add (you don't need to enter a value—it will automatically populate after you save).

  4. Copy the key value and save it to an empty text file.

    You'll enter this key into the Rancher UI later as your Application Secret.

    You won't be able to access the key value again within the Azure UI.

3. Set Required Permissions for Rancher​

Next, set API permissions for Rancher within Azure.

警告

Ensure that you set the permissions of type Application and NOT Delegated. Otherwise, you may not be able to login to Azure AD. This issue will persist even after you disable/re-enable Azure AD and will require an hour wait, or manual deletion of a cache value to resolve.

  1. From the navigation pane on left, select API permissions.

    Open Required Permissions

  2. Click Add a permission.

  3. From the Microsoft Graph, select the following Application Permissions:

    • Group.Read.All
    • User.Read.All

  1. Return to API permissions in the left nav bar. From there, click Grant admin consent. Then click Yes.

    Note: You must be signed in as an Azure administrator to successfully save your permission settings.

4. Copy Azure Application Data​

As your final step in Azure, copy the data that you'll use to configure Rancher for Azure AD authentication and paste it into an empty text file.

  1. Obtain your Rancher Tenant ID.

    1. Use search to open App registrations.

    Open App Registrations

    1. Find the entry you created for Rancher.

    2. Copy the Directory ID and paste it into your text file.

    Tenant ID

    • You'll paste this value into Rancher as your Tenant ID.

  2. Obtain your Rancher Application (Client) ID.

    1. Use search to open App registrations (if not already there).

    2. In Overview, find the entry you created for Rancher.

    3. Copy the Application (Client) ID and paste it to your text file.

    Application ID

  3. Your endpoint options will typically be Standard and China. With the Standard option, perform the steps below and Rancher will take care of the rest.

    • Enter the Tenant ID, Application ID, and Application Secret
    • Click Enable

Standard Endpoint Options

For Custom Endpoints:

Warning: Custom Endpoints are not supported nor fully tested by Rancher.

You will need to also manually enter the Graph, Token, and Auth Endpoints.

  • From App registrations, click Endpoints:

Click Endpoints

  • Copy the following endpoints to your clipboard and paste them into your text file (these values will be your Rancher endpoint values). Make sure to copy the v1 version of the endpoints.

    • Microsoft Graph API endpoint (Graph Endpoint)
    • OAuth 2.0 token endpoint (v1) (Token Endpoint)
    • OAuth 2.0 authorization endpoint (v1) (Auth Endpoint)

5. Configure Azure AD in Rancher​

From the Rancher UI, enter information about your AD instance hosted in Azure to complete configuration.

Enter the values that you copied to your text file.

  1. Log into Rancher.

  2. In the top left corner, click ☰ > Users & Authentication.

  3. In the left navigation menu, click Auth Provider.

  4. Click AzureAD.

  5. Complete the Configure Azure AD Account form using the information you copied while completing Copy Azure Application Data.

    The following table maps the values you copied in the Azure portal to the fields in Rancher.

    Rancher FieldAzure Value
    Tenant IDDirectory ID
    Application IDApplication ID
    Application SecretKey Value
    Endpointhttps://login.microsoftonline.com/

For Custom Endpoints:


The following table maps the custom config values you copied in the Azure portal to the fields in Rancher:
Rancher FieldAzure Value
Graph EndpointMicrosoft Graph API Endpoint
Token EndpointOAuth 2.0 Token Endpoint
Auth EndpointOAuth 2.0 Authorization Endpoint

**Important:** When entering the Graph Endpoint in a custom config, remove the tenant ID from the URL, like below:https://graph.microsoft.com/abb5adde-bee8-4821-8b03-e63efdc7701c
  1. Click Enable.

Result: Azure Active Directory authentication is configured.

(Optional) Configure Authentication with Multiple Rancher Domains​

If you have multiple Rancher domains, it's not possible to configure multiple redirect URIs through the Rancher UI. The Azure AD configuration file, azuread, only allows one redirect URI by default. You must manually edit azuread to set the redirect URI as needed for any other domains. If you don't manually edit azuread, then upon a successful login attempt to any domain, Rancher automatically redirects the user to the Redirect URI value you set when you registered the app in Step 1. Register Rancher with Azure.

Migrating from Azure AD Graph API to Microsoft Graph API​

Since Azure AD Graph API was deprecated in June 2022 and will be retired at the end of 2022, users should update their Azure AD App to use the new Microsoft Graph API in Rancher.

Updating Endpoints in the Rancher UI​

Important: Admins should create a [backup]../../../..//new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md) right before they commit to the endpoint migration in Step 4 below.

  1. Update the permissions of your Azure AD app registration as described here. This is critical.

  2. Log into Rancher.

  3. In the Rancher UI homepage, make note of the banner at the top of screen that advises users to update their Azure AD authentication. Click on the link provided to do so.

    Rancher UI Banner

  4. To complete the move to the new Microsoft Graph API, click Update Endpoint, then click Save.

    Note: Ensure that your Azure app has a new set of permissions before starting the update.

    Update Endpoint

  5. When you receive the pop-up warning message, click Update.

    Azure Update Pop-up

  6. Refer to the tables below for the full list of endpoint changes that Rancher performs. Admins do not need to do this manually.

Air-Gapped Environments​

In air-gapped environments, admins should ensure that their endpoints are whitelisted since the Graph Endpoint URL is changing.

Rolling Back the Migration​

If you need to roll back your migration, please note the following:

  1. Admins are encouraged to use the proper restore process if they want to go back. Please see backup docs, restore docs, and examples for reference.

  2. Azure app owners who want to rotate the Application Secret will need to also rotate it in Rancher as Rancher does not automatically update the Application Secret when it is changed in Azure. In Rancher, note that it is stored in a Kubernetes secret called azureadconfig-applicationsecret which is in the cattle-global-data namespace.

  3. Caution: If admins upgrade to Rancher v2.5.16 with an existing Azure AD setup and choose to disable the auth provider, they won't be able to restore the previous setup and also will not be able to set up Azure AD using the old flow. Admins will then need to register again with the new auth flow. Rancher now uses the new Graph API and, therefore, users need set up the proper permissions in the Azure portal.

Global:​

Rancher FieldDeprecated Endpoints
Auth Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/authorize
Endpointhttps://login.microsoftonline.com/
Graph Endpointhttps://graph.windows.net/
Token Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/token
Rancher FieldNew Endpoints
Auth Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/v2.0/authorize
Endpointhttps://login.microsoftonline.com/
Graph Endpointhttps://graph.microsoft.com
Token Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token

China:​

Rancher FieldDeprecated Endpoints
Auth Endpointhttps://login.chinacloudapi.cn/{tenantID}/oauth2/authorize
Endpointhttps://login.chinacloudapi.cn/
Graph Endpointhttps://graph.chinacloudapi.cn/
Token Endpointhttps://login.chinacloudapi.cn/{tenantID}/oauth2/token
Rancher FieldNew Endpoints
Auth Endpointhttps://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/authorize
Endpointhttps://login.partner.microsoftonline.cn/
Graph Endpointhttps://microsoftgraph.chinacloudapi.cn
Token Endpointhttps://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/token