Inicio rápido: Creación y administración de tokens de acceso

Los tokens de acceso de SDK de Azure Communication Services se autentican directamente en Azure Communication Services como una identidad determinada. Deberá crear tokens de acceso si desea que los usuarios se unan a una llamada o un subproceso de chat dentro de la aplicación.

En este inicio rápido, aprenderá a usar los SDK de Azure Communication Services para crear identidades y administrar los tokens de acceso. Para los casos de uso de producción, se recomienda generar tokens de acceso en un servicio del lado servidor.

Requisitos previos

Instalación

Adición de la extensión

Agregue la extensión Azure Communication Services para la CLI de Azure mediante el comando az extension.

az extension add --name communication

Inicio de sesión en la CLI de Azure

Deberá iniciar sesión en la CLI de Azure. Para iniciar sesión, ejecute el comando az login desde el terminal y proporcione sus credenciales.

(Opcional) Uso de operaciones de identidad de la CLI de Azure sin pasar una cadena de conexión

Puede configurar la variable de entorno AZURE_COMMUNICATION_CONNECTION_STRING para usar operaciones de identidad de la CLI de Azure sin tener que usar --connection_string para pasar la cadena de conexión. Para configurar una variable de entorno, abra una ventana de consola y seleccione el sistema operativo en las pestañas siguientes. Reemplace <yourConnectionString> por la cadena de conexión real.

Abra una ventana de consola y escriba el siguiente comando:

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Después de agregar la variable de entorno, puede que tenga que reiniciar todos los programas en ejecución que necesiten leer la variable de entorno, incluida la ventana de consola. Por ejemplo, si usa Visual Studio como editor, reinícielo antes de ejecutar el ejemplo.

Almacenamiento del token de acceso en una variable de entorno

Para configurar una variable de entorno, abra una ventana de consola y seleccione el sistema operativo en las pestañas siguientes. Reemplace <yourAccessToken> con su token de acceso real.

Abra una ventana de consola y escriba el siguiente comando:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Después de agregar la variable de entorno, puede que tenga que reiniciar todos los programas en ejecución que necesiten leer la variable de entorno, incluida la ventana de consola. Por ejemplo, si usa Visual Studio como editor, reinícielo antes de ejecutar el ejemplo.

Operaciones

Creación de una identidad

Para crear tokens de acceso, necesita una identidad. Azure Communication Services mantiene un directorio de identidad ligero para este propósito. Use el comando user create para crear una nueva entrada en el directorio con un Id único. La identidad es necesaria más adelante para emitir tokens de acceso.

az communication identity user create --connection-string "<yourConnectionString>"
  • Reemplace <yourConnectionString> por la cadena de conexión.

Creación de una identidad y emisión de un token de acceso en la misma solicitud

Ejecute el siguiente comando para crear una identidad de Communication Services y, a la vez, emitir un token de acceso para ella. El parámetro scopes define un conjunto de roles y permisos de token de acceso. Para obtener más información, vea la lista de acciones admitidas en Autenticación para Azure Communication Services.

az communication identity token issue --scope chat --connection-string "<yourConnectionString>"

Realice este reemplazo en el código:

  • Reemplace <yourConnectionString> por la cadena de conexión.

Emitir tokens de acceso

Ejecute el siguiente comando para emitir un token de acceso para la identidad de Communication Services. El parámetro scopes define un conjunto de roles y permisos de token de acceso. Para obtener más información, vea la lista de acciones admitidas en Autenticación para Azure Communication Services.

az communication identity token issue --scope chat --user "<userId>" --connection-string "<yourConnectionString>"

Realice este reemplazo en el código:

  • Reemplace <yourConnectionString> por la cadena de conexión.
  • Reemplace <userId> por su userId.

Los tokens de acceso son credenciales de corta duración que deben volver a emitirse. Si no lo hace, podría provocar una interrupción de la experiencia de los usuarios de la aplicación. La propiedad de respuesta expires_on indica la duración del token de acceso.

Emisión del token de acceso con varios ámbitos

