Inicializar aplicativos cliente usando o MSAL. jsInitialize client applications using MSAL.js

Este artigo descreve como inicializar a biblioteca de autenticação da Microsoft para JavaScript (MSAL. js) com uma instância de um aplicativo de agente do usuário.This article describes initializing Microsoft Authentication Library for JavaScript (MSAL.js) with an instance of a user-agent application. O aplicativo de agente de usuário é uma forma de aplicativo cliente público em que o código do cliente é executado em um agente de usuário, como um navegador da Web.The user-agent application is a form of public client application in which the client code is executed in a user-agent such as a web browser. Esses clientes não armazenam segredos, pois o contexto do navegador está aberto de acessível.These clients do not store secrets, since the browser context is openly accessible. Para saber mais sobre os tipos de aplicativo cliente e as opções de configuração de aplicativo, leia a visão geral.To learn more about the client application types and application configuration options, read the overview.

Pré-requisitosPrerequisites

Antes de inicializar um aplicativo, primeiro você precisa registrá-lo com o portal do Azure para que seu aplicativo possa ser integrado à plataforma Microsoft Identity.Before initializing an application, you first need to register it with the Azure portal so that your app can be integrated with the Microsoft identity platform. Após o registro, talvez você precise das seguintes informações (que podem ser encontradas no portal do Azure):After registration, you may need the following information (which can be found in the Azure portal):

  • A ID do cliente (uma cadeia de caracteres que representa um GUID para seu aplicativo)The client ID (a string representing a GUID for your application)
  • A URL do provedor de identidade (chamada de instância) e o público-alvo de entrada para seu aplicativo.The identity provider URL (named the instance) and the sign-in audience for your application. Esses dois parâmetros são coletivamente conhecidos como autoridade.These two parameters are collectively known as the authority.
  • A ID do locatário se você estiver escrevendo um aplicativo de linha de negócios somente para sua organização (também chamado de aplicativo de locatário único).The tenant ID if you are writing a line-of-business application solely for your organization (also named single-tenant application).
  • Para aplicativos Web, você também precisará definir o redirectUri onde o provedor de identidade retornará ao seu aplicativo com os tokens de segurança.For web apps, you'll have to also set the redirectUri where the identity provider will return to your application with the security tokens.

Inicializando aplicativosInitializing applications

Você pode usar MSAL. js da seguinte maneira em um aplicativo JavaScript/typescript simples.You can use MSAL.js as follows in a plain JavaScript/Typescript application. Inicialize o contexto de autenticação MSAL instanciando UserAgentApplication com um objeto de configuração.Initialize MSAL authentication context by instantiating UserAgentApplication with a configuration object. A configuração mínima necessária para inicializar o MSAL. js é o clientID do seu aplicativo que você deve obter do portal de registro de aplicativos.The minimum required config to initialize MSAL.js is the clientID of your application which you should get from the application registration portal.

Para métodos de autenticação com fluxos deloginRedirect redirecionamento (e acquireTokenRedirect), você precisará registrar explicitamente um retorno de chamada handleRedirectCallback() para êxito ou erro por meio do método.For authentication methods with redirect flows (loginRedirect and acquireTokenRedirect), you will need to explicitly register a callback for success or error through handleRedirectCallback() method. Isso é necessário, já que fluxos de redirecionamento não retornam promessas, pois os métodos com uma experiência de pop-up fazem.This is needed since redirect flows do not return promises as the methods with a pop-up experience do.

// Configuration object constructed
const config = {
    auth: {
        clientId: “abcd-ef12-gh34-ikkl-ashdjhlhsdg”
    }
}

// create UserAgentApplication instance
const myMSALObj = new UserAgentApplication(config);

function authCallback(error, response) {
    //handle redirect response
}

// (optional when using redirect methods) register redirect call back for Success or Error
myMSALObj.handleRedirectCallback(authCallback);

O UserAgentApplication MSAL. js foi projetado para ter uma única instância e configuração do para representar um único contexto de autenticação.MSAL.js is designed to have a single instance and configuration of the UserAgentApplication to represent a single authentication context. Várias instâncias não são recomendadas, pois causam entradas e comportamento de cache conflitantes no navegador.Multiple instances are not recommended as they cause conflicting cache entries and behavior in the browser.

Opções de configuraçãoConfiguration options

MSAL. js tem um objeto de configuração mostrado abaixo que fornece um agrupamento de opções configuráveis disponíveis para a criação UserAgentApplicationde uma instância do.MSAL.js has a configuration object shown below that provides a grouping of configurable options available for creating an instance of UserAgentApplication.

