> For the complete documentation index, see [llms.txt](https://docs.1kosmos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.1kosmos.com/authentication/admin-portal/getting-started-with-adminx.md). # Getting Started with AdminX *** ### Introduction to AdminX The AdminX Portal is a trial experience designed to let clients experience the world of passwordless login. As an administrator, you have access to the following core modules: | Module | Description | | ---------------------- | ------------------------------------------------------------------------------------------------ | | Directory Integrations | Connect to an LDAP directory to view users and map attributes within LDAP to 1Kosmos attributes. | | Users | View and invite users to enroll in 1Kosmos. | | Applications | Choose from a portfolio of SAML applications to configure passwordless login. | | Settings | Manage your invitation templates, IdP, and session attributes for your community. | #### Getting started **Step 1: Configure 1Kosmos session attributes** To enable passwordless login for SAML applications, you need to provide additional context to the target application so the user can be correctly authorized to work within it. Depending on the application, some service providers may require a very simple profile (username, email), while others may require a richer set of user data. Use 1Kosmos attributes to define the data that needs to be shared. Two types of attributes exist within 1Kosmos: **1Kosmos session attributes** These are managed by the community administrator. You are mapped with `firstname`, `lastname`, `status`, `username`, `email`, and `phone` by default. Add any other user attributes needed to identify the user. {% hint style="info" %} As a second step, these attributes need to be mapped to directory attributes so the system knows where to pick up the values. {% endhint %} **1Kosmos Ledger attributes** Ledger attributes are managed by 1Kosmos and limited to five attributes. If available, these attributes can be returned as part of the SAML response: * `device_info` — device information * `dl` — driver's license * `aal` — authentication assurance level * `ial` — identity assurance level * `ppt` — passport **Step 2: Manage your email templates** By default, two templates are available — `Email invitation` and `OTP`. The rich text editor lets you configure the look and feel of each template to meet your organization's needs. **Step 3: Set up IdP configuration** See[ IdP Configuration ](/authentication/admin-portal/settings/identity-provider-idp-configuration.md)for detailed information on configuring your Identity Provider (IdP). *** ### Preferred User Stores #### Overview Setting a preferred user store lets tenant and community administrators choose which user directory to use as the primary user store for their tenant. User profiles are searched first in the **primary** user store, followed by the **secondary** and **tertiary** stores. Any new user registrations are added to the **primary** user store. For more information on configuring user directories, see: * [Connect to AD via Broker](/authentication/authentication-broker/adminx-broker-directory-connector.md) * [Connect to LDAP via Broker](/authentication/authentication-broker/connect-to-ldap-via-broker.md) * [Connect to LDAP](/authentication/authentication-proxy/ldap-setup.md) * [Connect to Azure AD](/authentication/admin-portal/directory-integrations/connect-to-microsoft-entra-id.md) {% hint style="info" %} User directories must be created and configured before you define your preferred user stores. See the links above for information on how to connect a user directory to your tenant. {% endhint %} #### Set a preferred user store To set a preferred user store for your tenant: 1. Locate **Primary** and click the **pencil** icon to the right of the listed directory. 2. Select a user directory from the drop-down menu and click **Save**. The list is populated from directories linked to your tenant. 3. If desired, repeat these steps for your **secondary** and **tertiary** preferred user stores. #### Remove a preferred user store To remove a preferred user store: 1. Locate the user store you want to remove and click the **trash** icon to the right of it. 2. Confirm by clicking **Continue**. {% hint style="warning" %} User accounts from the removed user store will no longer be able to log in. {% endhint %} *** ### Resetting Account Passwords Community administrators can define how end users reset their forgotten passwords — via AdminX or the mobile app — using the **Authentication > Reset Password** menu in the AdminX interface. On the **Reset Password** page, administrators can configure the following options: * **Enable users to reset passwords through AdminX** — allow password resets via a link sent by email, or a passcode sent to the user's mobile device along with the email link. * **Enable users to reset passwords through Mobile App** — allow password resets directly within the mobile app. {% hint style="info" %} Although mobile-based password resets are supported in the current implementation, this feature requires that the **Enable users to reset passwords through Mobile App** setting be explicitly enabled in AdminX for mobile resets to function. {% endhint %} #### Configuring Reset Password Settings To configure the reset password settings: 1. Log in to your tenant as a community administrator. 2. Navigate to **Authentication > Reset Password**. 3. On the **Reset Password Configurations** page, enable the mode in which you want to reset the password. The following settings are available: * **Enable users to reset password through AdminX** * Reset password with link sent to email. * Reset password with link sent to email and passcode sent to registered phone. * **Enable users to reset password through Mobile App** * **Enable users to reset password through Identity Verification** 4. Select the identifier users will use to reset the password: * **Email address** — displays the email address field on the **Forgot Password?** screen, allowing users to specify the email address that should receive the reset password email link. * **Username** — displays a username field on the **Forgot Password?** screen, allowing users to enter their username. A password reset link is then sent to the email address associated with that username. 5. Click **Save**. **Resetting Passwords Using the AdminX Interface** If you want to use the AdminX interface to reset a password, choose one of the following methods: * Resetting passwords using an email link * Resetting passwords using an email link and passcodes **Resetting Passwords Using an Email Link** 1. Open the tenant URL for which you want to reset the password. 2. On the **USERNAME** tab, enter your name and click **Next**. 3. On the **Choose an authentication method** screen, select **Password & OTP**. 4. On the login screen, click the **Forgot Password?** link. 5. On the **Forgot Password?** page, enter your primary email address and click **Continue**. 6. Go to your email and open the reset password link you received. 7. Because you selected the **Reset password with link sent to email** option, the reset password screen is displayed. 8. Enter the new password twice and click **Reset Password**. The UI confirms your password has been reset. Click **Return to Login page** to log in with the new password. **Resetting Passwords Using an Email Link and Passcodes** 1. Follow steps 1–6 from *Resetting Passwords Using an Email Link*. 2. Because you selected the **Reset password with link sent to email and passcode sent to registered phone** option, the passcode screen appears. 3. On the **Reset your password** page, enter the passcode received on your phone, then enter the new password and click **Reset Password**. The UI confirms your password has been reset. Click **Return to Login page** to log in with the new password. {% hint style="info" %} * The **Reset Password** link received by email is valid for 30 minutes only. * If a user has multiple accounts associated with the same email address, the UI prompts them to select the account for which the password reset email should be sent. The email is then sent to the selected account. {% endhint %} **Event Logs** The following events are triggered: * `E_PWDRESET_SUCCEEDED` — triggered when the password reset is successful. * `E_PWDRESET_FAILED` — triggered when the password reset fails. For more information, see [Event Logs.](/authentication/admin-portal/monitoring-and-reporting.md#event-logs) **Resetting Passwords Using Identity Documents** End users can reset their passwords independently using the self-service password reset (SSPR) feature, which requires them to verify their identity by submitting a valid identity document before proceeding. Your organization can use any preferred user store as the default source for user attribute lookup (for example, Active Directory). However, if your organization uses Workday as the user source, ensure the Workday integration is properly configured before users attempt password resets using identity documents. {% hint style="info" %} To enable the SSPR feature, turn on the **Enable users to reset password through Identity Verification** setting under **Authentication > Reset Password > Reset Password Configurations** in the AdminX interface. {% endhint %} Community administrators can configure common name aliases to improve matching between identity documents and user records. Aliases are defined as a dictionary of equivalent or shorthand names, allowing the system to recognize name variants during automated verification. **Example aliases** | Alias | Matches with | | ----- | -------------------- | | Joe | Joseph | | Steph | Stephanie or Stephen | | Bob | Robert, Bobby | | Rob | Robert | | Mike | Michael | **Prerequisites for Workday Integration** Before resetting a password through SSPR using Workday, the following prerequisites must be met: * A connection between Active Directory (AD) and 1Kosmos is required. * Add the **Employee ID** attribute to the 1Kosmos attribute set. {% hint style="info" %} You must map the Workday attributes to one of the following 1Kosmos attributes. For more details, see [1Kosmos Attributes.](/authentication/admin-portal/settings/1kosmos-attributes.md) * `$employeeId` * `$username` * `$email` Where `employeeId` and `dob` are now standard 1Kosmos attributes. {% endhint %} * Use a transformation script to modify the Workday API response and convert it into 1Kosmos IDProofing session attributes. The required session attributes are: * Firstname * Lastname * DOB (Date of Birth) * Workday API URL * Enable the Workday option to fetch user attributes. If this is not enabled, the system defaults to your preferred user store (for example, AD) for attribute lookup. **Managing Workday Configurations** To reset the password using identity verification for users fetched through Workday or any other preferred user store, community administrators must enable the **Enable users to reset password through Identity Verification** setting in the AdminX interface and configure the appropriate settings. | Field | Description | Example/Notes | | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enable users to reset password through AdminX | Toggle to allow users to reset their password using the AdminX portal. | On/Off | | Enable users to reset password through Mobile App | Toggle to allow users to reset their password using the mobile application. | On/Off | | Enable users to reset password through Identity Verification | Toggle to enable identity verification–based password reset. | On/Off | | Select an identity verification journey type you want users to reset password with | Specify the workflow for password reset. Used to validate user identity with first name, last name, and date of birth. | Example: `sprc_idv` | | Choose the source to retrieve user attributes for identity verification | Select the source system (for example, Workday) for fetching user attributes. **Note:** If Workday is not enabled, your preferred user stores are used as the default source for user attribute lookup (for example, Active Directory). | Workday | | Workday API URL | Endpoint URL to fetch user attributes from Workday. Should include supported query parameters (EmployeeID, EmployeeEmail, and so on). **Note:** Currently, you can pass only the following parameters to the URL: `$employeeId`, `$username`, and `$email`. | `https://sample.workday.com/service/report/sampleorg?Employee_ID=$employeeId&format=json` | | Authorization Type | Defines the authentication method used to access the Workday API. Available values: **Basic Auth** (authenticate using username and password), **No auth** (skip authentication), **Bearer Token** (authenticate using a token). | | | Username (appears only if you select Basic Auth) | The Workday API username configured for authentication. | Example: `ISU-kosmos` | | Password (appears only if you select Basic Auth) | The Workday API password for authentication. | Hidden (masked field) | | User attributes transformation | Allows admins to write transformation scripts to modify or filter attributes before use. | Example: Combine names, parse phone numbers, filter sensitive attributes | | Script Editor | Section to enter transformation logic. Example provided to map first name, last name, and date of birth. | Example script: `function transformUser(user, wdResponse) { user.firstname = wdResponse.Legal_FirstName; user.lastname = wdResponse.Legal_LastName; user.dob = wdResponse.Date_Of_Birth; return user;}` | | Run/Clear Output | Click to execute the transformation script and clear console output. | Used for testing scripts | | Console Output | Displays results of script execution for validation. | | | Test User Attributes | Click to test attribute retrieval and transformation using sample user data. | | | Save | Click to save the reset password configuration changes. Before saving, you must verify your identity (see steps below). | | | Back | Click to navigate to the previous page without saving changes. | - | **To save the configuration:** 1. Click **Save**. 2. Select a mode (**Email** or **SMS**) to receive the verification code. 3. Enter the one-time code. 4. Upon successful verification, the UI confirms that the changes made to the script have been saved. 5. To test the transformed attributes, click **Test User Attributes**. **To reset the password using an identity document:** 1. Open your tenant URL. 2. Enter the username for which you want to reset the password and click **Next**. 3. Click **Forgot Password**. 4. On the **Forgot Password?** page, enter your primary email address and click **Continue**. If multiple accounts match the entered email address, specify the username and click **Continue**. 5. Select the mode in which you want to receive the verification link and click **Continue**. 6. Read the instructions before you begin, then click **Start Verification**. 7. The **Get ready to verify your identity!** screen confirms the verification link has been sent to your email and indicates verification is in progress. 8. Go to your email inbox and click the **Reset your password** link. 9. On the **Start Your Verification** screen, select the **Consent Notice** check box and click **Let's get started**. 10. Start the scan. 11. Scan the front side of the document. Once capture is successful, click **Continue**. 12. Provide your selfie. Once the selfie capture is successful, click **Continue**. 13. Once authenticity is verified, the AdminX interface confirms your identity has been verified, and you can proceed to reset the password. 14. On the **Reset your password** screen, enter your new password and click **Reset Password**. {% hint style="info" %} It is recommended to reset the password within 3 minutes. If you fail to do so, you'll receive the message: "Token expired. Please request a password reset again. {% endhint %} 15. The UI confirms your password has been reset. Log in with the user account for which the password was reset. 16. Log in to your tenant with the new password. You'll land on the AdminX interface. **Event Logs** The `E_IDV_DOCUMENT_VALIDATE` event has been enhanced to include additional details such as the fuzzy match score and the session summary certificate. During the SSPR process, the system logs events and includes additional factors to identify the mode of password reset and the reason for any failure. For both successful and failed events (`E_PWDRESET_SUCCEEDED` and `E_PWDRESET_FAILED`), the logged details include the following mode: * `email_link_with_otp` * `email_link` * `id_proofing` * `Authenticator` * `Other` If the mode is `id_proofing`, the session ID is mandatory. The following table lists common error scenarios and the corresponding messages that may appear in `E_PWDRESET_FAILED` events. | Scenario | Error Message | | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | Generic failure during password change | Generic error: Error while changing user password | | Password login not allowed by organization | Your organization does not allow you to login with a password | | ID proofing not configured in SSPR settings | DVCID not configured in SSPR settings - ID Proofing config not available | | Error during ID Proofing session creation | Error in creating ID Proofing session | | ID Proofing session expired or abandoned | ID Proofing session is expired | | ID Proofing failed due to document verification | Document verification failed | | User is disabled | User is disabled | | User is inactive | User is inactive | | User not found (e.g., deleted between password reset steps) | User not found | | `employeeId` is required but missing in user object | employeeId is missing in the user object | | `username` is required but missing in user object | username is missing in the user object | | `email` is required but missing in user object | email is missing in the user object | | SSPR is enabled but endpoint details are missing | {sspr.user\_profile\_api.provider} API details missing. Please check SSPR settings. | | API call to user profile provider failed | {sspr.user\_profile\_api.provider} API failed with error code: {resp.errcode} | | Transformation script execution failed | Transformation script failed | | Transformation script is missing but Workday/provider details are present | Transformation script is not present | **Enforcing Password History** 1Kosmos supports enforcing password history during password reset operations. This enforcement applies to all reset methods, including: * Mobile-based password reset * AdminX-initiated password reset * Identity document–based password verification When password history enforcement is enabled, users are prevented from resetting their password to any of their recently used passwords. If a user attempts to reuse a previous password, the password reset operation fails. This feature prevents users from reusing previously used passwords, ensuring stronger password security compliance. **Prerequisites** Before enabling password history enforcement, ensure the following: * Go Broker service version 1.09.02 or later. * Use the AdminX interface to enable this feature. * Active Directory password policy: password history must be configured and enforced at the Active Directory (AD) level. **Enabling Password History Enforcement** Community administrators can enable password history enforcement using the **Enforce Password History Check** switch under **Authentication > Reset Password > Password Reset Settings** in the AdminX interface. When enabled, the system enforces password history checks during password reset to prevent users from reusing previously used passwords. This setting is disabled by default. **Enabling Password History Policy in Active Directory** Follow these steps to configure password history enforcement using Group Policy Management. **Step 1: Open Group Policy Management** 1. Click **Start → Administrative Tools → Group Policy Management**. 2. Expand the following hierarchy: **Forest > Domains > yourdomain.com**. **Step 2: Edit Default Domain Policy** 1. Right-click **Default Domain Policy**. 2. Select **Edit**. **Step 3: Navigate to Password Policy Settings** Navigate to: **Computer Configuration > Policies > Windows Settings > Security Settings > Account Policies > Password Policy**. **Step 4: Configure Password History** 1. Double-click **Enforce password history**. 2. Set the number of passwords to remember (for example, 5). 3. Configure **Minimum password age**. This value must be greater than 0 for password history enforcement to function correctly. 4. Click **Apply**, then **OK**. **Step 5: Apply Group Policy Changes** 1. Close the Group Policy Editor. 2. Run the `gpupdate /force` command on the domain controller or target system. **Resetting Passwords with Password History Enforcement** To reset a password when password history enforcement is enabled: 1. Log in to the AdminX tenant. 2. Enter the username for which you want to reset the password. The new password must not be one that was previously used. 3. Click **Forgot Password**. 4. Enter the username or email address and click **Continue**. 5. Click the magic link received in the registered email address. 6. Enter the one-time password (OTP) received via SMS. 7. Enter a new password twice and click **Reset Password**. **Expected behavior** If the user enters a password that was previously used, the password reset operation fails. An error message similar to the following is displayed: * "The password does not meet the length, complexity, or history requirement of the domain." The user remains on the **Reset Your Password** screen and must enter a different password that complies with the configured password policies. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.1kosmos.com/authentication/admin-portal/getting-started-with-adminx.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.