Ejecute el siguiente comando para emitir un token de acceso con varios ámbitos para la identidad de Communication Services. El parámetro scopes define un conjunto de roles y permisos de token de acceso. Para obtener más información, consulte la lista de acciones admitidas en el modelo de identidad.

az communication identity token issue --scope chat voip --user "<userId>" --connection-string "<yourConnectionString>"

Realice este reemplazo en el código:

  • Reemplace <yourConnectionString> por la cadena de conexión.
  • Reemplace <userId> por su userId.

Los tokens de acceso son credenciales de corta duración que deben volver a emitirse. Si no lo hace, podría provocar una interrupción de la experiencia de los usuarios de la aplicación. La propiedad de respuesta expires_on indica la duración del token de acceso.

Intercambio de un token de acceso de Azure AD del usuario de Teams por un token de acceso de Communication Identity

Use el comando token get-for-teams-user para emitir un token de acceso para el usuario de Teams que se puede usar con los SDK de Azure Communication Services.

az communication identity token get-for-teams-user --aad-token "<yourAadToken>" --client "<yourAadApplication>" --aad-user "<yourAadUser>" --connection-string "<yourConnectionString>"

Realice este reemplazo en el código:

  • Reemplace <yourConnectionString> por la cadena de conexión.
  • Reemplace <yourAadUser> por el id. de usuario de Azure Active Directory.
  • Reemplace <yourAadApplication> por el id. de la aplicación de Azure Active Directory.
  • Reemplace <yourAadToken> por el token de acceso de Azure Active Directory.

Revocación de los tokens de acceso

En ocasiones, es posible que tenga que revocar explícitamente un token de acceso. Por ejemplo, lo haría cuando los usuarios de la aplicación cambien la contraseña que usan para autenticarse en el servicio. El comando token revoke invalida todos los tokens de acceso activos emitidos para la identidad.

az communication identity token revoke --user "<userId>" --connection-string "<yourConnectionString>"

Realice este reemplazo en el código:

  • Reemplace <yourConnectionString> por la cadena de conexión.
  • Reemplace <userId> por su userId.

Eliminación de una identidad

Cuando se elimina una identidad, se revocan todos los tokens de acceso activos y se impide la emisión adicional de tokens de acceso para la identidad. También quita todo el contenido conservado asociado a la identidad.

az communication identity user delete --user "<userId>" --connection-string "<yourConnectionString>"

Realice este reemplazo en el código:

  • Reemplace <yourConnectionString> por la cadena de conexión.
  • Reemplace <userId> por su userId.

Requisitos previos

Código final

Busque el código finalizado de este inicio rápido en GitHub.

Configurar el entorno

Creación de una aplicación de C#

En una ventana del símbolo del sistema, como cmd, PowerShell o Bash, ejecute el comando dotnet new para crear una nueva aplicación de consola con el nombre AccessTokensQuickstart. Este comando crea un sencillo proyecto de C#, "Hola mundo", con un solo archivo de origen: program.cs.

dotnet new console -o AccessTokensQuickstart

Cambie el directorio a la carpeta de la aplicación recién creada y use el comando dotnet build para compilar la aplicación.

cd AccessTokensQuickstart
dotnet build

Se debe mostrar una salida simple"Hola mundo". Si es así, la instalación funciona correctamente y puede empezar a escribir el código Azure Communication Services específico.

Instalar el paquete

En el directorio de aplicaciones, instale el paquete de la biblioteca de identidades de Azure Communication Services para .NET usando el comando dotnet add package.

dotnet add package Azure.Communication.Identity --version 1.0.0

Instalación del marco de la aplicación

En el directorio del proyecto, haga lo siguiente:

  1. Abra el archivo Program.cs en un editor de texto.
  2. Agregue una directiva using para incluir el espacio de nombres Azure.Communication.Identity.
  3. Actualice la declaración del método Main para admitir código asincrónico.

Para comenzar, ejecute el código siguiente:

using System;
using Azure;
using Azure.Core;
using Azure.Communication.Identity;

namespace AccessTokensQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Access Tokens Quickstart");

            // Quickstart code goes here
        }
    }
}

Autenticar el cliente

