Documentación de Oracle Cloud Infrastructure

Uso de la autorización de token de acceso con la API de Mis servicios

Importante

El panel de control Mis servicios y las API están en desuso.

En este tema se explica cómo configurar y utilizar la autorización de token de acceso con la API de Mis servicios de Oracle Cloud. La autorización de token de acceso permite al desarrollador acceder a puntos finales programáticos (API) para obtener información (por ejemplo, derechos, instancias o datos de medición) de su cuenta en la nube.

Acerca de los tokens de acceso

Un token de acceso contiene la información necesaria para que un desarrollador pueda acceder a información de su cuenta en la nube. El desarrollador presenta el token al realizar llamadas de API. Las acciones y los puntos finales permitidos dependen de los ámbitos (permisos) que seleccione al generar el token. El token de acceso es válido durante aproximadamente una hora.

Un token de refrescamiento permite al desarrollador generar un nuevo token de acceso sin tener que ponerse en contacto con un administrador. El token de refrescamiento es válido durante aproximadamente un año.

Visión general del proceso

Pasos de configuración para el administrador:

  1. Cree una aplicación cliente de Identity Cloud Service con los privilegios específicos que desee otorgar a los desarrolladores.
  2. Genere un token de acceso que contenga los privilegios necesarios para el desarrollador previsto.
  3. Proporcione el token de acceso y la información necesaria al desarrollador.
  4. Configure Identity Cloud Service para la validación de tokens de acceso.

Pasos para que el desarrollador utilice el token:

  1. Emita solicitudes a los puntos finales de la API de Mis servicios. Incluya el token de acceso para el parámetro de autorización.
  2. Cuando caduque el token de acceso, refrésquelo sin la intervención del administrador hasta que termine el privilegio.

Tareas del administrador para configurar la validación del token

Realice las siguientes tareas para permitir el acceso del desarrollador con un token de acceso:

Cree la aplicación cliente de IDCS
  1. Conéctese a Identity Cloud Services como administrador y vaya a la consola de administración. Consulte Cómo acceder a Oracle Identity Cloud Service si necesita ayuda para conectarse.
  2. Haga clic en el mosaico Aplicaciones. Se muestra una lista de las aplicaciones.
  3. Haga clic en + Agregar para crear una nueva aplicación.
  4. Haga clic en Aplicación confidencial como tipo de aplicación.
  5. En la sección Detalles de aplicación, introduzca un valor en Nombre y Descripción. Evite introducir información confidencial.
  6. Haga clic en Siguiente.

  7. En la sección Cliente:

    1. Seleccione Configurar esta aplicación como un cliente ahora.
    2. En Autorización, para Tipos de permiso autorizados, seleccione las siguientes opciones:
      • Afirmación JWT
      • Token de refrescamiento

  8. En Política de emisión del token, en Recursos, haga clic en Agregar ámbito.

  9. En el cuadro de diálogo Seleccionar ámbito, seleccione CloudPortalResourceApp y haga clic en la flecha para seleccionar ámbitos para el recurso.

  10. Active la casilla que aparece junto a cada autorización que desee otorgar a los desarrolladores a los que proporcionará un token de acceso. (Los permisos se asignan en otro paso).

  11. Haga clic en Agregar para cerrar el cuadro de diálogo. Al hacerlo, se mostrarán las selecciones.

  12. Haga clic en Siguiente.

  13. En la sección Recursos, acepte el valor por defecto y haga clic en Siguiente.
  14. En la sección Política de capa web, acepte el valor por defecto y haga clic en Siguiente.

  15. En la sección Autorización, haga clic en Terminar.

    En la notificación Aplicación agregada se muestran el nuevo ID de cliente y secreto de cliente de la aplicación.

    Importante

    Copie y guarde el ID de cliente y el secreto de cliente en un lugar seguro y, a continuación, haga clic en Cerrar. El ID de cliente y el secreto de cliente son credenciales específicas de la aplicación que acaba de crear. Necesitará estas credenciales más adelante.
  16. Para terminar el proceso de creación, haga clic en Activar, en la parte superior de la página.
Generar un token de acceso

  1. Navegue hasta la aplicación de IDCS que ha creado en la tarea anterior y seleccione el separador Detalles.

  2. Haga clic en Generar token de acceso.

  3. En el cuadro de diálogo Generar token, seleccione Ámbitos personalizados y, a continuación, Llama a otras API.

  4. Seleccione los ámbitos que desee proporcionar al desarrollador que recibirá este token de acceso.

    Nota

    Oracle recomienda que solo otorgue los privilegios mínimos necesarios.

  5. Seleccione Incluir token de refrescamiento.

  6. Haga clic en Descargar token. El explorador le solicitará que descargue un archivo de token (.tok). El archivo de token contiene un token de acceso y un token de refrescamiento.

  7. Proporcione este archivo al desarrollador.
Enviar la información de acceso a un desarrollador

