Auth0 is a popular service offering authentication as a service and can easily be connected to be used with Cumulocity IoT as a SSO provider. The following steps will show how to correctly configure both the Auth0 and Cumulocity IoT account.
Prerequisites
- A tenant on Cumulocity IoT. You will need admin access to be able to configure the SSO provider inside Cumulocity IoT.
- A tenant on Auth0. There is a free plan available that supports up to 7000 users and gives all the functionality we need to achieve the joined setup.
Setting up Auth0
Creating an application
The first step in Auth0 is to create an application. We will need a “Single Page Web Application”.
Once created you need to go to the settings page of the application and scroll down to the section of “Application URIs”. There we have to enter the “Allowed Callback URLs”. You will need to add your Cumulocity IoT tenant URL with the path /tenant/oauth here.
Example:
Afterwards scroll further down to the “Advanced Settings” and the “Grant Types” section. We will need “Authorization Code” and “Refresh Token” enabled (the others don’t matter for Cumulocity IoT).
Creating an API
As the next step we need to create an API in Auth0. The identifier will be the “audience” we later need to use to setup the OAuth 2.0 flow.
After the API is created in the settings page of the API we need to enable RBAC and add the permissions into the access token. We also want to allow for a refresh token. This will give us later the possibility to generate the dynamic access rules in Cumulocity IoT based on the permissions we set in Auth0.
Finally we add some permissions to the API. For this example we simply create 2 for demonstration purpose but feel free to create more.
Customising the Access Token
While the default access token is technically sufficient to use Cumulocity IoT we want to add some more fields into it from the Auth0 user for better mapping. Therefore we will need to create an “Action” in Auth0 and add it to the Login flow.
Go to Actions → Library and click “Build Custom”. Here you can enter the following code
exports.onExecutePostLogin = async (event, api) => {
const namespace = 'https://cumulocity';
if (event.authorization) {
// Set claims
api.accessToken.setCustomClaim(`${namespace}/email`, event.user.email);
api.accessToken.setCustomClaim(`${namespace}/username`, event.user.name);
api.accessToken.setCustomClaim(`${namespace}/user_id`, event.user.user_id);
}
};
This will add the email, username and userId of the Auth0 user into the access token so that we can access it in Cumulocity IoT. You can change the namespace but it has to be some kind of URL (otherwise Auth0 will drop it). Also you should avoid dots here as that makes it complicated for Cumulocity IoT to access it via JSONPath.
Once saved you can go to the flows and click on the “Login” flow. Afterwards from the right you can drag and drop the new action into the flow and apply it.
Creating a user
Finally we need a user in our Auth0 account (this is not the user you are currently using to do all the configurations).
Go to User Management → Users and create a new user.
Afterwards we just go into the user details and add the permissions we earlier created for the API.
Setting up SSO in Cumulocity IoT
In Cumulocity IoT we now need to configure the Single sign-on configuration which can be found in the Administration application under Settings → Authentication
Most of the parameters from Auth0 you can find in your Auth0 account when you go to the settings page of your created application. The different URLs you can find there as well under the Advanced Settings under “Endpoints” in the “OAuth” section.
Authorization request
The important part here is adding the audience. The value is what you created in Auth0 for your API. Only if we provide an audience for an API Auth0 will generate a JWT as access token (and Cumulocity IoT needs a JWT as access token).
The state can just be any random string.
Token request
Refresh request
The client_secret you can copy out of the application in your Auth0 account.
Logout request
Basic
The names in the basic sections you can freely choose. You need to ensure that the Redirect URI here also matches what you whitelisted in the application in Auth0
Access mapping
As we forced Auth0 to add the user permissions into the access token we can now use them in the access mapping in Cumulocity IoT. In the token the permissions are represented as a simple array of strings available under the “permissions” key.
Here an example mapping with the roles from earlier
User data mappings
Because we added the action in the Auth0 login flow we also now have some more parameters of the user available that we can use to populate the user in Cumulocity IoT.
Signature verification
The URI for the JWKS you can also find in your Auth0 account, but you can just take it from below screenshot and replace it with your Auth0 domain in the beginning
Testing
Now everything should work 
This is how the generated user after SSO login should roughly look like:
. Or I was too stupid.