Inicialice CommunicationIdentityClient con la cadena de conexión. El código siguiente, que se agrega al método Main, recupera la cadena de conexión para el recurso de una variable de entorno denominada COMMUNICATION_SERVICES_CONNECTION_STRING.

Para obtener más información, vea la sección "Almacenar la cadena de conexión" de Creación y administración de recursos de Communication Services.

// This code demonstrates how to retrieve your connection string
// from an environment variable.
string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
var client = new CommunicationIdentityClient(connectionString);

Como alternativa, puede separar el punto de conexión y la clave de acceso mediante la ejecución del código siguiente:

// This code demonstrates how to fetch your endpoint and access key
// from an environment variable.
string endpoint = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_ENDPOINT");
string accessKey = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_ACCESSKEY");
var client = new CommunicationIdentityClient(new Uri(endpoint), new AzureKeyCredential(accessKey));

Si ya ha configurado una aplicación Azure Active Directory (Azure AD), puede autenticarse mediante Azure AD.

TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(new Uri(endpoint), tokenCredential);

Creación de una identidad

Para crear tokens de acceso, necesita una identidad. Azure Communication Services mantiene un directorio de identidad ligero para este propósito. Use el método createUser para crear una nueva entrada en el directorio con un Id único. La identidad es necesaria más adelante para emitir tokens de acceso.

var identityResponse = await client.CreateUserAsync();
var identity = identityResponse.Value;
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");

Almacene la identidad recibida con la asignación a los usuarios de la aplicación (por ejemplo, almacenándola en la base de datos del servidor de aplicaciones).

Emitir tokens de acceso

Después de tener una identidad de Communication Services, use el método GetToken para emitir un token de acceso para ella. El parámetro scopes define un conjunto de roles y permisos de token de acceso. Para obtener más información, consulte la lista de acciones admitidas en el modelo de identidad. También puede construir una nueva instancia de communicationUser basada en una representación de cadena de una identidad de Azure Communication Service.

// Issue an access token with the "voip" scope for an identity
var tokenResponse = await client.GetTokenAsync(identity, scopes: new [] { CommunicationTokenScope.VoIP });

// Get the token from the response
var token =  tokenResponse.Value.Token;
var expiresOn = tokenResponse.Value.ExpiresOn;

// Write the token details to the screen
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

Los tokens de acceso son credenciales de corta duración que deben volver a emitirse. Si no lo hace, podría provocar una interrupción de la experiencia de los usuarios de la aplicación. La propiedad expiresOn indica la duración del token de acceso.

Creación de una identidad y emisión de un token en la misma solicitud

Use el método CreateUserAndTokenAsync para crear una identidad de Communication Services y, a la vez, emitir un token de acceso para ella. El parámetro scopes define un conjunto de roles y permisos de token de acceso. Para obtener más información, vea la lista de acciones admitidas en Autenticación para Azure Communication Services.

// Issue an identity and an access token with the "voip" scope for the new identity
var identityAndTokenResponse = await client.CreateUserAndTokenAsync(scopes: new[] { CommunicationTokenScope.VoIP });

// Retrieve the identity, token, and expiration date from the response
var identity = identityAndTokenResponse.Value.User;
var token = identityAndTokenResponse.Value.AccessToken.Token;
var expiresOn = identityAndTokenResponse.Value.AccessToken.ExpiresOn;

// Print the details to the screen
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

Tokens de acceso de actualización

Para actualizar un token de acceso, pase una instancia del objeto CommunicationUserIdentifier en GetTokenAsync. Si ha almacenado este Id y necesita crear un objeto CommunicationUserIdentifier, puede hacerlo pasando el Id almacenado al constructor CommunicationUserIdentifier como se indica a continuación:

var identityToRefresh = new CommunicationUserIdentifier(identity.Id);
var tokenResponse = await client.GetTokenAsync(identityToRefresh, scopes: new [] { CommunicationTokenScope.VoIP });

Revocación de los tokens de acceso

