Implement Intuit single sign-on with OpenID

This topic provides information related to implementing Intuit single sign-on (SSO) using OpenID.  For more information about OpenID, see the OpenID Authentication 2.0 Spec. Intuit single sign-on offers these key benefits:

  • The user only has to sign in once, instead of having to sign in to both your app and to the app store.
  • Regardless of your app's presence on the QuickBooks app store, your app can rely on Intuit's OpenID service for user authentication rather than a customized solution.
  • Click here for information about available Intuit single sign-on models.

​This topic contains the following sections:

Overview

The user initiates the sign in process in one of the following ways:

  • From within the QuickBooks app store: by clicking the Get App Now button for apps accessed from QuickBooks app store app card.
  • Outside of the QuickBooks app store: by clicking the Sign in with QuickBooks button from within your app.

In both cases, if the user is not already logged into their QuickBooks account, they are prompted for their Intuit ID and password. 

Here's what happens next:

One.pngEstablish the association
two.pngAuthentication request
three.pngVerify the claimed identity
four.pngOptional: obtain additional user information.

After successful verification, your app redirects the user's browser back to your app. 

Implementing the OpenID authentication workflow

Intuit OpenID provider URL: https://openid.intuit.com/OpenId/Provider

Your code provides an authentication request to the Intuit OpenID provider service.  Sample requests and responses are provided below to give you an idea of the workflow steps.  

Given the security implications of getting the implementation correct, we strongly encourage you to use community OpenID Authentication 2.0 libraries when interacting with QuickBooks OpenID endpoints. It is a best practice to use well-debugged code provided by others to help protect yourself and your users. 

One.pngEstablishing the association

Click to show details.

An association between the relying party and the Intuit OpenID provider establishes a shared secret between them, which is used to verify subsequent protocol messages and reduce round trips.

Making the request

Initiate the OpenID process by redirecting the user to intuit's OpenID server:

POST https://openid.intuit.com/OpenID/Provider

Here is an example of a complete associate handle request URL:

POST https://openid.intuit.com/OpenId/Provider 
  openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0&
  openid.mode=associate&openid.session_type=DH-SHA256&
  openid.assoc_type=HMAC-SHA256&
  openid.dh_consumer_public=db5AEcO7V%2BQHrCHe%2B4u693uUaC9CrVP6v8Kadkz6zb%2BtBhc
      ZL6bFUFsJT9BXn4vNzCrxYNDARYhr8nsSY2CQkO%2FqicvsHnCdMBSV%2BADiNNjGIyfBBmGVrstcC7%2Bo
      7dSVt%2BnXN4rcbwKegDDm%2F%2FSkk%2F5RjmCCQ17njCiPqHdsD7s%3D

Handling the response

Here is an example of the response received for the above request.

dh_server_public:AKPzQ4bQ2NPhffJ+l4Mu3Wk5UVozrQjzklACgO43cq/UKOB3gmVmQ1V
  BHGDGst2VjmEDRgqXdqT6hkERYRUn0nFew+2xqGuXamjPtmK6Fgi0v0FzCuDVHEuF3+R9R
  bm/ey4wENo0M3t9yRsGyyhK9/b5vJi74VhcpK2OFNYWYd6k
enc_mac_key:bpSnSYfYQgoK5aqbOxZvZhMggtPfSLV4RQEpNErA8UY=
assoc_handle:EP0i!IAAAAB68uD0k0zW2ySHYPVsvjCC-g8VcuEmmxcy472UZoaOxQQAAAAFvg6JpH
  lxBnq5x1udeXl4940HcHZVMmjJ5Af0LEMNSSaI_7anMoCTU9Ne5rX44ZN92izQmTjRHNCcBjRI3Uc9e
assoc_type:HMAC-SHA256
session_type:DH-SHA256
expires_in:1209598
ns:http://specs.openid.net/auth/2.0

two.pngRequesting authentication 

Click to show details.

Once the relying party has successfully performed discovery and (optionally) created an association with the discovered OpenID provider endpoint URL, it can send an authentication request to the OpenID provider to obtain an assertion.

Making the request

GET https://openid.intuit.com/OpenID/Provider

Here is an example of a complete request URL. Use the URL specified in the OpenID URL field in the app settings on the Intuit Developer site for openid.return_to.

