Crear aplicaciones integradas para OAuth de DDFS

Cree las aplicaciones de dominio de identidad de OCI que un cliente de servicio a servicio utiliza para obtener un token de acceso OAuth para el servicio FHIR de datos de dispositivo (DDFS).

Configure una aplicación confidencial como el servidor de recursos DDFS y una aplicación confidencial independiente para cada servicio de llamada. Este procedimiento utiliza el permiso de credenciales de cliente OAuth 2.0 con autenticación de afirmación de cliente JWT y otorga solo los ámbitos de recursos FHIR requeridos por el cliente.

Antes de empezar

  • Confirme que tiene acceso de administrador al dominio de identidad que desea utilizar para DDFS. Para crear un dominio, consulte Creating an Identity Domain. Para utilizar un dominio existente, consulte Obtención de detalles de un dominio de identidad.
  • Identifique los recursos y las operaciones de FHIR de DDFS que necesita el cliente. Otorgue solo los ámbitos mínimos necesarios.
  • Antes de configurar la aplicación cliente, obtenga un certificado público y su clave privada coincidente mediante el proceso de gestión de certificados aprobado por la organización. Consulte Importing a Trusted Partner Certificate.
  • Cree una instancia de DDFS u obtenga detalles de una instancia de DDFS para obtener la URL base de la API de FHIR específica de la versión para la instancia de DDFS a la que llama el cliente.

    Por ejemplo:

    https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r4
    o
    https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r6-ballot4

La configuración utiliza dos aplicaciones confidenciales:

AplicaciónFinalidadÁmbito de ejemplo
Servidor de recursos DDFSRepresenta la API de FHIR de DDFS protegida y define los ámbitos que los clientes pueden solicitar.system/Device.rs
Aplicación ClienteRepresenta una aplicación o servicio que llama a DDFS y recibe solo los ámbitos requeridos por ese emisor de llamada.ddfssystem/Device.rs

Para obtener la sintaxis completa del ámbito y la asignación de contexto, consulte Dónde se configuran y solicitan los ámbitos.

Paso 1: Preparar el dominio de identidad

  1. Abra el menú de navegación y seleccione Identidad y seguridad. En Identidad, seleccione Dominios.
  2. Seleccione el dominio de identidad que desea utilizar para DDFS.
  3. En la página Domain details (Detalles de dominio), en la parte superior, desplácese a la derecha y seleccione Settings (Configuración).
  4. En Configuración de dominio - Configuración regional, seleccione Editar configuración de dominio.
  5. En Acceder a certificado de firma, active Configurar acceso de cliente y, a continuación, guardar los cambios.
  6. Vuelva a la página Domain details (Detalles de dominio) y seleccione Integrated applications (Aplicaciones integradas).

Los dominios de identidad publican las claves de firma públicas en este punto final:

https://<identity-domain>/admin/v1/SigningCert/jwk

DDFS recupera estas claves de firma públicas automáticamente para validar las firmas de token de acceso. La descarga de certificados raíz, la creación de archivos PEM y los pasos de instalación de socios de federación no forman parte de esta configuración de DDFS.

