If you use Auth0 to authenticate your users, you can use the same authentication to log users into Xkit to connect other apps to yours.

🚧

Scopes not supported

Xkit's token authentication does not validate the scopes field, so any valid token, regardless of scopes will be accepted.

To set up Auth0 with Xkit, use the following steps:

1. In the APIs section of the Auth0 Dashboard, Click "Create API" or click on an existing API you'd like to re-use for Xkit.
2. Leave the Signing Algorithm as RS256.
3. Make note of the value in the "Identifier" field.
4. Click "Create" (if working with a new API)
5. Click on Settings in the left sidebar of the Xkit dashboard and scroll down to "User Tokens"
6. Click "Add Custom Issuer"
7. For the "iss Claim", use the value https://<YOUR_DOMAIN>/ where <YOUR_DOMAIN> is your Auth0 account domain (ex. myaccount.auth0.com)
8. For the "aud Claim", use the API Identifier you noted in #3.
9. For the "User ID Claim", keep it as sub to use the standard Auth0 identifier, or if you have included your User ID as a separate, custom claim, input that field here.
10. Optionally for the "Friendly User Name Claim" use the value email, or if you have another name for your user that is more meaningful in a custom claim, input that field here.
11. For the "JSON Web Key Set URL", use the value https:///<YOUR_DOMAIN>/.well-known/jwks.json where <YOUR_DOMAIN> as defined in #3.
12. Click "Save"

Your Xkit installation will now be able to use your Auth0 ID tokens to login to Xkit.

🚧

Add the API audience when authenticating

Your token will only work to authenticate with Xkit if it includes the audience specified in Step #3. See the Auth0 Docs for more information.

An example usage is below:

import createAuth0Client from '@auth0/auth0-spa-js'
const config = {
  domain: <YOUR_DOMAIN>,
  client_id: <YOUR_CLIENT_ID>,
  audience: <IDENTIFIER FROM STEP 3>
}

// Note: login with Auth0 is not handled here for brevity
async function setupAuth0 () {
    const auth0 = await createAuth0Client(config)
  
  const isAuthenticated = await auth0.isAuthenticated()
  
  if (isAuthenticated) {
      const token = await auth0.getTokenSilently()
    await window.xkit.login(token)
  }
  
  return auth0
}

User Groups

To take advantage of the User Groups feature, you'll need to add a custom claim to your token indicating the unique identifier of the group your user belongs to. Then you can add that claim to your Custom Token Issuer settings under "Group ID Claim".

Further Reading

For more details about this process, check out the Custom Token Issuer Guide on Xkit and the Verify JSON Web Tokens documentation on Auth0.