Federated Authentication

Describes the syncAccess Federated Authentication API

Definitions

Service Provider          The syncAccess system. This is the system that is managing the user identity and providing credential authentication.

Consumer/Client         This is the 3rd party system that wishes to leverage the authentication provided by the Service Provider.  This is a website or application that uses oAuth to access the Service Provider on behalf of the user.

User                             The individual account holder whose credentials are managed by the Service Provider.

Client Id                       A value used by the Consumer to identify itself to the Service Provider.

Client Secret               A value used by the Consumer to establish ownership of the Client Id.  In essence, this is the Consumer’s password to the Service Provider.

Request Token            A value used by the Consumer to obtain authorization from the Service Provider and later exchanged for an Access Token

Access Token              A value used by the Consumer to gain access to the protected resources on behalf of the User without the need to know or maintain the User’s Service Provider credentials.

Authentication Process Overview

The authentication process is broken up into 4 steps.

1. Client Authentication

The consumer itself must be authenticated with the Service Provider before any subsequent processing can occur.  This authentication step is hidden from the user and takes place between the Consumer and Service Provider directly.

The Consumer asks the Service Provider for a Request Token which it uses in subsequent requests to the Service Provider.  The Consumer must provide a Client ID and a Client Secret (aka username and password) to the Service Provider before the request token is granted.  The client ID and Client Secret are created by Syncronex and distributed to the Consumer before development work is started.

2. User Authentication

Once the Consumer has been granted a Request Token, it sends the User to the Service Provider for authentication. This is typically an HTTP Redirect to the authentication Uri at the Service Provider. The Service Provider, then, checks to see whether or not the User is currently authenticated (perhaps from a previous authentication session) and, if not, presents the User with a form to get credentials.
The User provides her credentials and is validated by the Service Provider. If she is validated, the Service Provider sends the User back to the Consumer’s site and passes along an authentication ticket.

3. Access Token

At this point, the User has been validated by the Service Provider and the Consumer has been informed of this via the authentication ticket.  If the Consumer needs additional information about the User, it must again interact with the Service Provider and request an Access Token.  This access token allows the Consumer to make additional, secured, requests to the Service Provider for details about the User.

4. Get Resource

The Consumer uses the access token to requests resources (typically user details) from the Service Provider.

Authentication Process Details

This section describes the specific details to use syncAccess Federated Authentication.  Several Url examples will be shown in the form:

https://syncaccess-{company}-{property}.{platform}.syncronex.com/{company}/{property}/oauth/api/{resource}

or

https://{customdomain}/{company}/{property}/oauth/api/

Values within the {…} indicate variable parts of the url and would change based on your specific installation.  When developing client applications, it's recommended you supply these variables from an easily modifiable configuration.

Platform

This will either be stage or blank depending on whether you are pointing to the testing or production servers. For example:

  • Stage: https://syncaccess-sync-test1.stage.syncronex.com/sync/test1/oauth/api/{resource}
  • Production: https://syncaccess-sync-test1.syncronex.com/sync/test1/oauth/api/{resource}

If your instance is employing a custom domain, there may not be a specific platform variable.  For example, a typical custom domain for a production instance might look like https://subscribe.acmenews.com/acme/news/oauth/api/authenticate

Company

This would represent the company designator that Syncronex uses to represent you.

If you don’t know your company and/or property designator, contact Syncronex Technical Support at [email protected]

Property

This will be the specific designator Syncronex uses for the property instance.

Resource

This is either authenticate, authorize, or resource depending on which part of the authentication process you are executing.

Client Authentication

The Consumer must first authenticate to the Service Provider before any user authentication can occur.  This is done by sending a request to the Service Provider and passing in a specific client id and client secret.

You should already have a client Id and client secret from Syncronex.  Contact Syncronex Technical Support at [email protected] if you do not have a client Id and secret.

You authenticate by making an HTTP POST request to: https://syncaccess-{company}-{property}.{platform}.syncronex.com/{company}/{property}/oauth/api/authenticate

The POST body can be JSON formatted or x-www-form-urlencoded and must contain:

  • client_id
  • client_secret

ClientId and Client Secret are case sensitive.  “TestClient” is different from “testclient” so be sure to double check your values.

Example:

