将重定向 URI 与用于 iOS 和 macOS 的 Microsoft 身份验证库配合使用Using redirect URIs with the Microsoft authentication library for iOS and macOS

当用户进行身份验证时,Azure Active Directory (Azure AD) 会将令牌发送到应用,方法是使用注册到 Azure AD 应用程序的重定向 URI。When a user authenticates, Azure Active Directory (Azure AD) sends the token to the app by using the redirect URI registered with the Azure AD application.

Microsoft 身份验证库 (MSAL) 要求重定向 URI 按特定格式注册到 Azure AD 应用。The Microsoft Authentication library (MSAL) requires that the redirect URI be registered with the Azure AD app in a specific format. 在未指定重定向 URI 的情况下,MSAL 使用默认的。MSAL uses a default redirect URI, if you don't specify one. 格式为 msauth.[Your_Bundle_Id]://authThe format is msauth.[Your_Bundle_Id]://auth.

默认的重定向 URI 格式适用于大多数应用和方案,包括代理身份验证和系统 Web 视图。The default redirect URI format works for most apps and scenarios, including brokered authentication and system web view. 尽可能使用默认格式。Use the default format whenever possible.

但是,你可能需要为高级方案更改重定向 URI,如下所述。However, you may need to change the redirect URI for advanced scenarios, as described below.

需要其他重定向 URI 的方案Scenarios that require a different redirect URI

跨应用单一登录 (SSO)Cross-app single sign on (SSO)

如果希望 Microsoft 标识平台跨应用共享令牌,每个应用都需要有相同的客户端 ID 或应用程序 ID。For the Microsoft Identity platform to share tokens across apps, each app needs to have the same client ID or application ID. 这是在门户中注册应用时系统提供的唯一标识符(不是按应用注册到 Apple 时的应用程序捆绑 ID)。This is the unique identifier provided when you registered your app in the portal (not the application bundle ID that you register per app with Apple).

每个 iOS 应用的重定向 URI 必须是不同的。The redirect URIs need to be different for each iOS app. 这样 Microsoft 标识服务才能唯一标识共享某个应用程序 ID 的不同应用。This allows the Microsoft identity service to uniquely identify different apps that share an application ID. 每个应用程序可以在 Azure 门户中注册多个重定向 URI。Each application can have multiple redirect URIs registered in the Azure portal. 套件中的每个应用都具有不同的重定向 URI。Each app in your suite will have a different redirect URI. 例如:For example:

在 Azure 门户中进行以下应用程序注册时:Given the following application registration in the Azure portal:

  • 客户端 ID:ABCDE-12345(这是单个客户端 ID)Client ID: ABCDE-12345 (this is a single client ID)
  • RedirectUris:msauth.com.contoso.app1://authmsauth.com.contoso.app2://authmsauth.com.contoso.app3://authRedirectUris: msauth.com.contoso.app1://auth, msauth.com.contoso.app2://auth, msauth.com.contoso.app3://auth

App1 使用重定向 msauth.com.contoso.app1://authApp1 uses redirect msauth.com.contoso.app1://auth.
App2 使用 msauth.com.contoso.app2://authApp2 uses msauth.com.contoso.app2://auth.
App3 使用 msauth.com.contoso.app1://authApp3 uses msauth.com.contoso.app1://auth.

从 ADAL 迁移到 MSALMigrating from ADAL to MSAL

在将使用 Azure AD 身份验证库 (ADAL) 的代码迁移到 MSAL 时,你可能已为应用配置重定向 URI。When migrating code that used the Azure AD Authentication Library (ADAL) to MSAL, you may already have a redirect URI configured for your app. 可以持续使用同一个重定向 URI,前提是 ADAL 应用已配置为支持中转方案,且重定向 URI 满足 MSAL 重定向 URI 格式要求。You can continue using the same redirect URI as long as your ADAL app was configured to support brokered scenarios and your redirect URI satisfies the MSAL redirect URI format requirements.