En ocasiones, es posible que tenga que revocar explícitamente un token de acceso. Por ejemplo, lo haría cuando los usuarios de la aplicación cambien la contraseña que usan para autenticarse en el servicio. El método RevokeTokensAsync invalida todos los tokens de acceso activos que fueron emitidos para la identidad.

await client.RevokeTokensAsync(identity);
Console.WriteLine($"\nSuccessfully revoked all access tokens for identity with ID: {identity.Id}");

Eliminación de una identidad

Cuando se elimina una identidad, se revocan todos los tokens de acceso activos y se impide la emisión adicional de tokens de acceso para la identidad. También quita todo el contenido conservado asociado a la identidad.

await client.DeleteUserAsync(identity);
Console.WriteLine($"\nDeleted the identity with ID: {identity.Id}");

Ejecución del código

Cuando haya terminado de crear el token de acceso, puede ejecutar la aplicación desde el directorio de la aplicación mediante el comando dotnet run.

dotnet run

La salida de la aplicación describe cada acción completada:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Prerrequisitos

Código final

Busque el código finalizado de este inicio rápido en GitHub.

Configurar el entorno

Creación de una aplicación Node.js

En una a terminal o una ventana del símbolo del sistema, cree un directorio para la aplicación y ábralo.

mkdir access-tokens-quickstart && cd access-tokens-quickstart

Ejecute npm init -y para crear un archivo package.json con la configuración predeterminada.

npm init -y

Instalar el paquete

Use el comando npm install para instalar Identity SDK de Azure Communication Services para JavaScript.

npm install @azure/communication-identity --save

La opción --save muestra la biblioteca como dependencia en el archivo package.json.

Instalación del marco de la aplicación

  1. Cree un archivo denominado issue-access-token.js en el directorio del proyecto y agregue el código siguiente:

    const { CommunicationIdentityClient } = require('@azure/communication-identity');
    
    const main = async () => {
      console.log("Azure Communication Services - Access Tokens Quickstart")
    
      // Quickstart code goes here
    };
    
    main().catch((error) => {
      console.log("Encountered an error");
      console.log(error);
    })
    

Autenticar el cliente

Cree una instancia CommunicationIdentityClient de con la cadena de conexión. El código siguiente, que se agrega al método Main, recupera la cadena de conexión para el recurso de una variable de entorno denominada COMMUNICATION_SERVICES_CONNECTION_STRING.

Para obtener más información, vea la sección "Almacenar la cadena de conexión" de Creación y administración de recursos de Communication Services.

// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];

// Instantiate the identity client
const identityClient = new CommunicationIdentityClient(connectionString);

Como alternativa, puede separar el punto de conexión y la clave de acceso mediante la ejecución del código siguiente:

// This code demonstrates how to fetch your endpoint and access key
// from an environment variable.
const endpoint = process.env["COMMUNICATION_SERVICES_ENDPOINT"];
const accessKey = process.env["COMMUNICATION_SERVICES_ACCESSKEY"];

// Create the credential
const tokenCredential = new AzureKeyCredential(accessKey);

// Instantiate the identity client
const identityClient = new CommunicationIdentityClient(endpoint, tokenCredential)

Si ya ha configurado una aplicación Azure Active Directory (Azure AD), puede autenticarse mediante Azure AD.

const endpoint = process.env["COMMUNICATION_SERVICES_ENDPOINT"];
const tokenCredential = new DefaultAzureCredential();
const identityClient = new CommunicationIdentityClient(endpoint, tokenCredential);

Creación de una identidad

Para crear tokens de acceso, necesita una identidad. Azure Communication Services mantiene un directorio de identidad ligero para este propósito. Use el método createUser para crear una nueva entrada en el directorio con un Id único. La identidad es necesaria más adelante para emitir tokens de acceso.

let identityResponse = await identityClient.createUser();
console.log(`\nCreated an identity with ID: ${identityResponse.communicationUserId}`);

Almacene la identidad recibida con la asignación a los usuarios de la aplicación (por ejemplo, almacenándola en la base de datos del servidor de aplicaciones).

Emitir tokens de acceso

