OpenID 2.0

Note

This content is provided as a reference for existing apps that implement OAuth 1.0a and OpenID 2.0. New or existing developers with no previous apps must implement OAuth 2.0 and OpenID Connect.

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.

    OpenID discovery

    OpenID discovery is optional for QuickBooks Online 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:

     

    Note

    These libraries are not by default configured for servers with multiple instances. If you use these libraries, and your server is behind a load balancer, additional configuration may be required.

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


    Did you find this page helpful?
    Your feedback helps us make our docs better. Please let us know if this page helped you, or if it needs improvement.

     Got Questions? Get Answers in our developer forums.