Configuración rápida

Agregar el sistema de identificación de Mozilla Persona a tu sitio web solo requiere seguir estos cinco pasos:

Incluye en tus páginas la biblioteca JavaScript de Mozilla Persona.
Agrega los botones "conectar" y "desconectar".
Presta atención a las acciones de conexión y desconexión.
Comprueba las credenciales de los usuarios.
Revisa las buenas prácticas.

Con esto deberías poder ponerlo en funcionamiento en una sola tarde, pero lo primero es lo primero: si vas a usar Mozilla Persona en tu sitio, por favor, dedica unos minutos a suscribirte a la lista de correo de Mozilla Persona. Tiene muy poco tráfico ya que solo se usa para anunciar cambios o cuestiones relacionadas con la seguridad que pueden tener un impacto negativo sobre tu sitio.

Paso 1: Incluye la biblioteca de Persona

Persona está diseñado para no depender del navegador y funciona correctamente con la todos los naveadores de escritorio y móviles modernos. Esto es posible gracias a la biblioteca JavaScript multiplataforma de Persona. Una vez que se carga ésta biblioteca en tu página, las funciones de Persona que necesitas (watch(), request(), y logout()) estarán disponibles en el objeto global navigator.id.

Para incluir la biblioteca JavaScript de Persona, puedes colocar ésta etiqueta script en el head de tu página:

<script src="https://login.persona.org/include.js"></script>

Debes incluir esto en todas las páginas que usen las funciones navigator.id. Debido a que Persona está aún en desarrollo, no debes alojar en tu servidor el archivo include.js.

Paso 2: Añadir botones de inicio y cierre de sesión

Debido a que Persona está diseñado como una API DOM, debes ejecutar funciones cuando un usuario haga clic en los botones de inicio y cierre de sesión en tu web. Para abrir un diálogo de Persona y pedir que el usuario inicie sesión, debes ejecutar navigator.id.request(). Para cerrar sesión, ejecuta navigator.id.logout().

Por ejemplo:

var signinLink = document.getElementById('signin');
if (signinLink) {
  signinLink.onclick = function() { navigator.id.request(); };
};

var signoutLink = document.getElementById('signout');
if (signoutLink) {
  signoutLink.onclick = function() { navigator.id.logout(); };
};

¿Cómo deben ser esos botones? Da un vistazo a nuestra página de recursos de marca para conseguir imágenes y botones css predefinidos.

Paso 3: Vigilar las acciones de inicio y cierre de sesión

Para que Persona funcione, necesitas indicarle qué hacer cuando un usuario inicia o cierra sesión. Este se puede realizar llamando a la función navigator.id.watch() y pasandole tres parámetros:

El loggedInEmail del actual usuario de tu sitio, o null si no existe. Deberías generar esto dinámicamente cuando la página es pintada.
Una función a la que invocar cuando la acción onlogin es desencadenada. Esta función se pasa como un parámetro único, una "afirmación de identidad", que debe ser verificada.
Una función a la que invocar cuando la acción onlogout es desencadenada. En esta función no se pasa ningún parámetro.

Nota: Siempre tienes que incluir ambas funciones, onlogin y onlogout, cuando llames a navigator.id.watch().

Por ejemplo, si actulamente crees que Bob ha iniciado sesión en tu sitio, puedes hacer esto:

var currentUser = '[email protected]';

navigator.id.watch({
  loggedInEmail: currentUser,
  onlogin: function(assertion) {
    // Un usuario ha iniciado sesión!  Aquí necesitas:
    // 1. Enviar la verificación a tu servidor para verificar y crear la sesión.
    // 2. Actualizar la interfaz de usuario.
    $.ajax({ /* <-- Este ejemplo utiliza Jquery, pero usar lo que más te guste */
      type: 'POST',
      url: '/auth/login', // Esta es la URL de tu servidor.
      data: {assertion: assertion},
      success: function(res, status, xhr) { window.location.reload(); },
      error: function(res, status, xhr) { alert("login failure" + res); }
    });
  },
  onlogout: function() {
    // Un usuario ha cerrado sesión. Aqui necesitas:   // Salir de la sesión redirigiendo al usuario o haciendo una llamada a tu servidor.
    $.ajax({
      type: 'POST',
      url: '/auth/logout', // Esta es la URL de tu servidor.
      success: function(res, status, xhr) { window.location.reload(); },
      error: function(res, status, xhr) { alert("logout failure" + res); }
    });
  }
});

