Authentication

SASL

HipChat supports authenticating with OAUTH2 tokens using the X-HIPCHAT-OAUTH2 SASL mechanism.

Note

For a technical description of SASL see RFC 4422. For its use in XMPP see RFC 6120 §6.

To authenticate with OAUTH2 you will need a token with at least the view_group scope. If OAUTH2 is supported, the stream features will contain an auth element qualified by the http://hipchat.com namespace:

<stream:features>
  <auth xmlns="http://hipchat.com"/>
</stream:features>

To initiate X-HIPCHAT-OAUTH2 SASL auth the client passes up \x00 + token + \x00 + resource as a Base64 encoded string as part of the SASL client first message:

<!-- Client -->
<auth xmlns="http://hipchat.com" node="http://hipchat.com/client/mac" ver="22" mechanism="oauth2">AGdhcnJldEBoaXBjaGF0LmNvbQBnYXJyZXQAdGVzdA==</auth>

Note the additional “mechanism” attribute. The server then responds with success or an error, as usual:

<success xmlns="urn:ietf:params:xml:ns:xmpp-sasl" jid="1_1@chat.hipchat.com/android" api_host="api.hipchat.com" chat_host="chat.hipchat.com" muc_host="conf.hipchat.com" web_host="www.hipchat.com"/>

Tokens

HipChat uses OAuth 2 Tokens for access to many services (such as for API calls or XMPP authentication when a password is not available). Tokens may be requested or revoked via XMPP by making special IQ requests to the server:

To request an auth token, you may send a query qualified with the http://hipchat.com/protocol/auth namespace to the conference entity. This will return a <token/> element which contains the token iteself and some metadata about the token. For example:

<!-- Client -->
<iq type='get' id='1' to='conf.hipchat.com'>
  <query xmlns='http://hipchat.com/protocol/auth' />
</iq>

<!-- Server -->
<iq type='result' from='conf.hipchat.com' id='1' to='1_1@chat.hipchat.com/mac'>
  <query xmlns='http://hipchat.com/protocol/auth'>
    <token expiration='1395755218' ttl='3600'>EXSFBabokEfqKS9</token>
  </query>
</iq>
stanza:IQ
xmlns:http://hipchat.com/protocol/auth
http:/v2/oauth/token/

Whenever an account is disassociated from a client (eg. the account is deleted from the clients list of accounts), any associated oauth tokens should be invalidated. This can be done by sending a query similar to the following:

<!-- Client -->
<iq type="set" id="1">
  <query xmlns="http://hipchat.com/protocol/auth" action="delete">
    <type>oauth2</type>
  </query>
</iq>

<!-- Server -->
<iq type='result' from='conf.hipchat.com' id='1' to='1_1@chat.hipchat.com/mac' />
stanza:IQ
xmlns:http://hipchat.com/protocol/auth
http:/v2/oauth/token/

Add observers to new client