Client Credentials Rules in Auth0

clientcreds.md

This is preliminary feature to add rules into the Client Credentials exchange pipeline (i.e. exchange a client_id and secret for an access_token).

To create a rule that runs on the client credentials exchange you have to use the webtask CLI (wt). To install the CLI, you can follow the steps here: https://manage.auth0.com/#/account/webtasks.

Assuming you have an API defined with scopes (https://manage.auth0.com/#/apis) and you created a non-interactive client (https://manage.auth0.com/#/applications) and authorized it to use that API, follow these steps to create a rule.

Currenlt you can create only one rule that will be executed for all clients and APIs.

1. The first step is to create the webtask rule. Create a file myrule.js and enter the following. This is an example rule that will add an arbitrary claim (https://foo.com/claim) to the access_token and will also add an extra scope to the default scopes configured on the API (https://manage.auth0.com/#/apis).

module.exports = function(client, scope, audience, context, cb) {
	var access_token = {};
 	access_token['https://foo.com/claim'] = 'bar'; 	
 	access_token.scope = scope;
 	access_token.scope.push('extra');
 	cb(null, access_token);  
};

2. Next, we will create the webtask. We have to set some specific metadata for the webtask to be picked up by the Auth0 runtime (namely wt-compiler, auth0-extension and auth0-extension-name). These values are always the same. We can all add secrets that will be kept encrypted.

wt create myrule.js --meta wt-compiler=auth0-ext-compilers/client-credentials-exchange --meta auth0-extension=runtime --meta auth0-extension-name=credentials-exchange --secret SOME_SECRET=shhhh

3. Once the webtask rule is created we can now test it by doing a

curl --request POST \
  --url https://YOURS.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET", "audience":"API_IDENTIFIER","grant_type":"client_credentials"}'

You should get back an access_token (which is a JWT) that look like this:

{
  "iss": "https://YOURS.auth0.com/",
  "sub": "YOUR_CLIENT_ID@clients",
  "aud": "API_IDENTIFIER",
  "exp": 1472832994,
  "iat": 1472746594,
  "scope": "test extra",
  "https://foo.com/claim": "bar"
}

Implementation notes:

The input parameters for this rule look like this:

• client (object): the client who is asking for a token, including the client metadata (a key-value set that can be set for each client). Here is an example:

  { tenant: 'matiastest10',
        id: 'Y85ZvJvSjfVIcntnzQB94HAMlJiLh794',
        name: 'testclient',
        metadata: { some_metadata: 'my metadata' } }

• scope (array of strings): the scopes available on the API that you have defined.

• audience (string): the API identifier available on the API settings.

• context (object): an object that represents contextual information about the request.

  {
    "ip": "123.123.123.123"
    "userAgent": "...",
    "webtask": {
      "secrets": { FOO: "bar" }
  }

The Auth0 runtime expects you to return an access_token that should look like the following:

{
  "https://anything.com/foo": "bar",
  "scope": [ "scope1", "scope2" ]
}

You could also return an Error (cb(new Error('access denied'))if you decide to not issue the token.

Finally, you can use wt logs to see realtime logs and use console.log inside your code.