POST https://syncaccess-sync-test1.dev.syncronex.com/sync/test1/oauth/api/authenticate
HEADERS: Content-Type:application/json
POST BODY:
{
 client_id:ABC1234,
 client_secret:83B3AB15-7A75-4436-A43C-1A515B67ED52
}

Note: if using Content-Type of: x-www-form-urlencoded, the argument names must be formatted differently:

  • clientId
  • clientSecret

(the underline character (_) must be removed).

The response from the authenticate call will be a JSON-encoded response like this:

{
    request_token: EAAAADwth4fyEuvH64F…WPeGsZKQ=,
    expires: 2014-03-29T23:22:26.241211Z,
    success: true
}

If the authentication is successful, you’ll get the request_token value, an expiration date (UTC) and a flag indicating success.  Errors will result in a success value of “false” as well as an error property that explains the failure.

{
    error: Invalid Client Id or Client Secret,
    success: false
}

User Authentication

Once you have the request token, you can pass the user along to the Service Provider to be authenticated.  This typically involves redirecting the user to the Service Provider’s log in page and passing along information on where to send the user after logon is complete.

The logon page is at https://syncaccess-{company}-{property}.{platform}.syncronex.com/portal/#/fedauthlogin if you are using the default workflow and https://syncaccess-{company}-{property}.{platform}.syncronex.com/{company}/{property}/account/logon if using the legacy workflow (see note below).

You must supply the target page to which the system will send the user once she has authenticated.  Use the returnUrl parameter for this.

returnUrl                       This is the fully-qualified URL to which the user should be sent after a successful authentication to the service provider

Example:

GET https://syncaccess-sync-test1.dev.syncronex.com/portal/#/fedauthlogin?returnUrl=http://my.consumersite.com

NOTE: returnUrl is one of the only case-sensitive URL query parameters you will encounter while working with Syncronex APIs.  It's important in this case that you supply that query parameter exactly as shown here: returnUrl

Note on Legacy Workflow

Contact [email protected] if you are not sure you whether or not you are using the syncAccess legacy workflow.  The location of the logon page is different in the legacy workflow.

The logon page will typically be at https://syncaccess-{company}-{property}.{platform}.syncronex.com/{company}/{property}/account/logon. You must include the redirection Url and an indicator that you are asking for a federated authentication by including the following query string arguments:

returnUrl

Just like above, this is the fully qualified url to which the authenticated user is returned after identification.

op           

This must be fedAuth or fedAuthIdentOnly and tells the Service Provider that the user is logging in as part of a federated authentication request.  The fedAuthIdentOnly qualifier removes the subscription and activation options from the logon page. This is useful when you want to remove clutter from the authentication process.

Example:

GET https://syncaccess-sync-test1.dev.syncronex.com/sync/test1/account/logon?returnUrl=http://my.consumersite.com/processauth&op=fedauth

Once the user has authenticated, the Service Provider will redirect her to the value for returnUrl and will include an encoded authentication ticket on the query string.

GET
http://my.consumersite.com/processauthsp-tk=4C0ADDEBC…64D61911BEC5

Access Token

The Consumer is now ready to request the access token from the Service Provider that will allow the Consumer to request specific details for a given user.

Both the request token and the authentication ticket are required to receive an access token. It’s assumed that the Consumer has taken steps necessary to manage these values throughout this process.

The Consumer requests the access token by executing an HTTP POST request to: https://syncaccess-{company}-{property}.{platform}.syncronex.com/{company}/{property}/oauth/api/authorize and passes in the request token and the authentication ticket in the body of the request.

Example:

POST https://syncaccess-sync-test1.dev.syncronex.com/sync/test1/oauth/api/authorize
HEADERS: Content-Type:application/json
POST BODY:
{
    request_token:EAAAANNoufW8jD9qTFfcLj…lwltrtBQ=,
    authentication_ticket:4C0ADDEBC32…D61911BEC5
}

Note: if using Content-Type of: x-www-form-urlencoded, the argument names must be formatted differently:

  • requestToken
  • authenticationTicket

(the underline character (_) must be removed).

The Service Provider will respond with a JSON-encoded response like this:

{
    Expires: 2014-03-30T04:57:47.506836Z,
    AccessToken: EAAAAJm/7s…cKUA==,
    Success: true,
    Error: null,
    UserName: [email protected]
}

