OneID for Developers

We started this company because we are all frustrated with passwords.

We all have dozens, if not hundreds, of usernames and passwords. You can’t possibly remember them all, and in today’s social Internet, no password is safe. That’s why we designed OneID: to keep your information secure and under your control, without requiring a password.

With OneID, you can login without a password, fly through a form, and confirm secure transactions. OneID is easy to set up and free to use.

 

What is OneID?

OneID is a platform designed to make secure digital transactions easy for you and your users. With OneID, unique secret keys are generated for each user, and those keys are stored securely on the user's device.

These secret keys are the magic sauce of OneID. With a secret key, OneID can help your users perform many secure transactions with little or no friction, including:

  • authenticating with your app without a password
  • storing and releasing encrypted personal information, like addresses or credit cards
  • verifying two-factor transactions using the OneID app
// simple signin with OneID OneID.signin({ challenge: { "callback" : "/auth" } }, function(response) { // check to see if login worked });
 

Setting up OneID

1. Include the OneID JavaScript API

The OneID JavaScript API is the primary way your app will communicate with OneID. To use it, just include the script from our CDN. Since OneID works by sending messages through the OneID <iframe> channel using the HTML5 Web Messaging API, we recommend that you always load the OneID API from our CDN rather than downloading the file separately.

We do not currently support downloading the oneid.js file, as we continuously add new features to the JavaScript API and may deprecate old features periodically, changing this file along with it.

<script src="//api.oneid.com/js/oneid.js"></script>

2. Install a OneID SDK or Plugin

If you're going to be authenticating users via OneID, then you need some kind of server-side component to sign the OneID request on your end. We've made many SDKs and Plugins to help with this step. These open-source tools rely on our Keychain API, which validates nonces created by OneID using private key cryptography.

Depending on how you configure your server-side components, you will end up with an API endpoint for your application that OneID.signin will use in its challenge option.

$ > npm install oneid

3. Customize your OneID experience

With these components in place, you're ready to start integrating OneID with your users, your forms, and actions that might require additional authentication, like account deletion or large monetary transactions.

/* confirm a transaction via the OneID app */ OneID.confirm("Are you for reals?", function(response) { if(response.confirm) user.wasForReals(); });
 

Under the Hood

 

Authentication

How does it work?

When a user clicks the OneID Sign in button, our JavaScript API triggers a special cryptographic protocol developed by OneID. Multiple parties are asked to "co-sign" a certificate for that user to authenticate with.

  • The device you are currenty using generates a digital signature.
  • The OneID cloud platform generates a digital signature.
  • (Optional) The OneID mobile app generates a digital signature.

The OneID JavaScript API assembles all of these digital signatures into a single certificate which gets released to your website for verification.

If the signatures are valid, you can be reasonably assured that the user authenticating can be signed in.

Easier and More Secure

To the user, signing in to your website is just a single click on the OneID Sign in button.

Under the hood, you are utilizing the most modern advancements in public key cryptography. Even with all the computational resources in the world, it would take a hacker billions of years to successfully crack your account.

On top of that, our "co-sign" approach distributes the risk of a full breach of your account. Even if your laptop gets stolen or the OneID cloud services get hacked, your secrets are still safe.

For privacy reasons, OneID will generate a unique set of public keys for each website you visit. The digital signatures we generate are specific to that website and cannot be phished and used on other websites. This also means you cannot be tracked across multiple sites.

 

Encrypted Data Storage

It's also possible to use your secret key for client-side encryption and decryption of your personal data.

Our JavaScript API lets you access and set key-value attributes for a user. Behind the scenes, this data is being encrypted and decrypted on the user's device. The OneID cloud repository never sees the user's personal data in unencrypted form.

Users are always in control of who gets their personal data. If a site requests access to a user's data, that user must authorize before any data gets released.

When a site asks you for information, such as filling out a form, your browser will download the encrypted information from the OneID servers, decrypt it on the user's device, give it to the website, and then forget it. OneID never sees your information and it is not accessible on your computer after the transaction.

We'll even do automatic formfill for your website. In fact, we liked this feature so much, we built the OneID QuickFill browser extension.

 

Using a OneID account across different devices

You are at your friend's house. You want to sign in to a site with your OneID, but you've never used your OneID account on their machine. How do you get your OneID secret key to that machine?

OneID App

We strongly recommend users download and install the OneID app.

If you have the OneID app, you can access your OneID anywhere. On any device, just navigate to the OneID Dashboard to sign in.

You will be asked to confirm with your mobile device. After you accept, your OneID account will be setup on that device.

When you authorize with your OneID app, behind the scenes we setup a secure channel between your smartphone and your new device. We then move your secrets from your smartphone to your new device.

No mobile device

No mobile device? No problem.

When you create an account, we generate a personalized OneID Key which can easily be written down or stored somewhere like Dropbox.

Even if you have the OneID app setup but lost your mobile device, you can always use your OneID Key as a fallback option to access your account.

 