Use el método getToken para emitir un token de acceso para la identidad de Communication Services. El parámetro scopes define un conjunto de roles y permisos de token de acceso. Para obtener más información, consulte la lista de acciones admitidas en el modelo de identidad. También puede construir una nueva instancia de communicationUser basándose en una representación de cadena de la identidad de Azure Communication Service.

// Issue an access token with the "voip" scope for an identity
let tokenResponse = await identityClient.getToken(identityResponse, ["voip"]);

// Get the token and its expiration date from the response
const { token, expiresOn } = tokenResponse;

// Print the expiration date and token to the screen
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

Los tokens de acceso son credenciales de corta duración que deben volver a emitirse. Si no lo hace, podría provocar una interrupción de la experiencia de los usuarios de la aplicación. La propiedad expiresOn indica la duración del token de acceso.

Creación de una identidad y emisión de un token en una llamada de método

Use el método createUserAndToken para crear una identidad de Communication Services y, a la vez, emitir un token de acceso para ella. El parámetro scopes define un conjunto de roles y permisos de token de acceso. De nuevo, se crea con el ámbito voip.

// Issue an identity and an access token with the "voip" scope for the new identity
let identityTokenResponse = await identityClient.createUserAndToken(["voip"]);

// Get the token, its expiration date, and the user from the response
const { token, expiresOn, user } = identityTokenResponse;

// print these details to the screen
console.log(`\nCreated an identity with ID: ${user.communicationUserId}`);
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

Tokens de acceso de actualización

A medida que expiren los tokens, deberá actualizarlos periódicamente. Su actualización es fácil. Simplemente, llame a getToken de nuevo con la misma identidad que se usó para emitir los tokens. También debe proporcionar los scopes de los tokens actualizados.

// Value of identityResponse represents the Azure Communication Services identity stored during identity creation and then used to issue the tokens being refreshed
let refreshedTokenResponse = await identityClient.getToken(identityResponse, ["voip"]);

Revocación de los tokens de acceso

En ocasiones, es posible que tenga que revocar un token de acceso. Por ejemplo, lo haría cuando los usuarios de la aplicación cambien la contraseña que usan para autenticarse en el servicio. El método revokeTokens invalida todos los tokens de acceso activos que fueron emitidos para la identidad.

await identityClient.revokeTokens(identityResponse);

console.log(`\nSuccessfully revoked all access tokens for identity with ID: ${identityResponse.communicationUserId}`);

Eliminación de una identidad

Cuando se elimina una identidad, se revocan todos los tokens de acceso activos y se impide la emisión adicional de tokens de acceso para la identidad. También quita todo el contenido conservado asociado a la identidad.

await identityClient.deleteUser(identityResponse);

console.log(`\nDeleted the identity with ID: ${identityResponse.communicationUserId}`);

Ejecución del código

Desde un símbolo del sistema de la consola, vaya al directorio que contiene el archivoissue-access-token.jsy, a continuación, ejecute el siguiente comando node para ejecutar la aplicación:

node ./issue-access-token.js

La salida de la aplicación describe cada acción completada:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Prerrequisitos

Código final

Busque el código finalizado de este inicio rápido en GitHub.

Configurar el entorno

Creación de una nueva aplicación de Python

  1. En una a terminal o una ventana del símbolo del sistema, cree un directorio para la aplicación y ábralo.

    mkdir access-tokens-quickstart && cd access-tokens-quickstart
    
  2. Use un editor de texto para crear un archivo denominado issue-access-tokens.py en el directorio raíz del proyecto y agregue la estructura del programa, incluido el control de excepciones básico. Agregará todo el código fuente de este inicio rápido a este archivo en las secciones siguientes.

    import os
    from azure.communication.identity import CommunicationIdentityClient, CommunicationUserIdentifier
    
    try:
       print("Azure Communication Services - Access Tokens Quickstart")
       # Quickstart code goes here
    except Exception as ex:
       print("Exception:")
       print(ex)
    

Instalar el paquete

En el directorio de aplicaciones, instale el SDK de identidad de Azure Communication Services para Python con el comando pip install.

pip install azure-communication-identity

Autenticar el cliente

