Одностраничное приложение: получение токена для вызова API

Область применения: арендаторы рабочей силы внешние арендаторы (подробнее)

Шаблон для получения токенов для API с помощью MSAL.js состоит в том, чтобы сначала попытаться выполнить тихий запрос токена с помощью метода acquireTokenSilent. При вызове этого метода библиотека сначала проверяет кэш в хранилище браузера, чтобы узнать, существует ли маркер доступа без истечения срока действия и возвращает его. Если маркер доступа не найден или срок действия маркера доступа истек, он пытается использовать его маркер обновления для получения нового маркера доступа. Если срок действия токена обновления 24 часа также истек, MSAL.js открывает невидимый iframe для автоматического запроса нового кода авторизации с использованием существующего активного сеанса с Microsoft Entra ID (если таковой имеется), который затем будет обменен на новый набор токенов (токены доступа и обновления).

Дополнительные сведения о сеансе единого входа и значениях времени существования токена в идентификаторе Microsoft Entra см. в разделе "Время существования токенов". Дополнительные сведения о политике поиска кэша MSAL.js см. в разделе "Получение токена доступа".

Запросы "тихого" маркера к идентификатору Microsoft Entra ID могут завершиться ошибкой по таким причинам, как изменение пароля или обновленные политики условного доступа. Чаще всего сбои связаны с тем, что истек 24-часовой срок существования маркера обновления и браузер блокирует сторонние файлы cookie, что предотвращает использование скрытых окон iframe для продолжения проверки подлинности пользователя. В этих случаях следует вызвать один из интерактивных методов, который может запросить у пользователя токены.

• Всплывающее окно, используя acquireTokenPopup.
• Перенаправление, используя acquireTokenRedirect.

Выберите между всплывающим окном или перенаправлением

Выбор между методами всплывающего окна и перенаправления зависит от логики работы приложения:

• Если вы не хотите, чтобы пользователи переходили со страницы основного приложения во время проверки подлинности, рекомендуем использовать метод всплывающего окна. Так как перенаправление проверки подлинности происходит во всплывающем окне, состояние основного приложения сохраняется.
• Если у пользователей есть ограничения браузера или политики, где отключены всплывающие окна, можно использовать метод перенаправления. Используйте метод перенаправления в браузере Internet Explorer, так как существуют известные проблемы со всплывающими окнами в Internet Explorer.

Можно задать области API, которые должен включать токен доступа при создании запроса токена доступа. Не все запрошенные области могут быть включены в маркер доступа. Это зависит от согласия пользователя.

Получение токена с помощью всплывающего окна

Реагировать

Следующий код объединяет ранее описанный шаблон с методами для всплывающего окна:

import {
  InteractionRequiredAuthError,
  InteractionStatus,
} from "@azure/msal-browser";
import { AuthenticatedTemplate, useMsal } from "@azure/msal-react";

function ProtectedComponent() {
  const { instance, inProgress, accounts } = useMsal();
  const [apiData, setApiData] = useState(null);

  useEffect(() => {
    if (!apiData && inProgress === InteractionStatus.None) {
      const accessTokenRequest = {
        scopes: ["user.read"],
        account: accounts[0],
      };
      instance
        .acquireTokenSilent(accessTokenRequest)
        .then((accessTokenResponse) => {
          // Acquire token silent success
          let accessToken = accessTokenResponse.accessToken;
          // Call your API with token
          callApi(accessToken).then((response) => {
            setApiData(response);
          });
        })
        .catch((error) => {
          if (error instanceof InteractionRequiredAuthError) {
            instance
              .acquireTokenPopup(accessTokenRequest)
              .then(function (accessTokenResponse) {
                // Acquire token interactive success
                let accessToken = accessTokenResponse.accessToken;
                // Call your API with token
                callApi(accessToken).then((response) => {
                  setApiData(response);
                });
              })
              .catch(function (error) {
                // Acquire token interactive failure
                console.log(error);
              });
          }
          console.log(error);
        });
    }
  }, [instance, accounts, inProgress, apiData]);

  return <p>Return your protected content here: {apiData}</p>;
}

function App() {
  return (
    <AuthenticatedTemplate>
      <ProtectedComponent />
    </AuthenticatedTemplate>
  );
}

В качестве альтернативы, если вам необходимо получить маркер вне компонента React, вы можете вызвать acquireTokenSilent, но не должны возвращаться к взаимодействию в случае сбоя. Все взаимодействие в дереве компонентов должно происходить ниже компонента MsalProvider.

// MSAL.js v2 exposes several account APIs, logic to determine which account to use is the responsibility of the developer
const account = publicClientApplication.getAllAccounts()[0];

const accessTokenRequest = {
  scopes: ["user.read"],
  account: account,
};