En este ejemplo, ambas funciones, onlogin y onlogout, son implementeadas por una petición asíncrona POST al servidor del sitio. El servidor registra la entrada o salida del usuario usualmente ajustando o eliminando información de la cookie de sesión. Entonces, si todo ha sido verificado, la página recargará para acceder al nuevo estado de sesión de la cuenta.

Puedes usar AJAX para implementar esto sin necesidad de recargar o redirigir la página, pero eso queda fuera del alcance de este tutorial.

Tienes que llamar a esta función en cada página con un botón de inicio o cierre de sesión. Para dar soporte a mejoras de Persona, como el inicio de sesión automático y el cierre de sesión global para los usuarios, deberás llamar a esta función en cada página de tu sitio.

Paso 4: Comprueba las credenciales de los usuarios

En lugar de contraseñas, Persona utiliza "declaraciones de identidad", que son algo así como contraseñas de un solo uso y un solo sitio combinadas con la dirección de correo electrónico del usuario. Cuando un ususario desea iniciar sesión, tu función de retorno onlogin será invocada con una declaración de ese usuario. Antes de que le inicies sesión, debes verificar que la declaración es válida.

Es extremadamente importante que verifiques la declaración en tu servidor, y no en el código JavaScript ejecutándose en el navegador del usuario, debido a que podría ser fácil de falsificar. El ejemplo de arriba envió la declaración al servidor del sitio utilizando la función $.ajax() de jQuery para hacer POST en /api/login.

Una vez que tu servidor tiene la declaración, ¿cómo la verificas? La manera más fácil es utilizando un servicio de ayuda provisto por Mozilla. Simplemente envía una solicitud POST a https://verifier.login.persona.org/verify con dos parámetros:

assertion: La declaración de identidad provista por el usuario.
audience: El nombre y puerto de tu sitio. Debes establecer rígidamente este valor en tu código de servidor; no lo derives de ningún dato suministrado por el usuario.

Por ejemplo, si eres example.com, puedes utilizar la línea de comandos para probar una declaración con:

$ curl -d "assertion=<ASSERTION>&audience=https://example.com:443" "https://verifier.login.persona.org/verify"

Si es válida, obtendrás una respuesta JSON como la siguiente:

{
  "status": "okay",
  "email": "[email protected]",
  "audience": "https://example.com:443",
  "expires": 1308859352261,
  "issuer": "eyedee.me"
}

Puedes aprender mas acerca del servicio de verificación leyendo La API del Servicio de Verificación. Un ejemplo la implementación de /api/login, utilizando Python, el framework web Flask, y la librería Requests HTTP se vería así:

@app.route('/api/login', methods=['POST'])
def login():
    # The request has to have an assertion for us to verify
    if 'assertion' not in request.form:
        abort(400)

    # Send the assertion to Mozilla's verifier service.
    data = {'assertion': request.form['assertion'], 'audience': 'https://example.com:443'}
    resp = requests.post('https://verifier.login.persona.org/verify', data=data)

    # Did the verifier respond?
    if resp.ok:
        # Parse the response
        verification_data = json.loads(resp.content)

        # Check if the assertion was valid
        if verification_data['status'] == 'okay':
            # Log the user in by setting a secure session cookie
            session.update({'email': verification_data['email']})
            return resp.content

    # Oops, something failed. Abort.
    abort(500)

El manejo de sesiones es probablemente muy similar a tu sistema actual de login. El primer gran cambio está en la verificación de la identidad del usuario revisando una aserción en vez de revisar un password. El otro gran cambio es asegurarse que la dirección de email del usuario está disponible para usarse en el parametro loggedInEmail para navigator.id.watch().

El Logout es simple: Solo necesitas remover la cookie de la sesión del usuario.

Paso 5: Revisa las mejores prácticas

Una vez que todo funciona y has logrado iniciar y cerrar sesion satisfactoriamente en tu sitio, debes de tomarte un momento para revisar las mejores prácticas para usar Persona de forma segura.

Si estás haciendo un sitio listo para producción, tal vez quieras hacer pruebas de integración que simulan un usuario entrando y saliendo de tu sitio utilizando BrowserID. Para facilitar esta acción en Selenium, considera la librería bidpom. Los sitios mockmyid.com y personatestuser.org también son útiles.

Por último, no olvides enrolarte en la lista de correos de Noticias de Persona para que seas notificado de cualquier problema de seguridad o cambios de incopatibilidad con versiones anteriores de la API de persona. La lista es extremadamente de poco tráfico: es solo utilizada para anunciar cambios que pueden impactar en tu sitio.