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.0and OpenID Connect.

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

Overview

qbo/docs/develop/authentication-and-authorization/identity/OpenID1Flow.png

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:

  1. Establish the association.
  2. Authentication request.
  3. Verify the claimed identity.
  4. Optional: 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.

1. Establishing the association

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:

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

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

1
2
3
4
5
6
7
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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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

2. Requesting authentication

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

1
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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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

3. Verifying the claimed identity

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.

1
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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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>

4. Obtaining additional user information

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:

  • 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.