Authenticating APIv2 calls with JWT - HL Vanilla Community
<main> <article class="userContent"> <p>You can use Higher Logic Vanilla's <strong>JWT</strong> addon to authenticate against the API v2, in addition to the normal web SSO flow.</p><h2 data-id="what-is-a-jwt">What is a JWT?</h2><p>JWT stands for <strong>JSON Web Token</strong>. JSON Web Tokens are an open, industry-standard <a href="https://tools.ietf.org/html/rfc7519" rel="nofollow noreferrer ugc">RFC 7519</a> method for representing claims securely between two parties. In order to use this authentication, you must create a JWT and pass it as a bearer token for API calls. For more information about JWTs, see <a href="https://jwt.io/" rel="nofollow noreferrer ugc">jwt.io</a>.</p><h2 data-id="required-jwt-information">Required JWT information</h2><p>Let's look at the specific information you'll need for the JWT.</p><h3 data-id="header">Header</h3><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">typ</code> - Hardcoded to <strong>JWT</strong>.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">alg</code> - One of three valid HMAC hashing algorithms. We support: <strong>HS256</strong>, <strong>HS512</strong>, and <strong>HS384</strong>.</li></ul><h3 data-id="payload">Payload</h3><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">iss</code> - The issuer (usually the domain of the Authentication Provider).</li><li><code class="code codeInline" spellcheck="false" tabindex="0">sub</code> - A unique identifier passed that will always accompany the user when they log in. This is the <code class="code codeInline" spellcheck="false" tabindex="0">UniqueID</code> in regular SSO.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">aud</code> - The intended audience (usually the URL of the community).</li><li><code class="code codeInline" spellcheck="false" tabindex="0">email</code> - The email address of the user.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">displayname</code> - The username to be displayed on the site.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">exp</code> - The expiry time of the token (unix time stamp).</li><li>Either <code class="code codeInline" spellcheck="false" tabindex="0">iat</code> or <code class="code codeInline" spellcheck="false" tabindex="0">nbf</code> - Unix time stamp when the token was created. We will reject any token that doesn't have one or has one set in the future.</li></ul><p>The payload can optionally include:</p><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">picture</code> - The URL of a profile picture displayed on the site. If one is not present, the user can upload one afterwards.</li></ul><h2 data-id="signing-the-jwt">Signing the JWT</h2><p>You sign your JWT with the same secret in the JWT settings. </p><p><strong>🛑 IMPORTANT</strong>: Make sure this secret stays on your server or else your authentication may become compromised. If your secret ever gets leaked, we strongly recommend changing it immediately.</p><h2 data-id="passing-the-jwt-to-api-calls">Passing the JWT to API calls</h2><p>You pass the JWT in the header as an <a href="https://tools.ietf.org/html/rfc6750" rel="nofollow noreferrer ugc">RFC 6750</a> bearer token in the <code class="code codeInline" spellcheck="false" tabindex="0">Authorization</code> header:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">Authorization: Bearer <JWT Here> </pre><p>Note the space between the word "Bearer" and the actual JWT.</p><h2 data-id="using-a-jwt-without-sso">Using a JWT without SSO</h2><p>Sometimes you may use another SSO method for the web flow, but still want to use a JWT for API calls.</p><p><strong>📝 NOTE</strong>: Currently, there's no official way to disable the regular JWT SSO, but if your main SSO method is set to the default you won't see the JWT sign in button on your site. We will be adding a config option to disable the JWT SSO web flow in the near future.</p> </article> </main>