Autenticación en las API de Vonage Business Communications

Una vez que haya has creado tu solicitudy suscrito a la API de aprovisionamiento Ya estás listo para crear un token de acceso. Las API de Vonage Business Communications utilizan OAuth para la autenticación.

Creación de claves de autenticación

  1. Inicie sesión en Portal para desarrolladores de comunicaciones empresariales utilizando sus credenciales de desarrollador.

  2. Seleccionar Applications en el menú de navegación superior.

  3. En el Aplicaciones página, busca tu solicitud en la tabla y haz clic en la solicitud nombre enlace.

  4. Selecciona el Claves de producción en el menú de navegación de la izquierda:

    Screenshot showing the Production Keys tab of the My Applications page

    Nota: El tipo de subvención predeterminado es Password. En tipo de subvención es el método que utiliza OAuth para generar un token de acceso. Cuando crees una aplicación de producción, lo habitual es que quieras utilizar Code método para autenticar las solicitudes. El Refresh Token Esta opción creará un nuevo token cuando caduque el actual.

  5. Si Code seleccionado, en el URL de devolución de llamada introduzca una URL de devolución de llamada válida que su aplicación utilizará para recibir el código generado. Si aún no ha creado su aplicación, introduzca http://localhost por ahora y recuerde introducir la URL correcta cuando esté listo para probarlo.

    Nota: Si tienes pensado utilizar el tipo de autorización mediante contraseña para tu aplicación, no necesitarás utilizar una URL de devolución de llamada para recuperar el token, como sí ocurriría con el flujo de código de autorización. Si utilizas la autorización mediante contraseña, puedes dejar este campo en blanco.

  6. Haz clic en el Generar claves botón. Esto genera el Clave del consumidor y El secreto del consumidor que tu aplicación utilizará para solicitar un token.

Tipos de subvenciones admitidas

Vonage Business Communications admite los siguientes tipos de concesión para generar tokens de acceso.

  • Código de autorización - El tipo de concesión Código de autorización es utilizado por clientes confidenciales y públicos para intercambiar un código de autorización por un token de acceso. Después de que el usuario vuelva al cliente a través de la URL de redirección, la aplicación obtendrá el código de autorización de la URL y lo utilizará para solicitar un token de acceso.
  • Concesión de contraseña - El tipo de autorización «Contraseña» es una forma de canjear las credenciales de un usuario por un token de acceso.

¿Cuándo utilizar el tipo de concesión de contraseña?

El tipo de autorización «Contraseña» requiere que la aplicación recopile la contraseña del usuario. Se recomienda utilizar el tipo de autorización «Contraseña» únicamente para habilitar aplicaciones de servidor a servidor en las que no sea necesario recopilar las credenciales del usuario.

  1. Fíjate en el Ejemplos de puntos finales y Generación de tokens de acceso para aprender a solicitar el código de autenticación e intercambiarlo por un token de acceso:

En producción, debe utilizar la función código_de_autorización tipo de subvención (Code) y esta es la única opción que aparece en la pestaña «Mis aplicaciones» en apimanager.uc.vonage.com. En Code requiere que tu aplicación implemente una URL de devolución de llamada válida para recuperar el código de autorización de los servidores de Vonage e intercambiarlo por un token. Consulta los ejemplos de puntos finales en la pestaña Mis aplicaciones para aprender a crear las solicitudes de autorización y token.

Autenticación con concesión de código de autorización

Advertencia: SSO no es compatible en este momento

El siguiente ejemplo muestra cómo obtener un authorization_code a través del punto final authorize.

https://api.vonage.com/authorize?scope=openid&response_type=code&redirect_uri=$REDIRECT_URI&client_id=$CONSUMER_KEY
  • REDIRECT_URI - La URL a la que se redirigirá al usuario tras la autenticación.
  • CONSUMER_KEY - La clave de consumidor que generó en el paso 5 anterior

El siguiente ejemplo muestra cómo intercambiar un código de autorización por un token a través del punto final de token

curl --request POST 'https://api.vonage.com/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic $AUTHORIZATION' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'code=$AUTHORIZATION_CODE' \ --data-urlencode 'redirect_uri=$REDIRECT_URI'
  • AUTHORIZATION_CODE - El código recibido por el redirect_uri después de iniciar sesión con éxito.
  • REDIRECT_URI - La URL a la que redirigir al usuario después de intercambiar el código de autorización.
  • AUTHORIZATION - Un token codificado en Base64 de las credenciales de la aplicación en el formato $CONSUMER_KEY:$CONSUMER_SECRET.

Tras canjear el token, recibirás una respuesta JSON con el access_token integrado en él. Necesitas este token para utilizar las API de Account, Extensión y Usuario:

{
   "access_token":"xyz123eyJ4NQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..gs7JO2RLPFIld7NXM9gnOy9CYaLs_EYXJJilxX76MFBiidoiG9sIW4RkeHLvDVLyFP1eVd_Pt7000wAr13mcXn-6x6D9oJeAH_Iz8nbzd3vmWDZ8VMHf1SueiAaChfvH0yLvwu02sp-QU-tljGYBTJ8Pr1jWQIG-o39XRrBSMis",
   "refresh_token":"dde2a67f-d99f-3f03-810b-1fcae59245de",
   "scope":"default",
   "token_type":"Bearer",
   "expires_in":86400
}

Autenticación mediante «Password Grant»

Todos los fragmentos de código de la documentación de la API VBC utilizan el método tipo de concesión de contraseña en lugar del recomendado authorization_code para facilitar su ejecución. Este tipo de subvención no requiere que implementes una URL de devolución de llamada. En su lugar, debes introducir tu nombre de usuario y contraseña de VBC para solicitar un token.