If there are problems retrieving the access token, the Error property will contain a message describing the problem and the AccesToken and UserName properties will be blank.  Success will show ‘false’ in any errors occurred.

{
    Expires: 0001-01-01T00:00:00,
    AccessToken: null,
    Success: false,
    Error: The request token supplied is invalid!,
    UserName: null
}

User Resource

The last step of the authentication process is to retrieve user details using the newly acquired access token. Note that the access token is only valid for a few hours. Once the token expires, you will have to repeat the authentication process to receive a new token.  This makes the token worthless as a means of permanently identifying the user within the Consumer system.  It’s common for the Consumer system to manage a unique identifier for the user within its own system.  This unique identifier can then be used in subsequent processing to associate the user with any records in the Consumer system.

The Service Provider will return details for the authenticated user including a unique identifier that can be stored in the Consumer system.

The Consumer gets the user details via another HTTP POST request to: https://syncaccess-{company}-{property}.{platform}.syncronex.com/{company}/{property}/oauth/api/resource .  The only required data for this call is the newly acquired access token. 

Example:

POST https://syncaccess-sync-test1.dev.syncronex.com/sync/test1/oauth/api/resource
POST BODY:
{
 access_token: EAAAAJ50/H/G/lf…Sevpp9Sgg==
}

Note: if using Content-Type of: x-www-form-urlencoded, the argument names must be formatted differently:

  • accessToken

(the underline character (_) must be removed).

The Service Provider will respond with the user details in a JSON-encoded response like this:

{
    FirstName: Steve,
    LastName: Rogers,
    Email: [email protected],
    Success: true,
    Error: null,
    PhoneNumber: (425) 555-1212,
    Address1: 123 MAIN ST E,
    Address2: APT 10,
    HouseNumber: 123,
    City: NEW YORK,
    State: NY,
    Zip: 10015
}

Any errors will result in the success property returning “false” with a description of the error in the Error property.

{
    FirstName: null,
    LastName: null,
    Email: null,
    Success: false,
    Error: The access token supplied is invalid!,
    PhoneNumber: null,
    Address1: null,
    Address2: null,
    HouseNumber: null,
    City: null,
    State: null,
    Zip: null
}

Testing the Federated Authentication APIs

You can use a tool like POSTMAN to test the Federated Authentication APIs to get a sense for how they work.

You can get POSTMAN here

You’ll need the following to test the APIs:

  1. A Client Id
  2. A Client Secret
  3. A valid syncAccess (Digital Paymeter) instance to test against.
  4. A valid account on that syncAccess system.

Contact Syncronex Support at [email protected] to get set up.

The following examples use POSTMAN but any HTTP client application should work (i.e., curl )

Client Authentication

Create a POST request to your Service Provider instance.

https://syncaccess-sync-test1.dev.syncronex.com/sync/test1/oauth/api/authenticate

Create the POST body using the x-www-form-urlencoded content type and provide your clientId and Client Secret.

Click Send to execute the request.

Save the Request Token value (just the part within the quotation marks) by cutting and pasting into an text editor of your choice.

User Authentication

You can get the authentication ticket by just navigating directly to your Service Provider instance’s log on page.

https://syncaccess-sync-test1.dev.syncronex.com/sync/test1/account/logon?returnUrl=http://google.com&op=fedAuth

(note the returnUrl in the example only serves to give the Service Provider a target for the redirect. You can use any of your favorite sites there).

Logon using an existing Subscriber Account.  You should be redirected to Google.com (or whatever site you used).  Look at your browser’s address bar. You need to get the sp-tk value from the address bar and paste that into your text editor next to the request token you grabbed previously.

Get the Access Token

Now you’re ready to get the Access Token.  Make a POST request to your Service Provider’s Authorize method:

https://syncaccess-sync-test1.stage.syncronex.com/sync/test1/oauth/api/authorize

Create the POST body using the x-www-form-urlencoded content type and provide the Request Token and the Authentication Ticket you saved from step 1 and step 2.

Click Send and copy the AccessToken value that is returned.  It’ll be used in the next step.

Get Resource (User Details)

Finally, make one last POST request to the Service Provider’s Resource method passing in the AccessToken you just received in the last step.

Click Send to retrieve the user’s details.