type storage = "localStorage" | "sessionStorage";

// Protocol Support
export type AuthOptions = {
    clientId: string;
    authority?: string;
    validateAuthority?: boolean;
    redirectUri?: string | (() => string);
    postLogoutRedirectUri?: string | (() => string);
    navigateToLoginRequestUrl?: boolean;
};

// Cache Support
export type CacheOptions = {
    cacheLocation?: CacheLocation;
    storeAuthStateInCookie?: boolean;
};

// Library support
export type SystemOptions = {
    logger?: Logger;
    loadFrameTimeout?: number;
    tokenRenewalOffsetSeconds?: number;
};

// Developer App Environment Support
export type FrameworkOptions = {
    isAngular?: boolean;
    unprotectedResources?: Array<string>;
    protectedResourceMap?: Map<string, Array<string>>;
};

// Configuration Object
export type Configuration = {
    auth: AuthOptions,
    cache?: CacheOptions,
    system?: SystemOptions,
    framework?: FrameworkOptions
};

Veja abaixo o conjunto total de opções configuráveis que têm suporte no momento no objeto de configuração:Below is the total set of configurable options that are supported currently in the config object:

  • clientID: Obrigatório.clientID: Required. O clientID do seu aplicativo, você deve obtê-lo no portal de registro de aplicativos.The clientID of your application, you should get this from the application registration portal.

  • autoridade: Opcional.authority: Optional. Uma URL que indica um diretório do qual MSAL pode solicitar tokens.A URL indicating a directory that MSAL can request tokens from. O valor padrão é: https://login.microsoftonline.com/common.Default value is: https://login.microsoftonline.com/common.

    • No Azure ad<, ele é do formato público>/>da instância<https://, em <que> Instance é o domínio do provedor de identidade ( https://login.microsoftonline.compor exemplo,) e o público-alvo> é um identificador que representa o público-alvo. <In Azure AD, it is of the form https://<instance>/<audience>, where <instance> is the identity provider domain (for example, https://login.microsoftonline.com) and <audience> is an identifier representing the sign-in audience. Esses valores podem ser os seguintes:This can be the following values:
      • https://login.microsoftonline.com/<tenant>-o locatário é um domínio associado ao locatário, como contoso.onmicrosoft.com, ou o GUID que representa a TenantID Propriedade do diretório usado somente para conectar usuários de uma organização específica.https://login.microsoftonline.com/<tenant>- tenant is a domain associated to the tenant, such as contoso.onmicrosoft.com, or the GUID representing the TenantID property of the directory used only to sign in users of a specific organization.
      • https://login.microsoftonline.com/common-Usado para conectar usuários com contas corporativas e de estudante ou uma conta pessoal da Microsoft.https://login.microsoftonline.com/common- Used to sign in users with work and school accounts or a Microsoft personal account.
      • https://login.microsoftonline.com/organizations/-Usado para conectar usuários com contas corporativas e de estudante.https://login.microsoftonline.com/organizations/- Used to sign in users with work and school accounts.
      • https://login.microsoftonline.com/consumers/-Usado para conectar usuários com apenas conta Microsoft pessoais (ao vivo).https://login.microsoftonline.com/consumers/ - Used to sign in users with only personal Microsoft account (live).
    • Em Azure ad B2C, é o formato https://<instance>/tfp/<tenant>/<policyName>/, em que Instance é o domínio Azure ad B2C, locatário é o nome do locatário Azure ad B2C, PolicyName é o nome da política B2C a ser aplicada.In Azure AD B2C, it is of the form https://<instance>/tfp/<tenant>/<policyName>/, where instance is the Azure AD B2C domain, tenant is the name of the Azure AD B2C tenant, policyName is the name of the B2C policy to apply.
  • validateAuthority: Opcional.validateAuthority: Optional. Valide o emissor de tokens.Validate the issuer of tokens. O padrão é true.Default is true. Para aplicativos B2C, como o valor de autoridade é conhecido e pode ser diferente por política, a validação de autoridade não funcionará e precisará ser falsedefinida como.For B2C applications, since the authority value is known and can be different per policy, the authority validation will not work and has to be set to false.

  • redirectUri: Opcional.redirectUri: Optional. O URI de redirecionamento do seu aplicativo, onde as respostas de autenticação podem ser enviadas e recebidas pelo aplicativo.The redirect URI of your app, where authentication responses can be sent and received by your app. Ele deve corresponder exatamente a um dos URIs de redirecionamento que você registrou no Portal.It must exactly match one of the redirect URIs you registered in the portal. Assume o padrão de window.location.href.Defaults to window.location.href.

  • postLogoutRedirectUri: Opcional.postLogoutRedirectUri: Optional. Redireciona o usuário para postLogoutRedirectUri depois de sair. O padrão é redirectUri.Redirects the user to postLogoutRedirectUri after sign out. The default is redirectUri.

  • navigateToLoginRequestUrl: Opcional.navigateToLoginRequestUrl: Optional. Capacidade de desativar a navegação padrão na página inicial após o logon.Ability to turn off default navigation to start page after login. O padrão é true.Default is true. Isso é usado somente para fluxos de redirecionamento.This is used only for redirect flows.

  • cacheLocation: Opcional.cacheLocation: Optional. Define o localStorage armazenamento do navegador como sessionStorageou.Sets browser storage to either localStorage or sessionStorage. O padrão é sessionStorage.The default is sessionStorage.

  • storeAuthStateInCookie: Opcional.storeAuthStateInCookie: Optional. Esse sinalizador foi introduzido no MSAL. js v 0.2.2 como uma correção para os problemas de loop de autenticação no Microsoft Internet Explorer e no Microsoft Edge.This flag was introduced in MSAL.js v0.2.2 as a fix for the authentication loop issues on Microsoft Internet Explorer and Microsoft Edge. Habilite o storeAuthStateInCookie sinalizador como true para tirar proveito dessa correção.Enable the flag storeAuthStateInCookie to true to take advantage of this fix. Quando habilitado, o MSAL. js armazenará o estado de solicitação de autenticação necessário para a validação dos fluxos de autenticação nos cookies do navegador.When this is enabled, MSAL.js will store the auth request state required for validation of the auth flows in the browser cookies. Por padrão, esse sinalizador é definido falsecomo.By default this flag is set to false.

  • logger: Opcional.logger: Optional. Um objeto de agente com uma instância de retorno de chamada que pode ser fornecida pelo desenvolvedor para consumir e publicar logs de maneira personalizada.A Logger object with a callback instance that can be provided by the developer to consume and publish logs in a custom manner. Para obter detalhes sobre como passar o objeto do agente, consulte registrando em log com MSAL. js.For details on passing logger object, see logging with msal.js.

  • loadFrameTimeout: Opcional.loadFrameTimeout: Optional. O número de milissegundos de inatividade antes de uma resposta de renovação de token do Azure AD deve ser considerado com tempo limite. O padrão é 6 segundos.The number of milliseconds of inactivity before a token renewal response from Azure AD should be considered timed out. Default is 6 seconds.

  • tokenRenewalOffsetSeconds: Opcional.tokenRenewalOffsetSeconds: Optional. O número de milissegundos que define a janela de deslocamento necessária para renovar o token antes da expiração.The number of milliseconds which sets the window of offset needed to renew the token before expiry. O padrão é 300 milissegundos.Default is 300 milliseconds.

