RapidIdentity Product Guide: New UI

Social Authentication Method
Setup
Facebook
  1. Log in to https://developers.facebook.com

  2. My Apps -> Add a New App -> Website

  3. Give it a meaningful name like "RapidFederation Test" -> Create New Facebook App ID

  4. Settings -> Advanced -> Valid OAuth redirect URIs

    1. https://<RF_HOST>:<RF_PORT>/idp/socialCallback?n=facebook

  5. Settings -> Advanced -> Require App Secret

    1. Set to "No"

  6. Enter App ID and App Secret in the Social configuration for your Authentication Policy

Google
  1. Log into Log into https://console.developers.google.com

  2. Create a new Project and give it a meaningful name like "RapidFederation Test"

  3. Choose "Use Google APIs"

  4. Search for and enable Identity Toolkit API

  5. Choose the "Credentials" item on the left

  6. Add credentials

    1. OAuth 2.0 client ID

    2. Configure consent screen -> Save

    3. Application Type: Web Application

    4. Authorized redirect URIs

      1. https://<RF_HOST>:<RF_PORT>/idp/socialCallback?n=googleplus

    5. Create

  7. Enter client ID and client secret in the Social configuration for your Authentication Policy

Twitter
  1. Log into https://apps.twitter.com/

  2. Create New App

    1. Give it a meaningful name like "RapidFederation Test"

    2. Fill in the rest of the required fields

    3. Callback URL

      1. https://<RF_HOST>:<RF_PORT>/idp/socialCallback/twitter

      2. If testing with localhost, just put in another hostname. It will be OK

  3. Permissions -> Read only

  4. Enter Consumer Key and Consumer Secret in the Social configuration for your Authentication Policy

LinkedIn
  1. Log into https://www.linkedin.com/secure/developer

  2. Create Application

    1. Give it a meaningful name like "RapidFederation Test"

    2. Fill in the rest of the required fields

  3. Keep Default Application Permission of r_basicprofile

  4. OAuth 2.0 Authorized Redirect URLs

    1. https://<RF_HOST>:<RF_PORT>/idp/socialCallback?n=linkedin

  5. Enter Client ID and Client Secret in the Social configuration for your Authentication Policy

API
Initial Response

Below is an example of an initial response:

{
  "type": "social",
  "id": "c2e109d0-8d7b-11e5-8c0d-0050b6c32ffc",
  "step": {
    "type": "choose",
    "providers": [
      {
        "id": "facebook",
        "iconUrl": "https://rapidIdentity.example.com:8443/idp/assets/img/
            social/facebook.svg",
        "authenticationUrl": "...."
      },
      {
        "id": "googleplus",
        "iconUrl": "https://rapidIdentity.example.com:8443/idp/assets/img/
            social/googleplus.svg",
        "authenticationUrl": "...."
      },
      {
        "id": "linkedin",
        "iconUrl": "https://rapidIdentity.example.com:8443/idp/assets/img/
            social/linkedin.svg",
        "authenticationUrl": "...."
      },
      {
        "id": "twitter",
        "iconUrl": "https://rapidIdentity.example.com:8443/idp/assets/img/
            social/twitter.svg",
        "authenticationUrl": "...."
      }
    ]
  }
}

This is an example of a "type" = "social" response from the server. Notice the "step" object whose type is "choose". This object contains information about all of the choices the user has for social authentication – in other words, which providers (social networks) are allowed for authentication.  Each provider has an "id", an "iconUrl" and an "authenticationUrl".  The choose screen should render each option as a clickable button with the specified iconUrl as the button's image.

When the user clicks on one of them, a new tab should be opened to the associated "authenticationUrl".  This will redirect the user to that social platform for authentication and once authenticated,  back into RapidFederation at the "callback URL" of .../idp/socialCallback?n=<network>.

Auth Step

As soon as the user clicks the button to open the new tab, the RapidFederation page should switch to a view that is ready to submit the "auth" step.

Below is an example auth request:

{
  "type": "social",
  "id": "c2e109d0-8d7b-11e5-8c0d-0050b6c32ffc",
  "step": {
    "type": "auth"
  }
}

kThe "auth" step is intended to be submitted after authentication at the social site has completed. If it is submitted before that takes place, the "choose" step will be returned again.

If the user authenticates to the social platform with an identity which has already been paired, then at this point life is good and RapidFederation will move on to the next step. If the user authenticates with a new identity (i.e. one which they have not previously paired), then we move on to the "pair" step which begins with a "pair" response from the server.

Pair Step

Below is an example pair response:

{
  "type": "social",
  "id": "c2e109d0-8d7b-11e5-8c0d-0050b6c32ffc",
  "step": {
    "type": "pair",
    "provider": {
      "id": "facebook",
      "iconUrl": "https://localhost:8443/idp/assets/img/social/googleplus.svg"
    },
    "profile": {
      "name": "John ",
      "email": "jdoe@example.com",
      "imageUrl": ""
    },
    "pairRequiresPassword": true
  }
}

The "pair" begins with the server responding with some basic information about the social identity used for authentication and should be considered as the server confirming that the user wants to pair that social identity with their RapidFederation identity. Note that there is information about the provider and some basic profile information.

In my testing with our currently supported social networks, I was able to get at least "name" and "imageUrl" to be returned.  Realize that the information we get back from each provider is dependent on what information the user has given to that provider as well as what OAuth permissions the app on that platform has been given.

One more request is required to complete the pair process and that is the confirmation from the user that they want to pair with that social identity:

Pair Request

Below is an example pair request:

{
  "type": "social",
  "id": "c2e109d0-8d7b-11e5-8c0d-0050b6c32ffc",
  "step": {
    "type": "pair",
    "password": "P@$$w0rD"
  }
}

If "pairRequiresPassword" is true in the previous Pair Response, then of course the user will need to provide their password to complete the pair. Otherwise it can be omitted. Once complete RapidFederation moves on to the next authentication step.