--- title: Create authentication trees description: In the AM admin UI, go to Realms > realm name > Authentication > Trees and click Create Tree. component: pingam version: 8.1 page_id: pingam:am-authentication:create-auth-trees canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authentication/create-auth-trees.html keywords: ["Authentication", "Nodes & Trees", "Setup & Configuration"] page_aliases: ["authentication-guide:create-auth-trees.adoc"] section_ids: create-authn-tree-ui: Create a tree in the UI create-authn-tree-rest: Create a tree over REST example: Example --- # Create authentication trees ## Create a tree in the UI 1. In the AM admin UI, go to Realms > *realm name* > Authentication > Trees and click Create Tree. 2. Enter a tree name, for example `myAuthTree`, and click Create. The authentication tree designer displays with the Start entry point connected to the Failure exit point. The authentication tree designer provides the following features on the toolbar: **Authentication tree designer toolbar** | Button | Usage | | ---------------------------------------------------------------- | ----------------------------------------------------------------- | | ![icon-trees-auto-layout](../_images/icon-trees-auto-layout.png) | Lay out and align nodes according to the order they're connected. | | ![icon-trees-full-screen](../_images/icon-trees-full-screen.png) | Toggle the designer window between normal and full screen layout. | | ![icon-trees-delete-node](../_images/icon-trees-delete-node.png) | Remove the selected node. You can't delete the Start entry point. | 3. Add a node to the tree by dragging the node from the Components panel on the left-hand side, and dropping it into the designer area. The list of authentication nodes is divided into categories. Click the category title to expand and collapse the categories. Use the filter text field to restrict the list of authentication nodes. This will match on the node's name and any tags applied to the node: ![Filters match on the node's name, and any tags applied to the node.](_images/auth-tree-component-panel.png) 4. Configure the node properties by using the right-hand panel. You can find more information on the available properties for each node in [Node reference](auth-nodes-reference.html). 5. Connect the node to the tree as follows: 1. Select and drag the output connector from an existing node and drop it onto the new node. 2. Select and drag the output connector from the new node and drop it onto an existing node. Nodes have one or more connectors, displayed as dots on the node. Unconnected connectors appear red until you connect them to other nodes in the tree. | | | | - | ------------------------------------------------------------------------------------------- | | | *Input* connectors appear on the left of the node, *output* connectors appear on the right. | A line is drawn between the connectors of connected nodes, and the connectors no longer appear red. 6. To change a connection, select and drag the green connector in the connection and drop it onto the new location. 7. Continue adding, connecting and removing nodes until the tree is complete, then click Save. 8. Test your authentication tree by navigating to a URL similar to the following: `https://am.example.com:8443/am/XUI/?realm=/alpha&service=myAuthTree#login` ## Create a tree over REST To create an authentication tree over REST, send individual PUT requests to create each node. Then send a PUT request to create the tree, specifying a tree ID and including all the nodes in the tree. You can find information on the required parameters in the [online REST API reference](../am-rest/about-api-explorer.html), and the latest node definitions in [List latest node definitions](list-latest-node-definitions.html). Consider the following when creating authentication trees using the REST API: * You must re-create each node when creating a new authentication tree. * Include the version of the node you want to create in the request URL. If the version doesn't exist, an HTTP 404 Not Found status code is returned, as follows: ```json { "code": 404, "reason": "Not Found", "message": "Resource 'n.0' not found" } ``` | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To find the latest version for a node, send a POST request to the `realm-config/authentication/authenticationtrees/nodes/node-name` endpoint with `_action=getLatestType` as the query string parameter. | * Each node must have a valid UUID as its identifier. You can generate UUIDs online, for example, using the [Online UUID Generator](https://www.uuidgenerator.net/). If you don't use a valid UUID, authentication will fail with the following error: ``` ERROR: Could not get SMS service: authenticationTreesService java.lang.IllegalArgumentException: Invalid UUID string: 12345 ``` * The `entryNodeId` field specified when creating the authentication tree is the UUID of the first node in the tree. * The `outcome` field specified when creating the authentication tree is the UUID of the next node. This allows you to move between nodes. * The Success and Failure nodes have the following static UUIDs: * Success node: `70e691a5-1e33-4ac3-a356-e7b6d60d92e0` * Failure node: `e301438c-0bd0-429c-ab0c-66126501069a` These UUIDs remain constant across all authentication trees and AM versions. ### Example Complete these steps to create a simple authentication tree consisting of three nodes: [Username Collector node](https://docs.pingidentity.com/auth-node-ref/8.1/am-only/username-collector.html), [Password Collector node](https://docs.pingidentity.com/auth-node-ref/8.1/am-only/password-collector.html), and [Data Store Decision node](https://docs.pingidentity.com/auth-node-ref/8.1/data-store-decision.html). 1. Generate UUIDs for each of the nodes you want to create. This example uses the following UUIDs: * Username Collector node: `8f9d2280-caa7-433f-93a9-1f64f4cae60a` * Password Collector node: `54f14341-d1b7-436f-b159-d1f9b6c626eb` * Data Store Decision node: `3fc7ce22-fc79-4131-85f2-f1844709d042` 2. Authenticate to AM as the `amAdmin` user: ```bash $ curl \ --request POST \ --header "Content-Type: application/json" \ --header "X-OpenAM-Username: amadmin" \ --header "X-OpenAM-Password: password" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate' { "tokenId":"AQIC5wM…​TU3OQ*", "successUrl":"/am/console", "realm":"/alpha" } ``` 3. Create a version 2 Username Collector node, where the UUID is the one you generated in step 1: ```bash $ curl \ --request PUT \ --header "iPlanetDirectoryPro: AQIC5wM…​TU3OQ*" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "If-None-Match: *" \ --data '{ "_id": "8f9d2280-caa7-433f-93a9-1f64f4cae60a", "_type": { "_id": "UsernameCollectorNode", "name": "Username Collector" } }' \ "https://am.example.com:8443/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/nodes/UsernameCollectorNode/2.0/8f9d2280-caa7-433f-93a9-1f64f4cae60a" { "_id": "8f9d2280-caa7-433f-93a9-1f64f4cae60a", "_rev": "280717409", "prepopulate": false, "_type": { "_id": "UsernameCollectorNode", "name": "Username Collector", "collection": true, "version": "2.0" }, "_outcomes": [ { "id": "outcome", "displayName": "Outcome" } ] } ``` 4. Create a version 1 Password Collector node, where the UUID is the one you generated in step 1: ```bash $ curl \ --request PUT \ --header "iPlanetDirectoryPro: AQIC5wM…​TU3OQ*" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "If-None-Match: *" \ --data '{ "_id": "54f14341-d1b7-436f-b159-d1f9b6c626eb", "_type": { "_id": "PasswordCollectorNode", "name": "Password Collector" } }' \ "https://am.example.com:8443/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/nodes/PasswordCollectorNode/1.0/54f14341-d1b7-436f-b159-d1f9b6c626eb" { "_id": "54f14341-d1b7-436f-b159-d1f9b6c626eb", "_rev": "792175357", "_type": { "_id": "PasswordCollectorNode", "name": "Password Collector", "collection": true, "version": "1.0" }, "_outcomes": [ { "id": "outcome", "displayName": "Outcome" } ] } ``` 5. Create a version 1 Data Store Decision node, where the UUID is the one you generated in step 1: ```bash $ curl \ --request PUT \ --header "iPlanetDirectoryPro: AQIC5wM…​TU3OQ*" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "If-None-Match: *" \ --data '{ "_id": "3fc7ce22-fc79-4131-85f2-f1844709d042", "_type": { "_id": "DataStoreDecisionNode", "name": "Data Store Decision" } }' \ "https://am.example.com:8443/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/nodes/DataStoreDecisionNode/1.0/3fc7ce22-fc79-4131-85f2-f1844709d042" { "_id": "3fc7ce22-fc79-4131-85f2-f1844709d042", "_rev": "2145625368", "_type": { "_id": "DataStoreDecisionNode", "name": "Data Store Decision", "collection": true, "version": "1.0" }, "_outcomes": [ { "id": "true", "displayName": "True" }, { "id": "false", "displayName": "False" } ] } ``` 6. Create the authentication tree with these three nodes, where the UUIDs are the ones you used to create the nodes. Make sure you set `entryNodeId` to the UUID of the first node, include the node versions, and set the `outcome` of each node to the UUID of the next node: ```bash $ curl \ --request PUT \ --header "iPlanetDirectoryPro: AQIC5wM…​TU3OQ*" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: protocol=2.1,resource=3.0" \ --header "If-None-Match: *" \ --data '{ "entryNodeId": "8f9d2280-caa7-433f-93a9-1f64f4cae60a", "nodes": { "8f9d2280-caa7-433f-93a9-1f64f4cae60a": { "displayName": "Username Collector", "nodeType": "UsernameCollectorNode", "version": "2.0", "connections": { "outcome": "54f14341-d1b7-436f-b159-d1f9b6c626eb" } }, "54f14341-d1b7-436f-b159-d1f9b6c626eb": { "displayName": "Password Collector", "nodeType": "PasswordCollectorNode", "version": "1.0", "connections": { "outcome": "3fc7ce22-fc79-4131-85f2-f1844709d042" } }, "3fc7ce22-fc79-4131-85f2-f1844709d042": { "displayName": "Data Store Decision", "nodeType": "DataStoreDecisionNode", "version": "1.0", "connections": { "false": "e301438c-0bd0-429c-ab0c-66126501069a", "true": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0" } } } }' \ "https://am.example.com:8443/am/json/realms/root/realms/alpha/realm-config/authentication/authenticationtrees/trees/myNewTree" { "_id": "myNewTree", "_rev": "2061817222", "entryNodeId": "8f9d2280-caa7-433f-93a9-1f64f4cae60a", "innerTreeOnly": false, "noSession": false, "mustRun": false, "enabled": true, "transactionalOnly": false, "uiConfig": {}, "nodes": { "8f9d2280-caa7-433f-93a9-1f64f4cae60a": { "displayName": "Username Collector", "nodeType": "UsernameCollectorNode", "version": "2.0", "connections": { "outcome": "54f14341-d1b7-436f-b159-d1f9b6c626eb" } }, "54f14341-d1b7-436f-b159-d1f9b6c626eb": { "displayName": "Password Collector", "nodeType": "PasswordCollectorNode", "version": "1.0", "connections": { "outcome": "3fc7ce22-fc79-4131-85f2-f1844709d042" } }, "3fc7ce22-fc79-4131-85f2-f1844709d042": { "displayName": "Data Store Decision", "nodeType": "DataStoreDecisionNode", "version": "1.0", "connections": { "false": "e301438c-0bd0-429c-ab0c-66126501069a", "true": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0" } } } } ``` 7. Verify the tree has been created in the AM admin UI. It should look similar to this: ![example tree](_images/example-tree.png)