GET https://openid.intuit.com/OpenId/Provider 
 openid.ns=http://specs.openid.net/auth/2.0&
 openid.claimed_id=http://specs.openid.net/auth/2.0/identifier_select&
 openid.identity=http://specs.openid.net/auth/2.0/identifier_select&
 openid.return_to=http://www.mydemoapp.com/verifyopenid.htm&
 openid.realm=http://www.mydemoapp.com/verifyopenid.htm&
 openid.assoc_handle=EP0i!IAAAAB68uD0k0zW2ySHYPVsvjCC-g8VcuEmmxcy472UZoaOxQQAAAAFvg6
     JpHlxBnq5x1udeXl4940HcHZVMmjJ5Af0LEMNSSaI_7anMoCTU9Ne5rX44ZN92izQmTjRHNCcBjRI3Uc9e&
 openid.mode=checkid_setup&
 openid.ns.ext1=http://openid.net/srv/ax/1.0&
 openid.ext1.mode=fetch_request&
 openid.ext1.type.FirstName=http://axschema.org/namePerson/first&
 openid.ext1.type.LastName=http://axschema.org/namePerson/last&
 openid.ext1.type.Email=http://axschema.org/contact/email&
 openid.ext1.type.RealmId=http://axschema.org/intuit/realmId&
 openid.ext1.required=FirstName,LastName,Email,RealmId&
 openid.ext1.count.Email=3 

Handling the response

The Intuit OpenId server issues a 302 redirect to the endpoint specified in the openid.return_to parameter in the above request. Here is an example of this response endpoint.  Use the user information returned to this endpoint to provision an account or to map to an existing account.

http://www.mydemoapp.com/verifyopenid.htm?
openid.claimed_id=https%3A%2F%2Fvm-openid.intuit.com%2FIdentity-03d6580f-7f
  a0-4480-8aff-15cbeae3c270&
openid.identity=https%3A%2F%2Fvm-openid.intuit.com%2FIdentity-03d658
  0f-7fa0-4480-8aff-15cbeae3c270&
openid.sig=XZJHFdZsZRms12a9Vux6zr0gm%2BJDB4uXQgoGgUFFe0I%3D&
openid.signed=claimed_id%2Cidentity%2Cassoc_handle%2Cop_endpoint%2Creturn_to%2C
  response_nonce%2Cns.alias3%2Calias3.mode%2Calias3.type.alias1%2Calias3.value.alias1%2
  Calias3.type.alias2%2Calias3.value.alias2%2Calias3.type.alias3%2Calias3.value.alias3&
openid.assoc_handle=EP0i%21IAAAAB68uD0k0zW2ySHYPVsvjCC-g8VcuEmmxcy472UZoaOxQ
  QAAAAFvg6JpHlxBnq5x1udeXl4940HcHZVMmjJ5Af0LEMNSSaI_7anMoCTU9Ne5rX44ZN92izQmTjRHNCcBjRI3Uc9e&
openid.op_endpoint=https%3A%2F%2Fvm-openid.intuit.com%2FOpenId%2FProvider&
openid.return_to=http%3A%2F%2Fwww.mydemoapp.com%3A8011%2Fverifyopenid.htm&
openid.response_nonce=2016-04-11T23%3A33%3A48ZshWIZDhf&
openid.mode=id_res&
openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0&
openid.ns.alias3=http%3A%2F%2Fopenid.net%2Fsrv%2Fax%2F1.0&
openid.alias3.mode=fetch_response&
openid.alias3.type.alias1=http%3A%2F%2Faxschema.org%2FnamePerson%2Ffirst&
openid.alias3.value.alias1=Bob&
openid.alias3.type.alias2=http%3A%2F%2Faxschema.org%2FnamePerson%2Flast&
openid.alias3.value.alias2=Smith&
openid.alias3.type.alias3=http%3A%2F%2Faxschema.org%2Fcontact%2Femail&
openid.alias3.value.alias3=kjonnala%2Beacct1%40gmail.com

three.pngVerifying the claimed identity

Click to show details.

Your code verifies the authentication response is from the Intuit OpenID provider service.  In the OpenID Authentication 2.0 spec, this verification is described in the section, Verifying Assertions

Making the request

Validate the openid.identity returned in the redirect response.

GET https://openid.intuit.com/Identity-03d6580f-7fa0-4480-8aff-15cbeae3c270

Handling the response

Here is an example of the response received for the above request. 

HTTP/1.1 200 OK
<xrds:XRDS
xmlns:xrds="xri://$xrds"
xmlns:openid="http://openid.net/xmlns/1.0"
xmlns="xri://$xrd*($v*2.0)">
<XRD>
<Service priority="10">

<Type>http://specs.openid.net/auth/2.0/signon</Type>

<Type>http://openid.net/extensions/sreg/1.1</Type>
<Type>http://axschema.org/contact/email</Type>
<URI>https://vm-openid.intuit.com/OpenId/Provider</URI>
</Service>

