RapidIdentity Product Guide

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>.

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.

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:

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.