// Use the same publicClientApplication instance provided to MsalProvider
publicClientApplication
  .acquireTokenSilent(accessTokenRequest)
  .then(function (accessTokenResponse) {
    // Acquire token silent success
    let accessToken = accessTokenResponse.accessToken;
    // Call your API with token
    callApi(accessToken);
  })
  .catch(function (error) {
    //Acquire token silent failure
    console.log(error);
  });

JavaScript (MSAL.js)

Следующий код объединяет ранее описанный шаблон с методами для всплывающего окна:

// MSAL.js v2 exposes several account APIs, logic to determine which account to use is the responsibility of the developer
const account = publicClientApplication.getAllAccounts()[0];

const accessTokenRequest = {
  scopes: ["user.read"],
  account: account,
};

publicClientApplication
  .acquireTokenSilent(accessTokenRequest)
  .then(function (accessTokenResponse) {
    // Acquire token silent success
    let accessToken = accessTokenResponse.accessToken;
    // Call your API with token
    callApi(accessToken);
  })
  .catch(function (error) {
    //Acquire token silent failure, and send an interactive request
    if (error instanceof InteractionRequiredAuthError) {
      publicClientApplication
        .acquireTokenPopup(accessTokenRequest)
        .then(function (accessTokenResponse) {
          // Acquire token interactive success
          let accessToken = accessTokenResponse.accessToken;
          // Call your API with token
          callApi(accessToken);
        })
        .catch(function (error) {
          // Acquire token interactive failure
          console.log(error);
        });
    }
    console.log(error);
  });

Angular (MSAL.js)

Программа-оболочка MSAL Angular предоставляет HTTP-перехватчик, который автоматически и незаметно получает токены доступа и прикрепляет их к HTTP-запросам к API.

Области для API-интерфейсов можно указать в параметре конфигурации protectedResourceMap. MsalInterceptor запрашивает указанные сферы при автоматическом получении токенов.

// In app.module.ts
import { PublicClientApplication, InteractionType } from "@azure/msal-browser";
import { MsalInterceptor, MsalModule } from "@azure/msal-angular";

