Estimated time to complete: 5 minutes
If you run into any problems, please contact your support team or support@claritysecurity.io.
Overview
When Clarity provisions access to someone who doesn’t have an account in a Dynamic Database application yet, it does two things:
Creates the account by running your Create New User statement (usually an INSERT).
Finds the account it just created by running your Get User statement, so it can link that account to the identity.
By default, step 2 looks the new account up using the ID the database auto-generates for the new row. That works for tables with an auto-numbering ID column. If your table has no auto-generated ID (for example, a table keyed by username, or by several columns together), the database has no ID to report. The account gets created, but Clarity can’t find it and the request fails with an error like:
There was no error inserting the user, but after inserting we were unable to retrieve the user
Identifier Binding fixes this. It tells Clarity which value to look the new account up by instead, such as the username it just inserted.
When to Use It
Set Identifier Binding if both of these are true:
The table your Create New User statement inserts into has no auto-generated ID column (no IDENTITY or auto-increment column).
Your Get User statement looks users up by a value you already know when creating them, such as the username or email.
Leave it blank if your table has an auto-generated ID that Get User looks users up by. Nothing changes for applications that leave it blank.
Before You Begin
Clarity access: you need permission to edit the application’s SQL statements (an application owner or a Clarity administrator).
ClarityConnect version: your ClarityConnect appliance must be on a version that supports Identifier Binding. Older appliances ignore the field. Setting it early does no harm, but it has no effect until the appliance is upgraded. Contact your customer success team if you aren’t sure which version you have.
What to Enter: a Binding Name, Not a Column Name
This is the part most people get wrong. Identifier Binding takes the name of a Clarity binding, not the name of a column in your database.
Clarity binding names are the values Clarity sends to your SQL statements, such as username, email, first_name and last_name. They’re the same names you type in a statement’s Parameter Bindings (?) box.
Column names are the names in your own table, such as UserName or LoginID. These do not go in Identifier Binding.
Rule of thumb: enter the same word that appears in your Create New User statement’s Parameter Bindings (?) box for the value that identifies the user.
Example
A table called UserRoles has three columns, AppName, UserName and RoleName, and no auto-generated ID. The application’s statements look like this:
Statement | SQL | Parameter Bindings (?) |
|---|---|---|
Create New User | INSERT INTO UserRoles (AppName, UserName, RoleName) VALUES ('App1', ?, 'Read-Only') | username |
Get User | SELECT ... FROM UserRoles WHERE UserName = ? AND AppName = 'App1' | identity_service_identifier |
Identifier Binding value | Result |
|---|---|
username | Correct. After the insert, Clarity runs Get User with the username it just inserted, finds the row, and links the account. |
UserName | Wrong. That’s the column name. Clarity has no binding called UserName (binding names are case-sensitive), so it stops with an error before running the insert. Nothing is written. |
(blank) | Clarity uses the database’s auto-generated ID. This table has none, so the account is created but can’t be found. |
Note
Whatever value you choose, your Get User statement must be able to find the user by it. In the example, Get User filters on UserName, and the username binding holds that same value.
Step-by-Step Guide
Open the application and click SQL in the title bar to open Update Application SQL Statements.
Select the Create New User tab.
Scroll down past Type to the Identifier Binding field.
Enter the Clarity binding name that identifies the new user, for example username. Check that the same word appears in this statement’s Parameter Bindings (?) box.
Click Update Application. The page reloads and a new version of your SQL statements is saved.
Test by requesting access for a user who doesn’t have an account in the application yet. The request should complete without the “unable to retrieve the user” error.
How It Behaves
The account already exists: if the insert fails because the row is already there (for example, on a retry after an earlier failed attempt), Clarity still looks the user up by the binding value. It finds the existing row and links the account, so the request succeeds instead of failing on every retry.
The binding value is missing: if the field you named is blank or missing for a user, Clarity reports an error and does not run the insert. This stops a row from being created that Clarity then couldn’t find.
Several Create New User statements: if more than one statement sets Identifier Binding, the first one that sets it is used.
Field left blank: Clarity keeps the previous behavior and uses the database’s last inserted ID.
Troubleshooting
Error or symptom | Likely cause | What to do |
|---|---|---|
“identifier_binding ‘…’ names a field that is absent or blank in the user data” | The value entered is a column name (like UserName) or a binding the statement doesn’t use. | Change Identifier Binding to the binding name from the Parameter Bindings (?) box, such as username. |
“unable to retrieve the user after the create_new_user statement ran” | Identifier Binding is blank on a table with no auto-generated ID, or Get User doesn’t filter on the value you chose. | Set Identifier Binding, and check that Get User looks users up by that same value. |
The field is set but nothing changed | Your ClarityConnect appliance is on a version that doesn’t support Identifier Binding. | Contact your customer success team to upgrade the appliance. |
Need Help?
If you have any problems, contact your customer success team. You can also get in touch with our general support via email, open a support ticket. Our general support team is available Monday - Friday from 8:00 AM - 6:30 PM CST.