Authentication with OneID

Once a user has a OneID, they can use it to sign in at third-party websites who implement OneID signin (that's you). Ideally, a user can sign in, link an existing account, or even create a brand new account at your site just by clicking a OneID button. When a user clicks a OneID Sign in button on your page, an authentication event happens at OneID that may or may not ask a user to approve signing on on their OneID app.

 

Signing In

What does it take to implement OneID signin on your site?

<!-- Drawing a OneID signin button on your page --> <div id=”oneid-signin-button”></div> <script type=”text/javascript”> OneID.init({ buttons: { "signin #oneid-signin-button": [{ challenge: { "callback": "/auth/", "attr": "email name" } }] } }); </script>
<!-- Draw your own HTML5 element and use OneID as a callback --> <button id=”oneid-signin-button”></button> <script type=”text/javascript”> $(“#oneid-signin-button”).click(function() { OneID.signin({ challenge: { "callback": "/auth/", "attr": "email name" } }); }); </script>
 

Server-side

The first thing you will want to do is validate the OneID data provided to the callback. You will get up to 3 digital signatures:

  1. AD Signature (from the user's OneID enabled browser, or "active device")
  2. Repo Signature (from OneID's server for this user)
  3. CD Signature (from the user's OneID Remote app, or "control device" (optional))

Each of these keys is cryptographically signed by a private key that is unique to that OneID user at your OneID-enabled site.

How does OneID verify my signatures?

When you call the Keychain API, you pass us the user's UID (unique to that user and to your site), and the up to 3 signatures that OneID has made for you (see above). Along with those 3 signatures, are the public keys for each signature. The Keychain API will keep a record of these public keys, and use them to cryptographically verify the signatures. If all of the signatures are valid, the Keychain API will return true and you can rest assured that the user is valid.

# in Ruby def auth oneid = OneID.new(API_ID, API_KEY) result = oneid.validate(params) render :json => JSON.generate({ "url" => oneid.success?(result) ? "/success" : "/error" }) end
 

What should I do in my callback function?

The example above gives a general purpose flow for what to do on your server-side callback. Each integration is unique, so you may have some unique business rules around account creation and validation on your site. If you have any questions about how to do something, please feel free to open a support ticket to get in touch with us.

  • Verify the OneID signatures (see Keychain section)
  • Determine if a user is signed in to your service already (i.e. is there a current user in my session?)
    • If so, set the UID from the OneID data to the user object and save
    • If no user is signed in:
      • Query your users table for any records where myUserObject.uid = uid
        • If found: load that user up and sign them in locally (i.e., set them as the current user in your session)
        • If no user found:
          • Try to look up a user in your database by some attribute data OneID has provided. For example, many sites use an email address as a unique identifier. You can ask OneID for the user's email address, and use that to look up your users.
            • If found: set myUserObject.uid = uid, save, and sign them in.
            • If not found: Create a new user record with the data provided from OneID and sign them in.
// Using the Node.js SDK client.validate(req.body, function(oneid_res) { if (oneid_res.isValid()) { // If user is signed in to my site // myUserObj.uid = oneid_res.uid; // else if (myUserObj = User.findByUid(oneid_res.uid)) // set user logged in // else if (myUserObj = User.findByEmail(oneid_res.email.email)) // myUserObj.uid = oneid_res.uid; // set user logged in // else // myUserObj = User(); // myUserObj.email = oneid_res.email.email; // myUserObj.uid = oneid_res.uid; res.send(200); } else { // something went wrong res.send(401) } })
 

Attributes

OneID's Attribute features take friction out of your forms. By relying on the client-side keys, OneID is able to safely encrypt and store a user's attributes, releasing the encrypted attributes to the browser, where they're decrypted upon user approval and authentication. With the OneID JavaScript API, you can set, get, auto-fill, and pluck out a user's attributes easily to make their experience with your product a simple, hassle-free one.

OneID stores and serves user attributes securely, using the same public-private key cryptography that drives OneID Authentication. With the 128 bits of entropy we have for this data, we can securely store credit card data, which gives you the opportunity to create single-button checkout experiences for your users.

Unlike other components of OneID, Attribute functions require no backend components on your site. Users must simply be signed in to OneID on the browser that they are currently using in order to decrypt their attributes with the keys in their local storage.

/* retrieve signed in user's data for the name and email cards */ OneID.attr(["name", "email"], function(response) { console.log(response.attribute_data); });
 

Getting and setting attributes

OneID.attr is the most flexible function in our API, and for good reason - you can do tons of interesting stuff with user attributes and information. OneID.attr actually acts as both a getter and a setter for OneID attributes (name, email, phone, employment, address, and payment cards). Users will be prompted to approve transactions from these functions with modals in the OneID <iframe>.

For a full synopsis of the uses for this function, see the full API definition.

// getter OneID.attr("email", callback); // setter OneID.attr({"email[email]": "test@email.com"}, callback);
 

Understanding maps

Maps are the magic sauce behind OneID QuickFill. Our OneID QuickFill browser extension, in essence, is a crowd-sourced generator of OneID maps. These maps have taken a variety of forms as OneID has evolved (most, if not all, of which are currently still supported), but as of now, we recommend a simple map format, described on the right.

A map is simply a JavaScript object which pairs familiar CSS selectors (which can be scoped into a context during the actual API call) to OneID Attributes. The full list of OneID attributes can be found at OneID.attr.

Many functions rely on these attribute mappings. OneID.quickfill uses the mappings to determine which attribute cards to request, and then uses the selectors to determine which elements to fill. OneID.collect uses the mappings to grab values out of currently filled inputs for the sake of creating an account or setting an existing user's attributes using OneID.attr.

var map = { ".my-input": "name[first_name]", "[name='lname']": "name[last_name]", "#another-el": "address[state]" }
 

One-click checkout with QuickFill

OneID.quickfill gives you a simple way to use your authenticated user's information stored inside their OneID. Adding a QuickFill button to your website means that users won't have to type their information at your site every time they want to checkout or complete some other task that requires a form. And, with the OneID QuickFill browser extension, the information the users put into their OneID attribute store can be used all over the web to avoid the hassle of forms.

Using either OneID.quickfill and OneID.attr, you can roll your own one-click checkout using OneID attributes. By requesting extra attr in the OneID.quickfill options, you can even handle multi-page checkout forms by requesting the cards that the page might use and passing the data along into those fields via JavaScript.

The key to this is implementing your form's logic in the callback. This could take many forms, depending on how your forms are implemented. In the example to the right, the callback triggers a submit event on the form. You could also run an AJAX request, completing a multi-page checkout in one fell swoop.

QuickFill Test Form
// create a OneID button which, when clicked, // fills the form and triggers submit OneID.init({ buttons: { "quickfill #quickfill-test-form" : [{ map: { "[name='fname']": "name[first_name]", "[name='lname']": "name[last_name]", "[name='pnum']": "phone[phone]" }, attr: ["address", "payment"], context: "#quickfill-test-form" }, function(response) { if(response) $("#quickfill-test-form").submit(); }] } });
 

Attribute transforms

When getting or setting OneID attributes, you will frequently want a simple way to transform them to ensure they match your system's paradigms. For example, we store all of our states as their Official USPS Abbreviations (e.g., California is stored as CA, Texas is stored as TX). If you ask for an address' state, this is the format we will use when we give the data to you. But what if you use a different format to store your dates (e.g., Magento uses numeric values for their states, California is 12 and Texas is 57). You can solve this data format issue by using the transform option in OneID config.

What do I pass to transform option?

The transform option takes an array of transform objects. Each transform object should contain an attribute name (attr), and at least one transform function (toOneID, fromOneID).

The transform function fromOneID is what you will want to set up for QuickFill and Sign in. They will run behind the scenes every time you ask for attributes. So, in the state example above, you only need to worry about defining the format change once in the OneID.init or in a OneID.config call.

The transform toOneID will run if you are sending data back to OneID (i.e., from a OneID.signup call or a OneID.attr setter call).

The most common transform use cases are

  • US states used in addresses
  • countries used in addresses
  • credit card expiration dates
  • and credit card types
var state_map = { "AL":1, "AK":2, "AS":3, "AZ":4, "AR":5, "AA":7, "AE":9 // etc ... }); OneID.config({ transform : [{ attr : "state", toOneID : function(state_val) { for (state in state_map) { if (state_map[state] == state_val) { return state; } } return null; }, fromOneID : function(state_val){ return state_map[state_val]; } }] });
US states used in addresses

For address states, we use Official USPS Abbreviations (as mentioned above).

{ "AL": "Alabama", "AK": "Alaska", "AS": "American Samoa", //... }
Credit card expiration months

For credit card expiration months, we use integers.

{ 1: "January", 2: "February", 3: "March" //... }
Credit card expiration years

For credit card expiration years we use full 4 digit years.

{ "2013": 2013, "2014": 2014, "2015": 2015, //... }
Credit card types

For credit card types, we use two-character identifiers.

If you have any questions about attribute transforms, feel free to contact support by opening a support ticket.

{ “AE”: “American Express”, “VI”: “Visa”, “MC”: “Master Card”, “DI”: “Discover” }
 

UI Components

 

Buttons

OneID Buttons are instantiated through OneID.config and help provide a quick, painless way to let your users interact with OneID. By using OneID buttons, you can automate the process of binding user actions to OneID API functions. You'll also be provided with branded OneID buttons the match up with these API functions.

Buttons have a format based loosely on Backbone.js Event definitions, which are objects that have a space-separated strings for keys and some kind of mapped behavior as values. For button definitions, we use the syntax {"function selector" : [/* arguments */]}.

Button Demo

If you run the demo to the right, a OneID Sign in button will be appended to the <div> below.

function:

The name of the OneID function being bound to the button. Available for use are the following functions: signin, signup, and quickfill.

selector:

A CSS selector which will be received by qwery. The buttons feature appends a button to each instance of the selector on the page at runtime.

arguments:

An array of arguments to pass to the function when the click event is fired on the button. Generally will contain an options object followed by a callback function. See the individual definitions of the functions in the JavaScript API for more information as to what arguments are required.

<!-- in your HTML: --> <div class="signin-button-example"></div>
OneID.init({ buttons: { "signin .signin-button-example" : [{ "challenge" : { "callback" : "/auth" } }, function (response) { if (response.valid) alert("signed in!"); else alert("no good. :("); }] } });
 

Iframe and Modals

OneID uses an <iframe> injected onto your page to handle communication with the OneID repo. By using the <iframe>, OneID is able to abstract many user interactions, most notably ones around second-factor device approval and user authentication, away from you so that you can quickly sign users in to your app.

Inside the <iframe>, we have a front-end application which handles user input, client-side cryptography, and AJAX requests to the OneID server. It's built on Foundation and we're dedicated to keeping it as slim as possible to keep your page load light. On that note, we also don't load the <iframe> until you call OneID.init or any function that requires the <iframe> channel functionality.

Calling OneID.get("apiReady", callback) will tell you if the OneID <iframe> has been initialized or not.

// attr is a function which requires user // input. The OneID iframe will pop open when // you click "Run." Your actions in the modal // determine what the response will look like. OneID.attr("name", function(response) { console.log(response); });
 

JavaScript API

The OneID JavaScript API is the primary method for communicating with OneID. By using the JavaScript API, your application will have a simple layer of communication with your users' OneID attributes, keys, and devices, which you can use to create a simple, password and form-free experience for your users. Or, augment your current setup and make your users' lives that much easier.

The API works by dropping the OneID <iframe> onto your page. This <iframe> remains hidden unless a non-silent action is requested by your application. The OneID <iframe> references the OneID Internal Client, which contains our cryptography libraries and business logic for encrypting and decrpyting users responses with the OneID keys living in their browsers. Luckily, all you have to do is call the appropriate OneID function, pass some options, and put your app's custom code into the callback function.

// send a message to the user's OneID app, // and respond according the user's input OneID.confirm("Confirm action?", function(response) { if(response.confirm) { app.runTransaction(); } });
 

init()

Initialize the OneID API by inserting the OneID <iframe> onto the page. Options passed in are passed directly to OneID.config.

OneID.init( Function callback )
callback:

A function that will be bound via OneID.once("apiReady").

OneID.init( Object options, Function callback )
options:

See OneID.config for the full list of options.

callback:

A function that will be bound via OneID.once("apiReady").

OneID.init(function() { alert("The OneID API is available!"); });
 

config()

Configure various aspects of how the OneID API interacts with attributes and runs in the browser. Can be set before or after OneID.init is run.

OneID.config( Object options )
options:

buttons - Object which, when config is run, will create a button matching up with a OneID function inside of the element specified with the selector. For more information, read the writeup on OneID buttons.

debug - Boolean to turn on console debug statements

ready - Function that is run on apiReady

transform - Function that transforms attributes released from OneID for the sake of QuickFill.

viewport - Boolean which, if set to false, will prevent OneID from creating a <meta> tag for the viewport if your page doesn't already have one. This meta tag is used to ensure that OneID is usable by your users on mobile devices, and is only used for pages which do not already have any viewport definition. For more information about the viewport, see the MDN article about viewports.

OneID.config({ buttons: { "signup .button-drop .b" : [ function(response) { if(response) alert("signed up!"); } ] } });
Buttons demo:
 

get()

Determine various aspect of the state of this session.

Note: there are many items in the state which are used throughout the external and internal parts of the OneID client which probably aren't very useful for you. Those attributes are not included in the list below for brevity's sake.

OneID.get( String property, Function callback )
property:

State properties referring to the current OneID session.

apiHost - String URL which points to the OneID API host.

apiReady - Boolean which states if the OneID <iframe> has finished loading.

browserSupport - Boolean which indicates if the current browser is supported by OneID.

buildVersion - String which refers to the most recent commit's SHA-1 checksum for the OneID client.

chanReady - Boolean which becomes true when the Channel between oneid.js and the OneID <iframe> has been established.

debug - Boolean, set by OneID.config, that turns on the client's debug logging.

enabled - Boolean which, if true, means that there are OneID keys present in the browser's local storage. Useful if you only want to show OneID functionality if a user already has it.

getMobileUrl - String URL which points to the Apple App Store or the Google Play Store, depending on the user's current user agent.

keychainHost - String URL which points to the Keychain API.

mobileEnabled - Boolean which states if the currently signed in user has set up the OneID account.

oneIdHost - String URL which points to the OneID account and Dashboard.

repoHost - String URL which points to the OneID repository.

signedIn - Boolean which indicates if there is a signed in user.

callback:

Function executed to deliver the state value.

callback( Mixed result )
result:

the state value of the type described above if a property was used. If not, OneID.get will return an Object with all of the state values.

/* check if user is signed in */ OneID.get("signedIn", function(signedIn) { alert(signedIn ? "User is signed in!" : "User not signed in :-("); });
/* see full OneID state */ OneID.get(function(state) { alert("API is at " + state.apiHost); });
 

on()

Bind a callback function to a OneID event.

OneID.on( String event, Function callback )
event:

The event name on which to add the callback.

callback:

The function that should be attached to the event.

callback( Object response )
response:

If the event is attached to an API function (like attr or confirm).

/* func runs every time with on */ var func = function(response) { alert("Run it up, " + response.attribute_data.name.first_name); }; OneID.on("attr", func); OneID.attr("name");
 

off()

Unbind a callback function to a OneID event.

OneID.off( String event, Function callback )
event:

The event name from which to remove the callback.

callback:

The function that should be removed from the event.

/* remove the function before the event gets fired */ var func = function() { alert("I'll never run!"); }; OneID.on("attr", func); OneID.off("attr", func); OneID.attr("name", function() {});
 

once()

Bind a callback function to a OneID event for a single instance of that event.

OneID.on( String event, Function callback )
event:

The event name on which to add the callback.

callback:

The function that should be attached to the event.

callback( Object response )
response:

If the event is attached to an API function (like attr or confirm).

/* event only fires the first time */ var func = function(response) { var name = response.attribute_data.name.first_name; alert("YORO (you only run once), " + name); }; OneID.once("attr", func); OneID.attr("name", function() { // alert won't run this time because // it was attached with once OneID.attr("name", function() {}); });
 

signin()

Signs user into this site, which subsequently signs them into the current browser if they weren't already. The challenge object is used as the definition for how the authentication should occur both in the OneID repo and the server. For more information about challenges, read the Authentication tutorial.

OneID.signin( Object options, Function callback )
options:

challenge - Object A OneID challenge object, which contains a callback to your server.

callback:

Callback function to execute when signin is complete

callback( Object response )
response:

Object returned from your server following the challenge response.

OneID.signin({ challenge: { "callback": "/auth" } }, function(result) { // success! });
 

signout()

In all likelihood, you do not really want to call OneID.signout. More than likely, you should just be running your own signout logic without touching OneID.

Signs user completely out of their OneID on the current browser. This particular function will require you to handle your own site signout, should you want to concurrently do that. You can place this logic within the callback.

OneID.signout( Object options, Function callback )
callback:

Callback function to execute when signout is complete

callback( Boolean response )
response:

True if signout was successful and null if signout failed

OneID.signout(function(response) { if(response) { alert("signed out!"); // sign user out of your website now // User.signout(); } });
 

signup()

Creates a OneID and signs the user into this browser. If a challenge is provided in the options, then OneID will attempt to authenticate the signin to your site's callback as well, simulating the action of OneID.signin after provisioning is complete. For more information, see the Authentication tutorial.

OneID.signup( Object options, Function callback )
options:

challenge - A OneID challenge object for signin

silent - If userData is set, create an account from the data passed with no modals

userData - A dictionary of user attributes to create the account with

callback:

Callback function to execute when provisioning is complete.

callback( Boolean result )
result:

True if signup was successful and null if signup failed.

OneID.signup({ userData: { name: { first_name: 'Jane', last_name: 'Doe' }, email: { email: 'jane.doe@gmail.com' } }, }, function(result) { // True or null });
 

optout()

If an account was created silently for a user, give them the opportunity to delete that OneID if they have not already opened the OneID Dashboard and the OneID account welcome email has not yet been dispatched. The OneID account welcome email is currently set to dispatch 10 minutes after an account is created.

OneID.optout( Function callback )
callback:

Callback to execute once the account has been deleted.

// OneID.signup({ ... }, function() { ... }); // user indicates they do not want their OneID account OneID.optout(function( result ) { if(result) { // user account has been deleted } });
 

confirm()

Wrap a transaction on your site in a OneID app Confirmation message. The user will receive a push notification on their mobile device which contains the message. Your response will indicate if the user accepted, rejected, or ignored the message.

OneID.confirm( Object options, Function callback )
options:

message - String to be used on the OneID app's approval message

silent - Boolean indicating whether or not the OneID <iframe> should pop open with the "Check Your OneID App" dialog.

callback:

Callback to execute once confirmation is complete on the mobile device.

callback( Object response )
response:

Object with key Boolean confirm, which is true if the user hit "Approve" and false if the user hit "Reject." response is null if there was an error, including if the user has no mobile app setup.

OneID.confirm("Approve me?", function(response) { if(response) { alert(response.confirm ? "accepted!" : "rejected :-("); } else { alert("There was an error, or the user doesn't have a 2FA device."); } });
 

attr()

OneID.attr is a getter and setter for OneID attributes. The flexible signature for calling OneID.attr makes it feel as natural as jQuery's attr function.

It seems obvious, but calls to OneID.attr's getter can only return information that the currently signed in user has stored with OneID. For example, if you make a request such as OneID.attr("payment", function() { ... }), OneID will only be able to return payment information if the user has entered that information into their OneID. The callback for OneID.attr will always receive an object, but if a card that was requested is missing, it will not be present in the attribute_data dictionary.

getter

OneID.attr( String name, Function callback )
name:

Attribute name to get from default card

callback:

Callback function to return the requested attributes.

OneID.attr( String[] names, Function callback )
names:

An array of attribute names to get from default card

callback:

Callback function to return the requested attributes.

callback( Boolean result )
result:

address - City, country, phone, state, street, street2, zip code, and phone number from the default card

company - Employer and occupation from personal information

email - Default email address from personal information

name - First and last name from personal information

payment - Credit card number, type, expiration month, year, and name on card from the default credit card

phone - Default phone number from personal information

setter

OneID.attr( Object attr, Function callback )
attr:

Object which includes attributes cards of OneID attributes

callback:

Callback function with response which returns an Object if successful and null if the transaction is canceled.

// retrieves the name OneID.attr('name', function(response) { // alert(response.attribute_data.name.first_name); });
// retrieves default data across all attributes var cards = ['address', 'company', 'email', 'name', 'payment', 'phone']; OneID.attr(cards, function(response) { // alert(response.attribute_data.phone.phone); });
// setter OneID.attr({ "address" : { "street": "123 Easy St.", "city": "Austin", "state": "TX", "zip": "78702" } }, function(response) { if(response) alert("card created!"); });
 

quickfill()

OneID.quickfill, like OneID's browser extension of the same name, uses OneID.attr to fill forms based on OneID map objects. For more info about QuickFill, please see the Attributes tutorial.

OneID.quickfill( Object map, Function callback )
map:

OneID map Object which maps CSS selectors to OneID attributes.

callback:

Function to execute when form fill is complete.

OneID.quickfill( Object options, Function callback )
options:

attr - array of extra attributes to retrieve from OneID, passed into callback.

context - Element or CSS selector String within which quickfill will look for the OneID map selectors. Defaults to the document.

map - OneID map Object which maps CSS selectors to OneID attributes.

silent - Boolean which determines whether or not the OneID.attr modal appears. Defaults to false.

triggerEvents - Boolean which determines whether or not click, focus, blur, and key events will be simulated during the fill. Useful if your validation depends on such events. Defaults to false.

callback:

Function to execute when form fill is complete.

OneID.quickfill({ "[name='first-js-api']": "name[first_name]" }, function(response) { // console.log(response); });
Example Form:
 

collect()

OneID.collect is a utility for OneID attributes and provisioning which, given a OneID map Object, creates a response Object which OneID can use to set user attributes during the provisioning process, or through the setter version of OneID.attr.

OneID.collect( Object map, Function callback )
map:

OneID map Object which maps CSS selectors to OneID attributes.

callback:

Function to execute when collection is complete. Collected data will be in the Object response.

OneID.collect( Object options, Function callback )
options:

context - Element or CSS selector String within which quickfill will look for the OneID map selectors. Defaults to the document.

map - OneID map Object which maps CSS selectors to OneID attributes.

save - Boolean which, if set to true, will pass the results of the collect straight into OneID.attr

callback:

Function to execute when collection is complete. Collected data will be in the Object response.

OneID.collect({ "[name='first-js-api-collect']": "name[first_name]", "[name='last-js-api-collect']": "name[last_name]", }, function(response) { // console.log(response); });
Example Form:
 

Keychain API

OneID verifies any given secure transaction using three signatures. Each signature is made up of a unique nonce value (current timestamp + some random characters), signed by a private key that is unique to a OneID user on your site.

The signatures are:
  1. AD Signature (from the user's OneID enabled browser, or "active device")
  2. Repo Signature (from OneID's server for this user)
  3. CD Signature (from the user's OneID Remote app, or "control device" (optional))

To make things easier on you, we provide a service that will do the cryptographic signature validations on these signatures. Instead of having to write the code to validate these signatures and keep track of the public keys, we provide one for you called the Keychain service. If you are interested, we have designed OneID in a way to let you do all of the signature verification yourself. Please open a support ticket if you would like more information on how to do that.

Keychain API Endpoint:

https://keychain.oneid.com/
 

/register

To call our OneID Keychain API, we require an API ID and an API Key. Examples of how to use these values are included in each of our language SDKs. You can get an API ID and API key by visiting https://keychain.oneid.com/register. This will return an API ID and Key for you to use, in a JSON format.

GET https://keychain.oneid.com/register
curl https://keychain.oneid.com/register
 

/validate

Validate is what you will call in order to check the integrity of the 3 signatures referenced above. From a OneID Authenticate (or OneID.confirm) payload that's sent to your server, you should send the nonces value as well as the UID.

POST https://keychain.oneid.com/validate
parameters:

HTTP Authorization Header - Contains a ':' seperated API_ID and API_KEY; for example: "{API_ID}:{API_KEY}". See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8 for more about Authorization headers.)

HTTP Body - Contains the OneID payload returned from the OneID.signin callback defined in the JavaScript API.

response:

errorcode - 0 is a successful validation of the OneID payload, nonzero values mean the payload did not validate.

error - "success" is a successful validation, otherwise a detailed message about why the OneID payload did not validate.

valid_signatures - A list of strings containing the individual keys which validated. Useful for debugging purposes.

attr_claims - (Advanced) Used for validating email claims.

curl -u "76624126-1fdf-49bd-80ac-e2d204efa010:rNcRrKH+krJben1MxcA8Ew==" \ -d '{ "uid": "BgAgUEDyTuWHOdBSnHzgwA==", "nonces": { "repo": { "nonce": "eyJhbGciOiJFUzI1NiJ9.eyJub25jZSI6ICIwMDEyMDEzLTA4LTIyVDIyOjI0OjQ0WnpNMk9nYiJ9.ZzwJXGQQjozl6NVChu-3g-FeIEKT-w5gOCceJGHNyJ5-dBf2gTetWQok98DZBY_Mb7yzY_gjtVkjUcEWTl2O3A", "key": "bkqFVCYlIkrHTca6dQKQovtTfJUxXxyRmkf5RlzpO0Hi_Q-8tvNpB5WTI-j9OsqCFAtiGZ6KClnzMm2TmlmikQ" }, "ad": { "nonce": "eyJhbGciOiJFUzI1NiJ9.eyJub25jZSI6IjAwMTIwMTMtMDgtMjJUMjI6MjQ6NDRaek0yT2diIn0.MwKWxc18qe12wFpnkAJzeY9zqNuvdyFhVp1A12Ya3Vvqlm3Bdp4Q1JF66ikh1J-ZFGikLWfE2NY7B3C0bQT8qA", "key": "qDORKZ2ZqfwrqQVBqpO62hJgSc5S/r7FShdtOlAZRFwequg5YtobmAuwzd63Ul1Bqce89g3uQFM2d6+i00hKjA" } } }' \ https://keychain.oneid.com/validate
 

SDKs

In order to make integrating OneID Authentication as simple as possible, OneID has created a number of language-specific SDKs for the sake of validating authentication calls using the Keychain API. Many of these SDKs are available via their respective package management tools, e.g. Node Package Manager or gem.

 

ASP.Net (on Github)

Please see the code on Github for more information, examples, and the code for the ASP.Net OneID SDK.

 

Java (on Github)

We recommend setting up with Maven.

mvn clean install

That will install our SDK into your .m2 directory. Then you can just include us as a dependency in your project:

<dependencies> <dependency> <groupId>com.oneid.rp</groupId> <artifactId>oneid-sdk</artifactId> <version>1.0-SNAPSHOT</version> <scope>test</scope> </dependency> </dependencies>

If you don't use Maven, you can just run: mvn clean package, and then reference the jar in your project: oneid-sdk-1.0-SNAPSHOT.jar in target/.

import com.oneid.rp.OneIDClient OneIDClient client = OneIDClient(apiKey, apiID); client.validate(payload);
 

Node.js (on Github) (on NPM)

The OneID SDK for Node can be installed using NPM or by downloading it from the repository.

$ > npm install oneid

Simply require the 'oneid' SDK from inside your Node application.

var oneid = require('oneid')

If you've already obtained OneID API credentials, create your client using the oneid.getClient() method.

var client = oneid.getClient(API_ID, API_KEY)

Otherwise, don't use any parameters and then use the register() method to generate some fresh credentials.

var client = oneid.getClient() client.register(function(response) { client.setCredentials(response.API_ID, response.API_KEY) })

Then set up a route in your Node application that matches the challenge callback used by the OneID JavaScript API.

app.post('/auth', function(req, res) { client.validate(req.body, function(oneid_res) { if (oneid_res.isValid()) { res.send(200) } else { res.send(401) } }) })
 

PHP (on Github)

The OneID PHP SDK powers the Magento and WordPress plugins. It, like the rest of the SDKs, is a wrapper around the Keychain API that you can use to link and unlink users from their OneID accounts.

To include the PHP SDK, place the code snippet found to the right at the top of each file on which you wish to use OneID. Keep in mind that the argument to require_once() must be a path to oneid-php-sdk/oneid.php.

For a full example of how to use the PHP SDK, please see the examples on Github.

<?php require_once("oneid.php"); $oneid = new OneID(); $response = $oneid->response(); if($oneid->success($response)) { // You now have access to OneID Attributes, // such as the following: $oneid_email = $response['attr']['personal_info']['email']; $oneid_user_id = $response['uid']; } else { // clear links that have already been set, // such as values from the SESSION } ?>
 

Python (on Github)

In order to make development easier for your Python projects, we've provided a SDK to help take care of the server-side validation for sign in.

The Python SDK contains oneid.py and an example using Flask. The demo to the right is a sample Flask route that receives the response from OneID.signin, checks it with the Keychain API, and then redirects to the Flask url for "account" if the signin was valid.

from lib.oneid import OneID @app.route("/oneid/validate", methods=["POST"]) def oneid_login(): ctx={} oneid_data = request.form.get("json_data", {}) oneid_connector = OneID(ONEID_API_ID, ONEID_API_KEY) valid = oneid_connector.validate(oneid_data) if oneid_connector.success(valid): session['uid'] = valid["uid"] session['logged_in'] = True return redirect(url_for("account")) return render_template('index.html', **ctx)
 

In order to make development easier for your Ruby projects, we've provided a SDK to help take care of the server-side validation for sign in.

To the right is an example for setting up OneID for use with Ruby on Rails. To use the SDK, you'll need to create a controller which provides a URL endpoint to OneID.

# controller def auth oneid = OneID.new(API_ID, API_KEY) result = oneid.validate(params) render :json => JSON.generate({ "url" => oneid.success?(result) ? "/success" : "/error" }) end

You'll then need include the OneID JavaScript API and create a call to OneID.signin inside of your view. Your callback to OneID.signin would redirect to response.url, but you could also support a more AJAX-y setup by passing back other information in the JSON to be handled inside of the signin callback.

// in the view OneID.signin({ "challenge": { "callback" : "/auth" } }, function(response) { window.location = response.url; });
 

Plugins

In addition to our language-specific SDKs, we've also created OneID Plugins to make integrating with popular platforms as simple as possible. We'll be adding more, so make sure to keep up with OneID on Github.

 

Magento (download plugin)

Do you run an ecommerce site powered by Magento? If so, we have an extension listed on Magento Connect that will enable all that OneID has to offer : signin, quickfill, checkout. Installation is as simple as installing via the Magento Connect manager, and possibly changing your site's theme in a few places to draw OneID Sign in buttons.

To install:

  1. Follow the directions for installing a Magento Connect extension.
  2. Once you've gotten to the Magento Connect page on your site, and you are prompted to enter an Extension Key, use http://connect20.magentocommerce.com/community/OneID
    • During the Installation process, the Magento extension will get a OneID API Key for you.
  3. The extension is now installed, but you may need to do a little theming work to put OneID into your custom theme.
    • There are some pointers inside of the file app/code/community/OneID/README.txt
    • You can also reach out to us by opening a support ticket for assistance in getting OneID hooked into your store's theme.
 

WordPress (download plugin)

The OneID Plugin can be downloaded from the WordPress Plugin Directory. After you've installed the plugin, click Activate for the OneID Sign in plugin in the WordPress Plugins menu.

If you already have your own API ID and Key pair, you can navigate to the Settings->OneID page and place them in the appropriate labels input fields. Otherwise, a fresh pair will have been already generated for you. If one or both of these values get accidentally deleted then simply go to the Plugins menu, deactivate the OneID Sign in plugin, and then activate it again. This will generate new values for you.

In the Settings → OneID, you can decide whether the default username for your prospective users should be their email address, or if it should be a string in the format FirstName_LastName. Additionally, you can require a user to have a verified OneID email address before using their OneID to sign into your site.

Linking

End users of the plugin can link their OneID to your WordPress site in a variety of ways.

If you do not already have a OneID, then go to the sign in page for this WordPress site and click the OneID Sign in button. You will be prompted to make a new OneID user by filling in your name and email address into an iframe that appears on the same page. After doing so, if the email you entered matches your WordPress account email, then you will be prompted to enter your WordPress username and password to complete the link. Afterwards, you should be able to sign in to this WordPress site simply by clicking the same OneID Sign in button.

Note: If you enter a different email than your WordPress email in the OneID registration form, then the system may think that you are trying to create a brand new WordPress account (provided that email has not already been taken) and you will be signed in to a brand new account.

If you already have a OneID and need to connect it to an existing WordPress account, then you first need to log in to WordPress with your username and password. Then, go to your user profile page and click the Link your OneID button. You should then be able to sign out of WordPress and sign back in using your OneID. Note: By linking the currently signed in OneID to a WordPress account, you will also be unlinking that OneID from any other WordPress account. This is for your, and WordPress', security.

You may unlink your OneID from your signed in WordPress account by going to your user profile page and clicking the Unlink your OneID button.

 

Support

If you're looking for help implementing OneID on your platform, look no further. We've got you covered.

 
 

Get In Touch

Can't find the answers you're looking for in the above links? Try getting in touch with us directly.

Submit a help request / Check on an open help request

Developer Forums

Developer Feedback

Or give us your feedback by sending your question, comment, or suggestion in an email to support@oneid.com.

Find us in #oneid on Freenode IRC.

Have code to share with us? Post it here!