MSAL 重定向 URI 格式要求MSAL redirect URI format requirements

  • MSAL 重定向 URI 必须采用 <scheme>://host 格式The MSAL redirect URI must be in the form <scheme>://host

    其中的 <scheme> 是用于标识应用的唯一字符串。Where <scheme> is a unique string that identifies your app. 它主要基于应用程序的捆绑标识符,目的是保证唯一性。It's primarily based on the Bundle Identifier of your application to guarantee uniqueness. 例如,如果应用的捆绑 ID 为 com.contoso.myapp,则重定向 URI 将采用 msauth.com.contoso.myapp://auth 格式。For example, if your app's Bundle ID is com.contoso.myapp, your redirect URI would be in the form: msauth.com.contoso.myapp://auth.

    如果从 ADAL 进行迁移,则重定向 URI 可能会采用此格式:<scheme>://[Your_Bundle_Id],其中的 scheme 是唯一字符串。If you're migrating from ADAL, your redirect URI will likely have this format: <scheme>://[Your_Bundle_Id], where scheme is a unique string. 只要使用 MSAL,此格式就可以继续使用。This format will continue to work when you use MSAL.

  • <scheme> 必须注册到应用的 Info.plist 的 CFBundleURLTypes > CFBundleURLSchemes 下。<scheme> must be registered in your app's Info.plist under CFBundleURLTypes > CFBundleURLSchemes. 在此示例中,Info.plist 已作为源代码打开:In this example, Info.plist has been opened as source code:

    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>msauth.[BUNDLE_ID]</string>
            </array>
        </dict>
    </array>
    

MSAL 会验证重定向 URI 是否已正确注册,否则会返回错误。MSAL will verify if your redirect URI registers correctly, and return an error if it's not.

  • 若要将通用链接用作重定向 URI,<scheme> 必须为 https,不需在 CFBundleURLSchemes 中声明。If you want to use universal links as a redirect URI, the <scheme> must be https and doesn't need to be declared in CFBundleURLSchemes. 只需在通过通用链接打开应用程序后,按照开发人员的通用链接中 Apple 的说明配置应用和域,然后调用 MSALPublicClientApplicationhandleMSALResponse:sourceApplication: 方法即可。Instead, configure the app and domain per Apple's instructions at Universal Links for Developers and call the handleMSALResponse:sourceApplication: method of MSALPublicClientApplication when your application is opened through a universal link.

使用自定义重定向 URIUse a custom redirect URI

若要使用自定义重定向 URI,请在初始化对象时,将 redirectUri 参数传递给 MSALPublicClientApplicationConfig,将该对象传递给 MSALPublicClientApplicationTo use a custom redirect URI, pass the redirectUri parameter to MSALPublicClientApplicationConfig and pass that object to MSALPublicClientApplication when you initialize the object. 如果重定向 URI 无效,初始化表达式会返回 nil,并根据其他信息来设置 redirectURIErrorIf the redirect URI is invalid, the initializer will return nil and set the redirectURIErrorwith additional information. 例如:For example:

Objective-C:Objective-C:

MSALPublicClientApplicationConfig *config =
        [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"your-client-id"
                                                        redirectUri:@"your-redirect-uri"
                                                        authority:authority];
NSError *redirectURIError;
MSALPublicClientApplication *application =
        [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&redirectURIError];

Swift:Swift:

let config = MSALPublicClientApplicationConfig(clientId: "your-client-id",
                                            redirectUri: "your-redirect-uri",
                                              authority: authority)
do {
  let application = try MSALPublicClientApplication(configuration: config)
  // continue on with application          
} catch let error as NSError {
  // handle error here
}       

处理“URL 已打开”事件Handle the URL opened event

应用程序在通过 URL 方案或通用链接收到任何响应时,应调用 MSAL。Your application should call MSAL when it receives any response through URL schemes or universal links. 当应用程序打开后,调用 MSALPublicClientApplicationhandleMSALResponse:sourceApplication: 方法。Call the handleMSALResponse:sourceApplication: method of MSALPublicClientApplication when your application is opened. 下面是自定义方案的一个示例:Here's an example for custom schemes:

Objective-C:Objective-C:

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    return [MSALPublicClientApplication handleMSALResponse:url 
                                         sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
}

Swift:Swift:

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}

后续步骤Next steps

详细了解身份验证流和应用程序方案Learn more about Authentication flows and application scenarios