Auth0

This guide provides detailed instructions on creating, managing, and migrating Auth0 Actions, along with the knowledge and tools necessary to leverage Actions effectively within your Authentication workflows and use them with a PlainID IDP Token Enrichment Authentication flow. This guide also provides instructions on how to migrate from Auth0 Rules to Auth0 Actions.

Create an Auth0 Action

An Auth0 Application is required to create an Action. Refer to Auth0's article on how to Write your First Action before continuing.

Configuring Auth0 Action Settings

1. Add a Login/Post Login trigger for your action.
2. In the dependency name field, input axios and choose a version. We recommend using recommended environment.
3. Save your action.

To add custom authentication logic:

1. Paste the following sample Auth0 Action Script in the provided Auth0 code editor:

exports.onExecutePostLogin = async (event, api) => {
  const axios = require('axios');
  const idpHookUrl = "https://{your-address}/idp-hook/auth0/action";
  const keysPrefix = "https:"
  const headers = { 
    "Content-Type": "application/json",
    'x-plainid-client': 'POBBVWIKIYVE5PX4FDZU',
    'x-plainid-secret': '5BQVXOpRg4MvPcmI2vp0XcHi0xTayBFsF5CODZsM',
    // 'x-plainid-workspace': '<workspaceId>' //Optional
  };

  try {
    const response = await axios.post(idpHookUrl, event, { headers });
    if (response && response.data) {
      for (const [key, value] of Object.entries(response.data)) {
        api.idToken.setCustomClaim(`${keysPrefix}${key}`, value);
      }
    }
  }
  catch (error) {
    console.error("error >>", error)      
  }
};

2. In the code editor, modify the address in the idpHookUrl parameter with your address. The rest of the endpoint should remain unchanged.

• Optional: Change the keyPrefix to your preferred key name.

3. In the 'x-plainid-client' and 'x-plainid-secret' parameters, input your PlainID Client ID and Secret.

• You can also refer to Auth0's article on Adding a secret if preferred.
• Optional: Input your workspaceID in the x-plainid-workspace parameter if needed. If not in use, it uses the entityType. If specified, the entityType value is taken from the workspaceID value and is used in the Runtime request.

4. Click Deploy.

Defining a Flow

Flows are what allow you to organize in what order you want your Action/s to be executed. See Auth0's Explore Flows and Triggers article to learn more.
To define a flow:

1. In the Flows section, drag your relevant Action between Start and Complete.
2. Click Apply to save the flow.

Converting a Rule to an Action

Since Auth0 is deprecating Rules, we recommend that you begin converting your rules into actions. After determining which Rules are enabled for your Auth0 tenant, follow these steps to convert a Rule to an Action:

1. Create a new Action to replace your Rule.
   • If migrating a Rule in a Production tenant, we recommend backing up your rule.
2. Update your Rule logic according to the Actions programming model, using the latest supported version of NodeJS. See Auth0's article on Access to npm Packages for more information
3. Test your new Action to make sure it functions as expected.
4. Deploy new Actions to Production tenants one Action at a time, disabling each existing Rule in parallel to creating a new Action.
5. Repeat the above steps for your remaining Rules, until they are all converted to Actions.

Define The Auth0 Rule Settings

Create a new Rule with the following parameters:

Sample Auth0 Rule Script

function plainidRule(user, context, callback) {  
    user.user_metadata = user.user_metadata || {};  
    var configuration = {  
        "PLAINID_CLIENT_ID": "[PLAINID_SCOPE_CLIENT_ID]",  
        "PLAINID_CLIENT_SECRET": "[PLAINID_SCOPE_CLIENT_SECRET]"  
    };  
    var body = {  
        "user": user,  
        "context": context,  
        "config": configuration  
    };  
    var request = require('request');  
    var options = {  
        'method': 'POST',  
        'url': 'https://[PLAIN_ID_URL]/hook/auth0?appPostfix=-V5',  
        'headers': {  
            'Content-Type': 'application/json',  
            'x-plainid-client': '[PLAINID_SCOPE_CLIENT_ID]',  
            'ngrok-skip-browser-warning': 'true',  
            'x-plainid-secret': '[PLAINID_SCOPE_CLIENT_SECRET]'  
        },  
        body: JSON.stringify(body)  
    };  
    request(options, function(error, response) {  
        if (error) throw new Error(error);  
        var object = JSON.parse(response.body);  
        let idTokenClaims = context.idToken || {};  
        context.idToken = idTokenClaims;  
        for (const [key, value] of Object.entries(object)) {  
            idTokenClaims[`https:${key}`] = value;  
        }   
        return callback(null, user, context);  
    });  
}

Testing the Web-Hook

To simulate the user login to the web-application, we can use an OIDC tool (e.g. https://oidcdebugger.com/). This tests the full integration and allows you to review the Token Enriched JWT that contains the relevant claims (keys and values) - Sample configuration for https://oidcdebugger.com:

After the configuring the settings, click on “Send Request” to test the configuration.

If everything is set up correctly you will receive a JWT/Response with the relevant claims from the PlainID Access Policy, e.g.:

{  
  "sub": "00u7mdjdhdhdhjBky5d7",  
  "ver": 1,  
  "iss": "https://dev-0eddvg.us.auth0.com/",  
  "aud": "0oa7m66nxxZ30CEOg5d7",  
  "iat": 1673259158,  
  "exp": 1673262758,  
  "jti": "ID.fMPCup1auYv4cJWA8h_7rm2RpdWRfQ77uAWQh4OvFyo",  
  "amr": [  
      "pwd"  
  ],  
  "idp": "00o7ifadsdasddXcpgO5d7",  
  "nonce": "s9r39ftqr7dm",  
  "auth_time": 1673250531,  
  "at_hash": "RJasdfadsfSakS7s-YiwQ",  
  "c_hash": "f3tMasdfasdfz4DDKyyk2QKw",  
  "https:claimPortalRole": [  
      "Administrator"  
  ],  
  "https:DepartmentManagerLevel": [  
      "Senior"  
  ]  
}