Skip to main content

Auth0

TakeShape supports auth0 for authenticating external users. After adding your auth0 service to TakeShape and configuring your application in auth0, you'll be able to create special queries and shapes that leverage the data in auth0-issued JSON Web Tokens to tailor the experience of your site users. With relatively little effort you'll have fully functional user accounts on your TakeShape project.

tip

Check out our Auth0 Starter Project for a comprehensive look at how you can incorporate Auth0 authentication into your TakeShape project.

Getting Started#

To get started, you'll need an auth0 account and an active TakeShape project. Auth0 provides several sample applications, which can be adapted to connect to TakeShape as an external API. Once everything is configured auth0 will be issuing your application a JWT, which is sent to TakeShape as a Bearer token, validated by TakeShape and made available to your custom queries. TakeShape will not have access to your auth0 user's passwords, and will only be able to read the base and custom claims you make available on your tokens.

Creating an Auth0 Application#

On your auth0 management page, go to Applications. Create or edit and application and fill in the values appropriately for your project. The important item to copy from this page is your auth0 domain. This domain might be the randomly assigned auth0 account ID, or you may have set up a custom domain.

Creating a TakeShape Service Connection#

In your TakeShape project, go to Schema and click Connect Service. Choose auth0 as the service provider and then fill out the configuration screen, using the domain you copied from auth0.

Note an audience has been created for you. You'll need to provide this url to auth0 in order to create a unique connection that TakeShape can validate. This audience also contains the name of your TakeShape service, so if you delete it, you will effectively invalidate all your auth0 tokens that were signed for this audience. This is an important safeguard to prevent unintended access.

Click save when you've copied the audience and have finished. You can always return to this screen later.

Creating a TakeShape Role For Your Auth0 Connection#

In order for your Auth0 connection to provide access to API resources you'll need to create a custom role and add permissions to it. Most importantly, you'll need to take advantage of the role conditions to ensure that requests coming through with Auth0 claims get this custom role assigned to them. That can be done simply with this JSON snippet:

{
"StringEquals": {
"claims:provider": "auth0"
}
}

Creating an Auth0 API Connection#

In Auth0, go to Applications > APIs then click Create API. On the next screen use the audience from TakeShape as the Identifier and be sure you use the default RS256 encryption algorithm.

Now you're ready to test your connection! Go to the Test tab for your API connection, and copy the provided curl command shown at the bottom of the page.

Paste the copied command into your terminal and replace http://path_to_your_api/ with https://api.takeshape.io/project/{YOUR_PROJECT_ID}/auth/me.

Run the edited command.

If the test succeeds your claims will be echoed back to you with additional data TakeShape uses internally to handle the claims.

Running this command uses a special machine-to-machine access token in the request that validates that the service is configured correctly and TakeShape is processing tokens from auth0.

Remember, all the data in a JWT is effectively public, so nothing in this token or in your auth0 data model should be considered sensitive.

Here's a sample of the request and expected response.

Incorporating Auth0 Claims#

Your Auth0 token will provide a number of claims. In short, these are data points from your verified Auth0 token. They are customizable, so they won't be the same for everybody, but generally you'll have the base Auth0 claims as well as the userinfo available.

Base Claims#

A full set of Auth0 base claims might look like this:

{
"iss": "https://dev-cy9w1mxg.us.auth0.com/",
"sub": "auth0|60845b2cb1cc580071d093dc",
"aud": [
"https://api.takeshape.io/project/5a0614fc-9519-4dbe-976a-99622dc4fe37/auth-0",
"https://dev-cy9w1mxg.us.auth0.com/userinfo"
],
"iat": 1622670727,
"exp": 1622757127,
"azp": "1VyUowW88mxDvmmhWeaSyVv5FJRqE9IK",
"scope": "openid profile email",
"sub": "auth0|60845b2cb1cc580071d093dc",
"nickname": "michael",
"name": "michael@takeshape.io",
"picture": "https://s.gravatar.com/avatar/ada2b620bdb3e2c0e61ebbf074e02854?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fm.png",
"updated_at": "2021-05-25T13:48:48.540Z",
"email": "michael@takeshape.io",
"email_verified": true
}

Custom Namespaced Claims#

You also have the ability to add special namespaced custom claims using the namespace https://takeshape.io. If you add these claims to your Auth0 token they will be available in a special, nested custom property. For example, the custom claim https://takeshape.io/favorite_color will be available as claims.custom.favorite_color.

Sample Use of Claims in Schema#

You can now incorporate Auth0 claims into your schema. The following sample code shows how you might use claims.sub to prepopulate an ID value for mutating and querying profile data that is stored in a TakeShape shape called Profile.

{
"queries": {
"getMyProfile": {
"shape": "Profile",
"resolver": {
"name": "takeshape:find",
"service": "takeshape:local",
"options": {"model": "Profile"},
"argsMapping": {"where.id.eq": [["get", {"path": "claims.sub"}]]}
},
"description": "Get a profile using a claim."
}
},
"mutations": {
"createMyProfile": {
"shape": "Profile",
"resolver": {
"name": "takeshape:create",
"service": "takeshape:local",
"options": {"model": "Profile"},
"argsMapping": {"id": [["get", {"path": "claims.sub"}]]}
},
"description": "Create a profile, id'd by a claim.",
"args": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
}
}
}
}
}
}