Eles só se aplicam a serem passados da biblioteca de invólucro angular do MSAL:These are only applicable to be passed down from the MSAL Angular wrapper library:

  • unprotectedResources: Opcional.unprotectedResources: Optional. Matriz de URIs que são recursos desprotegidos.Array of URIs that are unprotected resources. MSAL não anexará um token às solicitações de saída que têm esse URI.MSAL will not attach a token to outgoing requests that have these URI. Assume o padrão de null.Defaults to null.

  • protectedResourceMap: Opcional.protectedResourceMap: Optional. Esse é o mapeamento de recursos para escopos usados pelo MSAL para anexar automaticamente tokens de acesso em chamadas à API Web.This is mapping of resources to scopes used by MSAL for automatically attaching access tokens in web API calls. Um único token de acesso é obtido para o recurso.A single access token is obtained for the resource. Portanto, você pode mapear um caminho de recurso específico da seguinte "https://graph.microsoft.com/v1.0/me" maneira: {"", ["User. Read"]} ou a URL do aplicativo do recurso como "https://graph.microsoft.com/" : {"", ["User. Read", "mail. Send"]}.So you can map a specific resource path as follows: {"https://graph.microsoft.com/v1.0/me", ["user.read"]}, or the app URL of the resource as: {"https://graph.microsoft.com/", ["user.read", "mail.send"]}. Isso é necessário para chamadas de CORS.This is required for CORS calls. Assume o padrão de null.Defaults to null.