Parear cuenta - Githubissues

palako commented 3 weeks ago

La aplicacion en este repositorio ya esta obsoleta, hay que implementar algo completamente nuevo compatible con el Jira Marketplace or Jira Forge.

Estas son las instrucciones de Latch para autentica el API y para parear una cuenta. Esta Issue es para crear una cuenta basica con el pareado entre Latch y Jira.

Implementar todo en un nuevo directorio /JiraMarketplace

AUTENTICACION

En esta página se describe cómo funciona la autenticación en el servicio Latch.

Todas las solicitudes a la API de Latch deben estar firmadas. El proceso de firma es una versión simplificada del protocolo Oauth de dos vías.

Cada solicitud HTTP a la API debe ir acompañada de dos encabezados de autenticación: Authorization y Date.

El encabezado Authorization El encabezado Authorization debe tener el formato siguiente:

11PATHS requestId requestSignature requestId puede ser o bien un 'applicationId' o un 'userId', dependiendo de la API a la que acceda la petición.

11PATHS es una constante que determina el método de autenticación.

applicationId es un identificador alfanumérico que se obtiene al registrar una aplicación nueva.

requestSignature es una firma derivada de la url, parámetros, encabezados personalizados y fecha de la solicitud actual, todos ellos con hash utilizando un Secreto que también se obtiene mediante el applicationId al registrar la aplicación.

La firma de solicitud es una cadena codificada en Base64 y con firma HMAC-SHA1. La cadena se debe crear siguiendo este proceso.

Empezar por una cadena vacía. Anexar el nombre de método en mayúsculas. Actualmente, solo se admiten los valores GET, POST, PUT y DELETE. Anexar un separador de línea, " " (Punto Unicode U+000A). Anexar una cadena con la fecha actual en este formato exacto aaaa-MM-dd HH:mm:ss. Todo en este formato debe explicarse por sí solo, ten en cuenta que todo es numérico y se debe completar con ceros en caso necesario para que todos los números tengan dos dígitos, excepto el año, que tiene cuatro. Este valor se debe mantener para utilizarlo en el encabezado Date. El proceso de comprobación de firma fallará si no coinciden ambos. Anexar un separador de línea, " " (Punto Unicode U+000A). Serializar todos los encabezados específicos de esta aplicación (no cada encabezado HTTP de la solicitud). Todos los nombres de estos encabezados empiezan por X-11paths-. Convertir todos los nombres de encabezados a minúsculas. Ordenar los encabezados por nombre de encabezado en orden alfabético ascendente. Para cada valor de encabezado, convierte los encabezados de varias líneas en una única línea sustituyendo los caracteres de línea nueva " " por espacios sencillos " ". Crear una cadena vacía. A continuación, para cada encabezado después de la ordenación y transformaciones anteriores, añadir a la cadena recién creada el nombre de encabezado seguido de dos puntos ":" y del valor de encabezado. Cada nombre:valor debe estar separado del siguiente por un espacio sencillo " ". Recortar la cadena para asegurarse de que no contenga ningún carácter de espacio al inicio o al final. Anexar un separador de línea, " " (Punto Unicode U+000A). Anexa la cadena de consulta con codificación URL que consta de la ruta (empezando por la primera barra inclinada) y los parámetros de consulta. La cadena de consulta no debe contener el nombre de host o el puerto y no debe contener ningún carácter de espacio como prefijo o sufijo. Solamente para peticiones POST o PUT, anexar un separador de línea, " " (Punto Unicode U+000A). Solamente para peticiones POST o PUT, serializar los parámetros de la petición de la siguiente forma, siendo el nombre del parámetro y su valor, la representación en UTF-8 de su codificación URL. Ordenar los parámetros por nombre de parámetro en orden alfabético ascendente y a continuación por valor de parámetro. Crear una cadena vacía. A continuación, para cada parámetro después de la ordenación, añadir a la cadena recién creada el nombre de parámetro seguido de un signo igual "=" y del valor del parámetro. Cada nombre=valor debe estar separado del siguiente por un ampersand "&". Recortar la cadena para asegurarse de que no contenga ningún carácter de espacio al inicio o al final. Una vez que se haya creado la cadena siguiendo el proceso descrito más arriba, se debe firmar mediante el algoritmo HMAC-SHA1 y el secreto obtenido al registrar la aplicación. Después de la firma, los datos binarios sin procesar se deben codificar en base64. La cadena resultante es la cadena requestSignature que añadir al encabezado Authorization.

El encabezado X-11Paths-Date El encabezado X-11Paths-Date contiene el valor de la fecha UTC actual y debe tener el siguiente formato:

yyyy-MM-dd HH:mm:ss donde yyyy es el año, MM es el número del mes, dd es el número del día, HH es la hora en formato de 24 horas, mm son los minutos y ss los segundos. Todos los valores se deben completar con ceros para que tengan valores de dos dígitos, excepto el año, que tiene cuatro.

Es muy importante que el valor y el formato de este encabezado sean exactamente los mismos que los utilizados en el proceso de creación de requestSignature para el encabezado de autorización como se explica más arriba.

Ten en cuenta que puedes seguir utilizando el encabezado HTTP Date estándar en el formato que desees, por ejemplo RFC 1123. Solo asegúrate de no confundir ambos y de utilizar siempre el valor que utilices en X-11Paths-Date en el proceso de firma. La API ignorará el encabezado Date estándar.

Errores La siguiente es una lista de condiciones de error posibles que pueden ocurrir durante la autenticación

Error 101: Invalid Authorization header format Error 102: Invalid application signature Error 103: Authorization header missing Error 104: Date header missing Error 108: Invalid date format Error 109: Request expired, date is too old Error 111: User not authorized Error 112: Invalid user signature Error 113: Secret signing this request is not authorized to perform this operation

PAREADO

En esta página se describe el método preferido para parear cuentas mediante un token de pareado que los usuarios pueden obtener a través de las aplicaciones móviles.

Diagrama de pareado con la secuencia de token Autenticación Para utilizar esta solicitud tienes que autenticar tu app utilizando tu applicationId y firmarlo como se explica en la sección de autenticación.

Solicitud Para parear con la API de token, lleva a cabo una solicitud HTTP GET en el siguiente extremo:

https://latch.tu.com/api/2.0/pair/{token} donde token es un token alfanumérico de seis caracteres de longitud que se debe obtener del usuario que, a su vez, lo ha obtenido mediante la app móvil.

Respuesta Si todo va bien, la API devolverá una respuesta con este aspecto:

{"data":{"accountId":"..."}} donde accountId es un token alfanumérico de 64 caracteres de longitud que se puede utilizar para identificar de forma única la cuenta que se está pareando con esta aplicación. Este valor se debe almacenar para utilizarlo posteriormente en llamadas siguientes tales como estado o anular pareado.

Errores La siguiente es una lista de condiciones de error posibles que pueden ocurrir al intentar utilizar esta API:

Error 205: Account and application already paired Se devolverá este error cuando un usuario cuya cuenta ya esté pareada con esta aplicación haya generado el token especificado.

Error 206: Pairing token not found or expired La causa más probable de este error es el uso de un token caducado. Los tokens se deben utilizar para realizar el pareado hasta 60 segundos después de su creación, transcurrido dicho período caducan. Otra razón obvia para este error es que la solicitud incluya un token inventado.

Error 401: Missing parameter in API call