Sustituya los siguientes marcadores de posición del ejemplo por sus propios valores:

  • VBC_USERNAME - Tu nombre de usuario de Vonage Business Communications
  • VBC_PASSWORD - Tu contraseña de Vonage Business Communications
  • CONSUMER_KEY - La clave de consumidor que generó en el paso 5 anterior
  • CONSUMER_SECRET - El Secreto de Consumidor que generó en el paso 5 anterior

Nota: Si utiliza la concesión de contraseña, tendrá que añadir @vbc.prod a tu nombre de usuario.

Advertencia: No utilices las credenciales de tu Account de desarrollador de VBC (*.api) para solicitar el token. Debes utilizar las credenciales de tu Account de usuario de VBC para VBC_USERNAME y VBC_PASSWORD.

curl --request POST 'https://api.vonage.com/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=password' \ --data-urlencode 'scope=openid' \ --data-urlencode 'username=$VBC_USERNAME@vbc.prod' \ --data-urlencode 'password=$VBC_PASSWORD' \ --data-urlencode 'client_id=$VBC_CLIENT_ID' \ --data-urlencode 'client_secret=$VBC_CLIENT_SECRET'

Al ejecutarlo, recibirás una respuesta JSON con el access_token integrado en él. Necesitas este token para utilizar las API de Account, Extensión y Usuario:

{
    "access_token": "xyz123eyJ4NQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..gs7JO2RLPFIld7NXM9gnOy9CYaLs_EYXJJilxX76MFBiidoiG9sIW4RkeHLvDVLyFP1eVd_Pt7000wAr13mcXn-6x6D9oJeAH_Iz8nbzd3vmWDZ8VMHf1SueiAaChfvH0yLvwu02sp-QU-tljGYBTJ8Pr1jWQIG-o39XRrBSMis",
    "refresh_token": "abc123-5903-3513-8d27-333daf581837",
    "scope": "openid",
    "id_token": "abc123eyJ4NQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..gs7JO2RLPFIld7NXM9gnOy9CYaLs_EYXJJilxX76MFBiidoiG9sIW4RkeHLvDVLyFP1eVd_Pt7000wAr13mcXn-6x6D9oJeAH_Iz8nbzd3vmWDZ8VMHf1SueiAaChfvH0yLvwu02sp-QU-tljGYBTJ8Pr1jWQIG-o39XRrBSMis",
    "token_type": "Bearer",
    "expires_in": 82566
}

Expiración de la ficha

  • Token de acceso - Los tokens de acceso caducan al cabo de 24 horas (86 400 segundos). Una vez que un token de acceso haya caducado, tendrás que utilizar el token de actualización con el tipo de autorización «refresh» para solicitar un nuevo token de acceso.
  • Actualizar ficha - Los tokens de actualización caducan a los 7 días (604 800 segundos). Una vez que se canjea un token de actualización por un token de acceso, el token de actualización deja de ser válido y se proporciona uno nuevo. Si no se utiliza el token de actualización dentro del plazo de validez, tendrás que volver a autenticarte.

Uso del token de actualización

Cuando el token de acceso caduque, tendrá que regenerar un nuevo token de acceso, utilizando el token de actualización. El token de actualización se enviará la primera vez que realice una solicitud a la aplicación /token punto final.

Para regenerar el token de acceso:

curl --location --request POST 'https://api.vonage.com/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'client_id=$VBC_CLIENT_ID' \ --data-urlencode 'client_secret=$VBC_CLIENT_SECRET' \ --data-urlencode 'refresh_token=$REFRESH_TOKEN'

Sustituya los siguientes marcadores de posición del ejemplo por sus propios valores:

  • VBC_CLIENT_ID - El ID de cliente de su aplicación de desarrollo
  • VBC_CLIENT_SECRET - La clave secreta de tu aplicación de desarrollador
  • REFRESH_TOKEN - El token de actualización de tu solicitud inicial para obtener un token de acceso.

Esto devolverá un nuevo token de acceso y un token de actualización

{
   "access_token": "xyz123eyJ4NQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..gs7JO2RLPFIld7NXM9gnOy9CYaLs_EYXJJilxX76MFBiidoiG9sIW4RkeHLvDVLyFP1eVd_Pt7000wAr13mcXn-6x6D9oJeAH_Iz8nbzd3vmWDZ8VMHf1SueiAaChfvH0yLvwu02sp-QU-tljGYBTJ8Pr1jWQIG-o39XRrBSMis",
    "refresh_token": "abc123-5903-3513-8d27-333daf581837",
    "scope": "openid",
    "id_token": "abc123eyJ4NXQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJraWQiOiJNemcxTnpZeU5UTXhPR1kxTlRNMU1HUTBPR1ZsTVRnM05XRXlZamRpWVdRNE1XSTFNemhrWmciLCJhbGciOiJSUzI1NiJ9..kpFXRg4qSW9sntliysg-3EGO8KwZ8Vk5jGvOwqq0gJEyPQHL5BQKKrF799VL6Z9OJfCne564N42UWnrQqUmNyU0q8l0td1E3zPA0L5iQQEbaVsbxRf5NCZUwYY9Pb7bXjINCiGF4Xy7wCw2SRpv9iQvg3G68qI5Z8f_25QmxSTY",
    "token_type": "Bearer",
    "expires_in": 86400
}

Para todas las solicitudes de API que se realicen a partir de ahora, deberás utilizar este token de acceso. Cuando este token de acceso caduque, deberás generar uno nuevo utilizando el último token de actualización.

Próximos pasos

Ahora que ha creado un token de acceso, está listo para realizar una solicitud API.