@NgModule({
  declarations: [
    // ...
  ],
  imports: [
    // ...
    MsalModule.forRoot(
      new PublicClientApplication({
        auth: {
          clientId: "Enter_the_Application_Id_Here",
        },
        cache: {
          cacheLocation: "localStorage",
          storeAuthStateInCookie: isIE,
        },
      }),
      {
        interactionType: InteractionType.Popup,
        authRequest: {
          scopes: ["user.read"],
        },
      },
      {
        interactionType: InteractionType.Popup,
        protectedResourceMap: new Map([
          ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
        ]),
      }
    ),
  ],
  providers: [
    {
      provide: HTTP_INTERCEPTORS,
      useClass: MsalInterceptor,
      multi: true,
    },
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

Для успешного или неудачного получения токена в фоновом режиме MSAL Angular предоставляет события, на которые вы можете подписаться. Важно также помнить об отмене подписки.

import { MsalBroadcastService } from '@azure/msal-angular';
import { EventMessage, EventType } from '@azure/msal-browser';

import { filter, Subject, takeUntil } from 'rxjs';

// In app.component.ts
export class AppComponent implements OnInit {
  private readonly _destroying$ = new Subject<void>();

  constructor(private broadcastService: MsalBroadcastService) { }

  ngOnInit() {
    this.broadcastService.msalSubject$
    .pipe(
      filter((msg: EventMessage) => msg.eventType === EventType.ACQUIRE_TOKEN_SUCCESS),
      takeUntil(this._destroying$)
    )
    .subscribe((result: EventMessage) => {
      // Do something with event payload here
    });
  }

  ngOnDestroy(): void {
    this._destroying$.next(undefined);
    this._destroying$.complete();
  }
}

Кроме того, можно явно получить токены с помощью методов получения токена, как это описано в основной библиотеке MSAL.js.

Получение токена с помощью перенаправления

Реагировать

Если в acquireTokenSilent происходит сбой, вернитесь к acquireTokenRedirect. Этот метод инициирует перенаправление на весь экран, а ответ будет обрабатываться при возврате к приложению. Когда этот компонент отображается после возврата из перенаправления, acquireTokenSilent теперь должен быть выполнен успешно, поскольку токены будут извлечены из кэша.

import {
  InteractionRequiredAuthError,
  InteractionStatus,
} from "@azure/msal-browser";
import { AuthenticatedTemplate, useMsal } from "@azure/msal-react";

function ProtectedComponent() {
  const { instance, inProgress, accounts } = useMsal();
  const [apiData, setApiData] = useState(null);

  useEffect(() => {
    const accessTokenRequest = {
      scopes: ["user.read"],
      account: accounts[0],
    };
    if (!apiData && inProgress === InteractionStatus.None) {
      instance
        .acquireTokenSilent(accessTokenRequest)
        .then((accessTokenResponse) => {
          // Acquire token silent success
          let accessToken = accessTokenResponse.accessToken;
          // Call your API with token
          callApi(accessToken).then((response) => {
            setApiData(response);
          });
        })
        .catch((error) => {
          if (error instanceof InteractionRequiredAuthError) {
            instance.acquireTokenRedirect(accessTokenRequest);
          }
          console.log(error);
        });
    }
  }, [instance, accounts, inProgress, apiData]);

  return <p>Return your protected content here: {apiData}</p>;
}

function App() {
  return (
    <AuthenticatedTemplate>
      <ProtectedComponent />
    </AuthenticatedTemplate>
  );
}

В качестве альтернативы, если вам необходимо получить маркер вне компонента React, вы можете вызвать acquireTokenSilent, но не должны возвращаться к взаимодействию в случае сбоя. Все взаимодействие в дереве компонентов должно происходить ниже компонента MsalProvider.

// MSAL.js v2 exposes several account APIs, logic to determine which account to use is the responsibility of the developer
const account = publicClientApplication.getAllAccounts()[0];

const accessTokenRequest = {
  scopes: ["user.read"],
  account: account,
};

// Use the same publicClientApplication instance provided to MsalProvider
publicClientApplication
  .acquireTokenSilent(accessTokenRequest)
  .then(function (accessTokenResponse) {
    // Acquire token silent success
    let accessToken = accessTokenResponse.accessToken;
    // Call your API with token
    callApi(accessToken);
  })
  .catch(function (error) {
    //Acquire token silent failure
    console.log(error);
  });

JavaScript (MSAL.js)

Следующий шаблон подобен описанному ранее, но показан с помощью метода перенаправления для получения маркеров в интерактивном режиме. Вам нужно вызвать и ожидать handleRedirectPromise при загрузке страницы.

const redirectResponse = await publicClientApplication.handleRedirectPromise();
if (redirectResponse !== null) {
  // Acquire token silent success
  let accessToken = redirectResponse.accessToken;
  // Call your API with token
  callApi(accessToken);
} else {
  // MSAL.js v2 exposes several account APIs, logic to determine which account to use is the responsibility of the developer
  const account = publicClientApplication.getAllAccounts()[0];

  const accessTokenRequest = {
    scopes: ["user.read"],
    account: account,
  };

  publicClientApplication
    .acquireTokenSilent(accessTokenRequest)
    .then(function (accessTokenResponse) {
      // Acquire token silent success
      // Call API with token
      let accessToken = accessTokenResponse.accessToken;
      // Call your API with token
      callApi(accessToken);
    })
    .catch(function (error) {
      //Acquire token silent failure, and send an interactive request
      console.log(error);
      if (error instanceof InteractionRequiredAuthError) {
        publicClientApplication.acquireTokenRedirect(accessTokenRequest);
      }
    });
}

Запрос необязательных требований

Необязательные утверждения можно использовать в следующих целях:

• Включите дополнительные утверждения в токены для вашего приложения.
• Измените поведение определенных утверждений, которые возвращает система Microsoft Entra ID в токенах.
• Добавлять и использовать произвольные утверждения в вашем приложении.

Чтобы запросить необязательные утверждения в IdToken, можно отправить объект утверждений в строковом формате в поле claimsRequest класса AuthenticationParameters.ts.

var claims = {
  optionalClaims: {
    idToken: [
      {
        name: "auth_time",
        essential: true,
      },
    ],
  },
};

var request = {
  scopes: ["user.read"],
  claimsRequest: JSON.stringify(claims),
};

myMSALObj.acquireTokenPopup(request);

Дополнительные сведения см. в статье о необязательных утверждениях.

Angular (MSAL.js)

Этот код аналогичен описанному ранее, за исключением того, что мы рекомендуем инициализировать MsalRedirectComponent для обработки перенаправлений. Конфигурации MsalInterceptor также можно изменить для использования переадресации.

// In app.module.ts
import { PublicClientApplication, InteractionType } from "@azure/msal-browser";
import {
  MsalInterceptor,
  MsalModule,
  MsalRedirectComponent,
} from "@azure/msal-angular";

@NgModule({
  declarations: [
    // ...
  ],
  imports: [
    // ...
    MsalModule.forRoot(
      new PublicClientApplication({
        auth: {
          clientId: "Enter_the_Application_Id_Here",
        },
        cache: {
          cacheLocation: "localStorage",
          storeAuthStateInCookie: isIE,
        },
      }),
      {
        interactionType: InteractionType.Redirect,
        authRequest: {
          scopes: ["user.read"],
        },
      },
      {
        interactionType: InteractionType.Redirect,
        protectedResourceMap: new Map([
          ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
        ]),
      }
    ),
  ],
  providers: [
    {
      provide: HTTP_INTERCEPTORS,
      useClass: MsalInterceptor,
      multi: true,
    },
  ],
  bootstrap: [AppComponent, MsalRedirectComponent],
})
export class AppModule {}

Следующий шаг

• Вызов веб-API.