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:
This topic contains the following sections:
The user initiates the sign in process in one of the following ways:
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:
|Establish the association|
|Verify the claimed identity|
|Optional: obtain additional user information.|
After successful verification, your app redirects the user's browser back to your app.
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.
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.
Initiate the OpenID process by redirecting the user to intuit's OpenID server:
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
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
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.
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
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
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.
Validate the openid.identity returned in the redirect 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>
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:
For example with axschema.org, your code can fetch the following data:
For example, specify the following to get the email address of the user's OpenID account with the axschema.org namespace:
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.
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.
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:
From the developer.intuit.com, select the My Apps tab and click on your app. The app's dashboard is displayed.
Click Authorize and verify that the app's landing page, as defined with the Launch URL in your app settings, appears.
Intuit Developer supports two models of Intuit single sign-on, standard and modified, as described below.
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.
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.
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:
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:
If your OpenID library requires your app to perform discovery, then you must specify the XRDS document at the following OpenID discovery URL:
For more information about discovery, in the OpenId Authentication 2.0 Spec this is described in the section, Discovery.
Got Questions? Get Answers in our developer forums.