Cree una instancia de un objeto CommunicationIdentityClient con su cadena de conexión. El código siguiente, que se agrega al bloque try, recupera la cadena de conexión para el recurso de una variable de entorno denominada COMMUNICATION_SERVICES_CONNECTION_STRING.

Para obtener más información, vea la sección "Almacenar la cadena de conexión" de Creación y administración de recursos de Communication Services.

# This code demonstrates how to retrieve your connection string
# from an environment variable.
connection_string = os.environ["COMMUNICATION_SERVICES_CONNECTION_STRING"]

# Instantiate the identity client
client = CommunicationIdentityClient.from_connection_string(connection_string)

Como alternativa, si ya ha configurado una aplicación Azure Active Directory (Azure AD), puede autenticarse mediante Azure AD.

endpoint = os.environ["COMMUNICATION_SERVICES_ENDPOINT"]
client = CommunicationIdentityClient(endpoint, DefaultAzureCredential())

Creación de una identidad

Para crear tokens de acceso, necesita una identidad. Azure Communication Services mantiene un directorio de identidad ligero para este propósito. Use el método create_user para crear una nueva entrada en el directorio con un Id único. La identidad es necesaria más adelante para emitir tokens de acceso.

identity = client.create_user()
print("\nCreated an identity with ID: " + identity.properties['id'])

Almacene la identidad recibida con la asignación a los usuarios de la aplicación (por ejemplo, almacenándola en la base de datos del servidor de aplicaciones).

Emitir tokens de acceso

Use el método get_token para emitir un token de acceso para la identidad de Communication Services. El parámetro scopes define un conjunto de roles y permisos de token de acceso. Para obtener más información, consulte la lista de acciones admitidas en el modelo de identidad. También puede construir una nueva instancia de parámetro CommunicationUserIdentifier basada en una representación de cadena de la identidad de Azure Communication Service.

# Issue an access token with the "voip" scope for an identity
token_result = client.get_token(identity, ["voip"])
expires_on = token_result.expires_on.strftime("%d/%m/%y %I:%M %S %p")

# Print the details to the screen
print("\nIssued an access token with 'voip' scope that expires at " + expires_on + ":")
print(token_result.token)

Los tokens de acceso son credenciales de corta duración que deben volver a emitirse. Si no lo hace, podría provocar una interrupción de la experiencia de los usuarios de la aplicación. La propiedad de respuesta expires_on indica la duración del token de acceso.

Creación de una identidad y emisión de un token de acceso en la misma solicitud

Use el método create_user_and_token para crear una identidad de Communication Services y, a la vez, emitir un token de acceso para ella. El parámetro scopes define un conjunto de roles y permisos de token de acceso. Para obtener más información, vea la lista de acciones admitidas en Autenticación para Azure Communication Services.

# Issue an identity and an access token with the "voip" scope for the new identity
identity_token_result = client.create_user_and_token(["voip"])

# Get the token details from the response
identity = identity_token_result[0]
token = identity_token_result[1].token
expires_on = identity_token_result[1].expires_on.strftime("%d/%m/%y %I:%M %S %p")

# Print the details to the screen
print("\nCreated an identity with ID: " + identity.properties['id'])
print("\nIssued an access token with 'voip' scope that expires at " + expires_on + ":")
print(token)

Tokens de acceso de actualización

Para actualizar un token de acceso, use el objeto CommunicationUserIdentifier para volver a emitir un token pasando la identidad existente:

# The existingIdentity value represents the Communication Services identity that's stored during identity creation
identity = CommunicationUserIdentifier(existingIdentity)
token_result = client.get_token(identity, ["voip"])

Revocación de los tokens de acceso

En ocasiones, es posible que tenga que revocar explícitamente un token de acceso. Por ejemplo, lo haría cuando los usuarios de la aplicación cambien la contraseña que usan para autenticarse en el servicio. El método revoke_tokens invalida todos los tokens de acceso activos que fueron emitidos para la identidad.

client.revoke_tokens(identity)
print("\nSuccessfully revoked all access tokens for identity with ID: " + identity.properties['id'])

Eliminación de una identidad