<Service priority="20">
<Type>http://openid.net/signon/1.0</Type>
<Type>http://openid.net/extensions/sreg/1.1</Type>
<Type>http://axschema.org/contact/email</Type>
<URI>https://vm-openid.intuit.com/OpenId/Provider</URI>
</Service>

</XRD>
</xrds:XRDS>

four.pngObtaining additional user information

Click to show details.

The Intuit OpenID service supports the OpenID Simple Registration Extension 1.0 (SREG) and the OpenID Attribute Exchange 1.0 (AX), enabling your code to fetch user data such as the email address from the authentication response.  AX supports the following namespaces:

  • http://axschema.org
  • http://schema.openid.net
  • http://openid.net/schema

For example with axschema.org, your code can fetch the following data:

  • contact/email
  • namePerson
  • namePerson/first
  • namePerson/last
  • intuit/realmId—This field is available when there is an active connection between the realm and the app and when the user is launching the application from the QuickBooks App Store.

For example, specify the following to get the email address of the user's OpenID account with the axschema.org namespace:

   http://axschema.org/contact/email

Note

Intuit does not verify the user email address associated with the user's OpenID account.  Therefore, do not use the email address for authentication and do not link user accounts based on email address.

Adding the Sign in with Intuit button

To enable your user to sign into your app with their Intuit user ID (email) and password, provide the Sign in with Intuit button in your app. Upon clicking this button, the browser is redirected to the Intuit App Center sign-in window, which prompts the user to log in with their Intuit user ID (email) and password. If you're implementing modified Intuit single sign-on, adding this button is optional.

Testing your Intuit single sign-on implementation

For apps published on the QuickBooks app store, the user starts the app subscription and OpenID flow by clicking the Get app now button on the app card for the published app. To simulate this flow before your app is published, perform these steps:

Click here to see process.
  1. From the developer.intuit.com, select the My Apps tab and click on your app. The app's dashboard is displayed.  

  1. In the Test Connections section click on the link labeled Try app in Production (App Store flow). The Create your account dialog is displayed, initiating the Intuit single sign-on workflow. From here your customer can create an account or use their existing Intuit account.

  1. After the user is signed in, the QuickBooks company selector is displayed.  If the user has only one company in his account, this dialog is omitted from the workflow. 

  1. After the user selects a company, the authorize dialog is displayed.

Click Authorize and verify that the app's landing page, as defined with the Launch URL in your app settings, appears.

Intuit single sign-on models

Intuit Developer supports two models of Intuit single sign-on, standard and modified, as described below.

Standard single sign-on

With this model your application is required to implement OpenID in order to allow the customer signing up for your application from QuickBooks Apps.com to sign in directly to your application without being prompted to create a new account or password on your site. The customer signs in only once with their Intuit credentials.

In this model it is mandatory to add the Sign in with Intuit button on all of your sign-in pages. 

Because this flow is easy for customers, it results in more paid customers signing up for your app. We recommend this flow unless you have a very good reason to use the Modified option.

Modified single sign-on

With this model you still implement OpenID, but your application can let a customer create an account on your site for your app’s use. Subsequent sign-ins from QuickBooks Apps.com  honor the OpenID credentials from Intuit and sign the user directly in to your application.

This modified model makes adding the Sign in with Intuit button to your sign-in pages optional.

Use modified Intuit single sign-on if your customers really need to create an identity and password on your site. For example, they need to sign in to your mobile or tablet app.

Which model is right for your app?

When considering which Intuit single sign-on model to implement, consider how your users interact with your app.  With the Sign in with Intuit button, the user only has to sign in once, instead of having to sign in to both your app and to QuickBooks Apps.com. The Sign in with Intuit button is optional with the modified single sign-on model. Here are some use cases for including it in your app:

  • You can create user accounts without an independent username and password in your system when the user's account is created through the Get App Now flow.  In particular for mobile apps, this approach is not recommended. 
  • All your users typically have an Intuit account for an accountant-facing application.
  • Your users spend most of their day in QuickBooks Online, so having the Sign in with Intuit button saves them from having to login again.

OpenID discovery

OpenID discovery is optional for QuickBooks API apps.  Your app may skip the discovery step and send the authentication request to the Intuit OpenID provider URL:

https://openid.intuit.com/OpenId/Provider

If your OpenID library requires your app to perform discovery, then you must specify the XRDS document at the following OpenID discovery URL:

https://openid.intuit.com/openid/xrds

For more information about discovery, in the OpenId Authentication 2.0 Spec this is described in the section, Discovery.

References

Sample OpenID Implementation

OpenID Community Resources

Here are some libraries we recommend:

In the terminology of the spec, Intuit is the OpenID provider and your app is the relying party.

 Got Questions? Get Answers in our developer forums.