Paso 2: Crear y activar el servidor de recursos DDFS

  1. En la página Aplicaciones integradas, seleccione Agregar aplicación.
  2. Seleccione Aplicación confidencial y Iniciar flujo de trabajo.
  3. Introduzca un nombre y una descripción que identifiquen esta aplicación como el servidor de recursos de DDFS y Envíe la aplicación. Evite introducir información confidencial.
  4. En la página detalles de la aplicación, seleccione Acciones y, a continuación, Activar la aplicación del servidor de recursos.
  5. Seleccione Configuración de OAuth y, a continuación, Editar la configuración de OAuth.
  6. En Configuración del servidor de recursos, seleccione Configurar esta aplicación como un servidor de recursos Ahora.
  7. Active la opción Permitir refrescamiento de token.
  8. En Público principal, introduzca el valor exacto en minúscula ddfs.
  9. Active la opción para Agregar ámbitos.
  10. Seleccione Agregar para agregar un Ámbito para cada operación necesaria para la aplicación que realiza la llamada; introduzca solo los ámbitos canónicos de DDFS que necesitan las aplicaciones que realizan la llamada. Por ejemplo, agregue system/Device.rs para el acceso de lectura y búsqueda del dispositivo o agregue system/Device.* para el acceso a todas las operaciones del dispositivo. O bien, puede agregar system/*.* para acceder a todas las operaciones de todos los recursos.

    Para definir un acceso específico a los recursos admitidos, consulte Referencia de configuración de ámbito para obtener una lista de nombres de recursos, letras de operación, formularios de ámbito de cliente, requisitos de estado de suscripción y ámbitos administrativos necesarios para las operaciones de supresión inmediata.

  11. De manera opcional, introduzca un nombre mostrado o una descripción para cada ámbito.
  12. Seleccione Agregar y, a continuación, Enviar para guardar la configuración de OAuth.

Paso 3: Crear y activar la aplicación cliente

  1. Vuelva a la página Aplicaciones integradas del dominio de DDFS y seleccione Agregar aplicación.
  2. Seleccione Aplicación confidencial y Iniciar flujo de trabajo.
  3. Introduzca un nombre y una descripción que identifiquen la aplicación o el servicio que llama a DDFS y seleccione Enviar para crear la aplicación. Cree una aplicación cliente independiente para cada emisor de llamada gestionado de forma independiente.
  4. En la página de detalles de la aplicación, seleccione Configuración de OAuth y, a continuación, seleccione Editar configuración de OAuth para configurarla como cliente.
  5. En Configuración de cliente, seleccione la opción para Configurar esta aplicación como Cliente ahora y, a continuación, Enviar.
  6. En Autorización, seleccione Credenciales de cliente como tipo de permiso de OAuth para este servicio en el flujo de trabajo de servicio; no es un flujo de conexión de nombre de usuario y contraseña.
  7. En Política de emisión de token, active la opción Agregar recursos para que pueda agregar el servidor de recursos de DDFS como recurso autorizado.
  8. Seleccione Agregar ámbito, ahora puede ver los ámbitos configurados anteriormente para el servidor de recursos, seleccione la casilla de control junto a los ámbitos que desea agregar y, a continuación, seleccione Agregar y, a continuación, seleccione Enviar para guardar la configuración de OAuth.

    Otorgue solo los ámbitos de DDFS orientados al cliente requeridos por este emisor de llamada. Por ejemplo, otorgue ddfssystem/Device.rs cuando el cliente lea y busque recursos de dispositivo o para otorgar al cliente acceso a todas las operaciones de dispositivo, seleccione ddfssystem/Device.*

  9. En la página detalles de la aplicación, seleccione el menú Acciones y, a continuación, seleccione Activar. Confirme que la aplicación cliente muestra un estado Activo.
  10. Seleccione Configuración y, a continuación, certificados de socio de confianza.
  11. En Seguridad, seleccione Certificados de partner de confianza.
  12. Seleccione Importar certificado e importe el certificado público que corresponde a la clave privada protegida del cliente.

La clave privada permanece con la aplicación que realiza la llamada y no se carga en los dominios de identidad. La aplicación utiliza la clave privada para firmar cada afirmación de cliente de JWT de corta duración enviada con una solicitud de token de acceso.

Paso 4: Recopilar los valores de solicitud de token

Recopile los siguientes valores sin colocar credenciales ni material de claves privadas en el control de origen, los logs, los tickets de soporte o la documentación.

ValorOrigen
DOMAIN_URLURL base del dominio de identidad que contiene ambas aplicaciones integradas, por ejemplo, https://idcs-xxxxxxxx.identity.oraclecloud.com.
CLIENT_IDID de cliente en la página de detalles de la aplicación cliente confidencial.
CLIENT_ASSERTIONUna nueva afirmación de JWT de corta duración firmada con la clave privada protegida del cliente. Genere inmediatamente antes de la solicitud de token.
SCOPEÁmbitos orientados al cliente otorgados a la aplicación cliente, como ddfssystem/Device.rs. Separe varios ámbitos con un espacio.
FHIR_API_BASE_URLURL base de la API de FHIR específica de la versión completa de los detalles de la instancia de DDFS, como https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r4 o https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r6-ballot4.

Paso 5: Solicitar un token de acceso de OAuth

Solicite un token del dominio de identidad mediante el otorgamiento de credenciales de cliente y una afirmación de cliente JWT recién generada. El valor SCOPE solo debe contener ámbitos ya otorgados a la aplicación cliente.

Tratar el token de acceso devuelto como una credencial. No lo registre, reténgalo más tiempo del necesario o péguelo en un ticket de soporte.

  • curl -sS -X POST "${DOMAIN_URL}/oauth2/v1/token" \
      -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
      --data-urlencode "grant_type=client_credentials" \
      --data-urlencode "client_id=${CLIENT_ID}" \
      --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
      --data-urlencode "client_assertion=${CLIENT_ASSERTION}" \
      --data-urlencode "scope=${SCOPE}"
  • $body = @{
      grant_type = "client_credentials"
      client_id = $CLIENT_ID
      client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
      client_assertion = $CLIENT_ASSERTION
      scope = $SCOPE
    }
    
    $response = Invoke-RestMethod -Method Post `
      -Uri "$DOMAIN_URL/oauth2/v1/token" `
      -ContentType "application/x-www-form-urlencoded;charset=UTF-8" `
      -Body $body
    
    $ACCESS_TOKEN = $response.access_token

Paso 6: Llama a la API de DDFS FHIR

Envíe el token de acceso en la cabecera HTTP Authorization al llamar a un punto final de FHIR de DDFS protegido:

Authorization: Bearer <access_token>

Por ejemplo, un cliente con permiso de lectura Dispositivo puede recuperar un recurso Dispositivo:

curl -sS "${FHIR_API_BASE_URL}/Device/${DEVICE_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/fhir+json"

Utilice el token de acceso solo con solicitudes autorizadas por sus ámbitos otorgados. No descodifique el token como parte del flujo de trabajo normal del cliente.

Resultado

La aplicación cliente activa puede solicitar un token de acceso OAuth para sus ámbitos de DDFS otorgados y utilizar ese token para llamar a los puntos finales de FHIR protegidos correspondientes.

Solución de problemas

ProblemaCausa PosibleAcción
El servidor de recursos DDFS no está disponible al configurar el cliente.Las aplicaciones se encuentran en diferentes dominios de identidad o el servidor de recursos no está activo.Confirme que ambas aplicaciones estén en el mismo dominio de identidad y que el estado del servidor de recursos sea Activo.
La solicitud de token no autentica al cliente.La afirmación del cliente ha caducado, tiene un público de punto final de token incorrecto o no ha sido firmada por la clave asociada al certificado público registrado.Genere una nueva afirmación de corta duración, verifique el punto final del token y el ID de cliente y confirme que el certificado público registrado coincide con la clave de firma protegida.
La solicitud de token informa de un ámbito no válido o no autorizado.El ámbito no se ha definido en el servidor de recursos, no se ha otorgado al cliente, utiliza el formulario de contexto incorrecto o no se ha codificado form-URL.Defina el ámbito canónico system/... en el servidor de recursos, otorgue y solicite el formulario ddfssystem/... correspondiente y form-URL-encode el valor completo del parámetro de ámbito.
DDFS devuelve HTTP 401.Falta el token de acceso, ha caducado, tiene un formato incorrecto o no se ha emitido para el público y el dominio de identidad de DDFS configurados.Solicite un nuevo token del dominio de identidad configurado y envíelo una vez en la cabecera Authorization: Bearer. No incluya el token en los registros de diagnóstico.
DDFS devuelve HTTP 403.El token es válido, pero no otorga el recurso y la operación necesarios para la solicitud.Compare la interacción de FHIR solicitada con los ámbitos otorgados del cliente. Otorgue y solicite solo el ámbito de privilegio mínimo que falta.

Para obtener información general sobre el diagnóstico de API, consulte Solución de problemas.

Preguntas frecuentes

¿Por qué se necesitan dos aplicaciones integradas?
El servidor de recursos representa la API de FHIR de DDFS protegida y define los ámbitos disponibles. La aplicación cliente representa un emisor de llamada y recibe solo los ámbitos que necesita el emisor de llamada.
¿Cuándo activo las aplicaciones?
Active cada aplicación después de guardar su configuración de OAuth. El servidor de recursos debe estar activo antes de otorgar sus ámbitos al cliente, y el cliente debe estar activo antes de solicitar un token.
¿Por qué este procedimiento utiliza una afirmación de cliente JWT?
Una afirmación de cliente JWT permite al cliente confidencial probar la posesión de su clave privada sin enviar esa clave privada a los dominios de identidad. La afirmación sigue siendo material de credenciales de corta duración y no se debe registrar ni reutilizar.
¿En qué se diferencian el certificado de firma de dominio de identidad, el certificado de autenticación de cliente y el secreto de suscripción?
  1. Configuración de firma de acceso de dominio de identidad: en el Step 1, active el acceso al certificado de firma del dominio de identidad. Esto permite a DDFS obtener las claves de firma públicas del dominio de identidad y validar los tokens de acceso emitidos. DDFS recupera las claves automáticamente; no crea ni carga el par de claves de autenticación de cliente, descarga un certificado raíz ni instala un certificado en un socio de federación en este paso.
  2. Par de claves de autenticación de cliente: obtenga un certificado público y una clave privada coincidente mediante el proceso aprobado de su organización. En el Step 3, configure la aplicación confidencial como cliente, seleccione el permiso Client Credentials y el Trusted Client, e importe el certificado público. La clave privada permanece con la aplicación que realiza la llamada y firma cada afirmación de cliente de JWT de corta duración. En Adición de una aplicación confidencial se describe el flujo de trabajo general de los dominios de identidad y sus opciones disponibles; en el paso 3 se identifican las selecciones necesarias para DDFS.
  3. Secreto de suscripción: el secreto de OCI Vault para la autorización de notificación de suscripción R6 es independiente y opcional. Solo se utiliza cuando un punto final de bloqueo de REST R6 necesita una cabecera Authorization saliente y no está relacionado con la solicitud de token de acceso realizada por la aplicación que realiza la llamada.
¿Necesito descodificar el token de acceso?
Nº Después de que los dominios de identidad devuelvan el token, envíelo a DDFS en la cabecera Authorization: Bearer <access_token>. Decodificar tokens solo como parte de un proceso de diagnóstico aprobado y nunca revelar un token activo.
¿Configura esto SMART en la autorización FHIR?
Nº DDFS utiliza ámbitos de OAuth emitidos por los dominios de identidad de OCI y no proporciona ámbitos de autorización de usuarios y pacientes SMART ni de inicio SMART.

Autorización de eliminación inmediata opcional

Configure la autorización de supresión automática solo para un flujo de trabajo administrativo que deba llamar a $hardDelete o $purgeDeleted. Estas operaciones requieren un ámbito de supresión de recursos coincidente y el ámbito de supresión permanente personalizado. Para conocer los valores exactos de cliente y servidor de recursos, consulte Custom Hard-Delete Scope.