Cuando se elimina una identidad, se revocan todos los tokens de acceso activos y se impide la emisión adicional de tokens de acceso para la identidad. También quita todo el contenido conservado asociado a la identidad.

client.delete_user(identity)
print("\nDeleted the identity with ID: " + identity.properties['id'])

Ejecución del código

Desde un símbolo del sistema de la consola, vaya al directorio que contiene el archivo issue-access-tokens.py y, a continuación, ejecute el siguiente comando python para ejecutar la aplicación.

python ./issue-access-tokens.py

La salida de la aplicación describe cada acción completada:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Prerrequisitos

Código final

Busque el código finalizado de este inicio rápido en GitHub.

Configurar el entorno

Creación de una aplicación Java

En una terminal o una ventana del símbolo del sistema, vaya al directorio donde desea crear la aplicación Java. Para generar un proyecto de Java a partir de la plantilla maven-archetype-quickstart, ejecute el código siguiente:

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

Notará que la tarea generate crea un directorio con el mismo nombre que artifactId. En este directorio, el directorio src/main/java contiene el código fuente del proyecto, el directorio src/test/java contiene el origen de la prueba, y el archivo pom.xml es el modelo de objetos del proyecto o POM. Este archivo se usa para los parámetros de configuración del proyecto.

Instalación de los paquetes de Communication Services

Abra el archivo pom.xml en el editor de texto. Agregue el siguiente elemento de dependencia al grupo de dependencias:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-identity</artifactId>
    <version>1.1.1</version>
</dependency>

Este código indica a Maven que instale el SDK de identidad de Communication Services, que usará más adelante.

Instalación del marco de la aplicación

En el directorio del proyecto, haga lo siguiente:

  1. Vaya al directorio /src/main/java/com/communication/quickstart.
  2. Abra el archivo App.java en el editor.
  3. Reemplace la instrucción System.out.println("Hello world!");.
  4. Agregue las directivas import.

Use el código siguiente para empezar:

package com.communication.quickstart;

import com.azure.communication.common.*;
import com.azure.communication.identity.*;
import com.azure.communication.identity.models.*;
import com.azure.core.credential.*;

import java.io.IOException;
import java.time.*;
import java.util.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Access Tokens Quickstart");
        // Quickstart code goes here
    }
}

Autenticar el cliente

Cree una instancia de CommunicationIdentityClient con la clave de acceso y el punto de conexión del recurso. Para obtener más información, vea la sección "Almacenar la cadena de conexión" de Creación y administración de recursos de Communication Services.

Además, puede inicializar el cliente con cualquier cliente HTTP personalizado que implemente la interfaz com.azure.core.http.HttpClient.

En el archivo App.java, agregue el código siguiente al método main:

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
String accessKey = "SECRET";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
        .endpoint(endpoint)
        .credential(new AzureKeyCredential(accessKey))
        .buildClient();

En lugar de proporcionar el punto de conexión y la clave de acceso, puede proporcionar toda la cadena de conexión mediante el método connectionString().

// You can find your connection string from your Communication Services resource in the Azure portal
String connectionString = "<connection_string>";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Si ya ha configurado una aplicación Azure Active Directory (Azure AD), puede autenticarse mediante Azure AD.

String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
TokenCredential credential = new DefaultAzureCredentialBuilder().build();

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
        .endpoint(endpoint)
        .credential(credential)
        .buildClient();

Creación de una identidad

Para crear tokens de acceso, necesita una identidad. Azure Communication Services mantiene un directorio de identidad ligero para este propósito. Use el método createUser para crear una nueva entrada en el directorio con un Id único.

CommunicationUserIdentifier user = communicationIdentityClient.createUser();
System.out.println("\nCreated an identity with ID: " + user.getId());

La identidad creada es necesaria más adelante para emitir tokens de acceso. Almacene la identidad recibida con la asignación a los usuarios de la aplicación (por ejemplo, almacenándola en la base de datos del servidor de aplicaciones).

Emitir tokens de acceso

Use el método getToken para emitir un token de acceso para la identidad de Communication Services. El parámetro scopes define un conjunto de roles y permisos de token de acceso. Para obtener más información, consulte la lista de acciones admitidas en el modelo de identidad.