Para llamar a los puntos finales de API, el desarrollador necesita:

  • Un archivo de token que haya generado.

  • El ID de cliente y el secreto de cliente de la aplicación de IDCS utilizada para generar el archivo de token. El ID y el secreto del cliente son necesarios para que el desarrollador pueda generar un nuevo token de acceso a partir del token de refrescamiento.

  • Los puntos finales de las API.

    • Los puntos finales relacionados con los ámbitos de itas:myservices son: https://itra.oraclecloud.com/itas/<ID-IDCS-inquilino>/myservices/api/v1
    • Los puntos finales relacionados con los ámbitos de itas:metering son: https://itra.oraclecloud.com/metering/api/v1

Asegúrese de enviar la información anterior de manera segura. Si cree que esta información se ha visto comprometida, consulte Revocación de la capacidad del desarrollador de refrescar tokens de acceso.

Configurar Identity Cloud Service para validar el token de acceso

Para permitir que los clientes puedan acceder al certificado de firma del inquilino sin conectarse a Oracle Identity Cloud Service:

  1. Conéctese a la consola de administración de Oracle Identity Cloud Services. Consulte Cómo acceder a Oracle Identity Cloud Service si necesita ayuda para conectarse.
  2. Abra el menú de navegación. En Configuración, seleccione Configuración por defecto.
  3. Defina el botón de conmutación Acceder a certificado de firma en la opción de activado.

Uso del token de acceso

El archivo de token tiene la extensión .tok. El archivo contiene el token de acceso y el token de refrescamiento. El contenido es similar al siguiente:

{"app_access_token":"eyJ4N...aabb...CpNwA","refresh_token":"AQID...9NCA="}

Para utilizar el token con la API de Mis servicios:

  1. Abra el archivo de token.

  2. Emita una solicitud a un punto final válido, insertando el token de acceso del parámetro Authorization.

    Por ejemplo:

    curl -X GET  https://itra.oraclecloud.com/itas/<tenant-IDCS-ID>/myservices/api/v1/serviceEntitlements   -H 'Authorization: Bearer eyJ4N...aabb...CpNwA'

Solicitud de un nuevo token de acceso a partir de un token de refrescamiento

El token de acceso es válido durante aproximadamente una hora. Cuando el token ya no sea válido, recibirá un código de respuesta 401 y un valor de mensaje de error ("errorMessage") que contiene "Caducado".

Puede generar un nuevo token de acceso de corta duración a partir del token de refrescamiento. Necesitará el ID de cliente y el secreto de cliente para generar el nuevo token. Solo puede generar tokens con un acceso (ámbitos) igual o inferior a su token original.

Ejemplo con el comando curl:

curl -i -H 'Authorization: Basic <base64Encoded clientid:secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<tenant-IDCS-ID>/oauth2/v1/token -d 'grant_type=refresh_token&refresh_token=<refresh-token>'

Utilizando el archivo de token de ejemplo de la sección anterior, el valor de <token-refrescamiento> sería AQID...9NCA=.

Respuesta de ejemplo:

{ "access_token": "eyJraWQiO....2nqA", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "AQIDBAUn…VkxNCB7djF9NCA=" }
Nota

Cuando un desarrollador genera un token de acceso y un token de refrescamiento nuevos, el token de refrescamiento anterior deja de ser válido.

Revocación de la capacidad del desarrollador de refrescar tokens de acceso

Si necesita revocar la capacidad de un desarrollador de refrescar tokens de acceso, puede invalidar el token de refrescamiento existente generando un nuevo secreto de cliente para el token; o bien, puede revocar temporalmente el acceso desactivando la aplicación.

Importante

Con cualquiera de estas acciones se finalizará o suspenderá la capacidad de todos los desarrolladores que utilicen el secreto de cliente o la aplicación actual. Al generar tokens para varios desarrolladores, considere la posibilidad de crear más de una aplicación de IDCS para aislar a los desarrolladores entre sí.

Para finalizar la capacidad de un desarrollador de refrescar su token de acceso

  1. Conéctese a Identity Cloud Services como administrador y vaya a la consola de administración. Consulte Cómo acceder a Oracle Identity Cloud Service si necesita ayuda para conectarse.
  2. Haga clic en el mosaico Aplicaciones. Se muestra una lista de las aplicaciones.
  3. Haga clic en la aplicación utilizada para generar el token para ver sus detalles.
  4. Haga clic en Configuración.
  5. En Información general, junto a Secreto del cliente, haga clic en Volver a generar para generar un nuevo secreto de cliente.

Para restaurar la capacidad del desarrollador de generar un token de acceso a partir de un token de refrescamiento, genere un nuevo token de acceso. A continuación, proporcione el token junto con el nuevo secreto de cliente al desarrollador.

Para suspender temporalmente la capacidad de un desarrollador de refrescar su token de acceso

  1. Conéctese a Identity Cloud Services como administrador y vaya a la consola de administración. Consulte Cómo acceder a Oracle Identity Cloud Service si necesita ayuda para conectarse.
  2. Haga clic en el mosaico Aplicaciones. Se muestra una lista de las aplicaciones.
  3. Haga clic en la aplicación utilizada para generar el token para ver sus detalles.
  4. En la esquina superior derecha, haga clic en Desactivar.
  5. En la petición de datos, haga clic en Desactivar aplicación.

Para volver a habilitar a los desarrolladores para que utilicen los mismos tokens, haga clic en Activar.