En el código siguiente, use la variable de usuario que creó en el paso anterior para obtener un token.

// Issue an access token with the "voip" scope for a user identity
List<CommunicationTokenScope> scopes = new ArrayList<>(Arrays.asList(CommunicationTokenScope.VOIP));
AccessToken accessToken = communicationIdentityClient.getToken(user, scopes);
OffsetDateTime expiresAt = accessToken.getExpiresAt();
String token = accessToken.getToken();
System.out.println("\nIssued an access token with 'voip' scope that expires at: " + expiresAt + ": " + token);

Creación de una identidad y emisión de un token en una solicitud

Como alternativa, puede usar el método "createUserAndToken" para crear una nueva entrada en el directorio con un único Id y emitir un token de acceso al mismo tiempo.

List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(scopes);
CommunicationUserIdentifier user = result.getUser();
System.out.println("\nCreated a user identity with ID: " + user.getId());
AccessToken accessToken = result.getUserToken();
OffsetDateTime expiresAt = accessToken.getExpiresAt();
String token = accessToken.getToken();
System.out.println("\nIssued an access token with 'chat' scope that expires at: " + expiresAt + ": " + token);

Los tokens de acceso son credenciales de corta duración que deben volver a emitirse. Si no lo hace, podría provocar una interrupción de la experiencia de los usuarios de la aplicación. La propiedad expiresAt indica la duración del token de acceso.

Tokens de acceso de actualización

Para actualizar un token de acceso, use el objeto CommunicationUserIdentifier para volver a emitirlo:

// existingIdentity represents the Communication Services identity that's stored during identity creation
CommunicationUserIdentifier identity = new CommunicationUserIdentifier(existingIdentity.getId());
AccessToken response = communicationIdentityClient.getToken(identity, scopes);

Revocación de un token de acceso

En ocasiones, es posible que tenga que revocar explícitamente un token de acceso. Por ejemplo, lo haría cuando los usuarios de la aplicación cambien la contraseña que usan para autenticarse en el servicio. El método revokeTokens invalida todos los tokens de acceso activos para un usuario determinado. En el código siguiente, puede usar el usuario creado anteriormente.

communicationIdentityClient.revokeTokens(user);
System.out.println("\nSuccessfully revoked all access tokens for user identity with ID: " + user.getId());

Eliminación de una identidad

Cuando se elimina una identidad, se revocan todos los tokens de acceso activos y se impide la emisión adicional de tokens de acceso para la identidad. También quita todo el contenido conservado asociado a la identidad.

communicationIdentityClient.deleteUser(user);
System.out.println("\nDeleted the user identity with ID: " + user.getId());

Ejecución del código

Vaya al directorio que contiene el archivo pom.xml y, a continuación, compile el proyecto mediante el comando mvn siguiente:

mvn compile

A continuación, compile el paquete:

mvn package

Ejecute el siguiente comando mvn para ejecutar la aplicación:

mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

La salida de la aplicación describe cada acción completada:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 30/03/21 08:09 09 AM:
<token signature here>

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Uso de la identidad para la supervisión y las métricas

El identificador de usuario está pensado para actuar como clave principal para los registros y métricas que se recopilan a través de Azure Monitor. Para ver todas las llamadas de un usuario, por ejemplo, puede configurar la autenticación de una manera que asigna una identidad de Azure Communication Services específica (o identidades) a un único usuario.

Obtenga más información sobre los conceptos de autenticación, los diagnósticos de llamadas a través de los análisis de registros y las métricas que están disponibles para usted.

Limpieza de recursos

Si quiere limpiar y quitar una suscripción de Communication Services, elimine el recurso o el grupo de recursos. Al eliminar un grupo de recursos también se eliminan los demás recursos asociados a él. Para obtener más información, vea la sección "Almacenar la cadena de conexión" de Creación y administración de recursos de Communication Services.

Pasos siguientes

En este inicio rápido ha aprendido a:

  • Administrar identidades
  • Emitir tokens de acceso
  • Usar el SDK de identidades de Communication Services

También puede que desee consultar: