Provision users automatically with Okta

Axon offers automatic user and group account provisioning with Advanced User Management (AUM), using the System for Cross-domain Identity Management (SCIM) protocol. This allows you to sync Single Sign-On (SSO) user accounts automatically with Axon user accounts and groups. Automatic provisioning can be done with Okta, as described here; or Provision users automatically with Microsoft Entra ID or Active Directory.

Learn about configuring IAM to use Single Sign-On (SSO) in the Single Sign-On Quick Start Guide.

After you configure automatic provisioning, Okta runs a synchronization process at regular intervals. The process queries Axon for assigned users and groups and then creates or modifies them to match the assignment details in Okta.

Prerequisites

Before you begin, ensure you have:

  1. Axon Administrator access: Your role must include the Configure Agency Security Settings permission to configure provisioning.
  2. Configure Single Sign-On with Okta
  3. Okta Org URL: The Okta URL your organization uses for sign-in, in the format https://{yourorg}.okta.com. For example, Example Police Department’s URL might be https://examplepd.okta.com.
  4. Okta Administrator access and URL: Your Okta account needs administrator privileges.
    • Your Okta admin URL will be in the format https://{yourorg}-admin.okta.com - using the example above, Example PD’s Okta admin URL would be https://examplepd-admin.okta.com

Decide if you want to sync only users, or users and groups. If you are concerned about syncing of groups overwriting changes to user accounts when they are synced, only sync users.

Learn more about groups in the Groups overview.

In the Axon Admin Console

  1. In the Axon Admin Console, expand User Management, and select Automatic Provisioning.
  2. Set Provisioning Options to Okta.
  3. Enter your Okta Org URL described in Prerequisites.
  4. Copy the SCIM Endpoint URL displayed on the page. You will need this for Okta configuration.
    1. The endpoint URL format is: https://{yourorg}.region}.evidence.com/api/v2/agencies/{yourorgid}/scim
    2. Example: https://examplepd.evidence.com/api/v2/agencies/e1e19bb4-ecab-4ffa-b60d-3fd152d50892/scim
  5. Set the Sync options to your preference, as described in Prerequisites.

In Okta

The rest of these steps will be done in Okta.

Create the OIDC Application

The OIDC application provides OAuth 2.0 authentication for SCIM provisioning.

  1. Sign in to your Okta Admin URL (https://yourorg-admin.okta.com) described in Prerequisites.
  2. Navigate to Applications > Applications, then select Create App Integration.
  3. Select OIDC - OpenID Connect as the sign-in method and Web Application as the application type.
  4. Choose Next.
  5. Configure the application settings:
    1. App integration name: Enter a descriptive name, for example, "OIDC for Axon Integration".
    2. Grant type: Check both Authorization Code and Refresh Token
    3. Sign-in redirect URIs: Leave as http://localhost temporarily. You will change this later in the process.
    4. Controlled access: This determines who can see the OIDC information. If there isn’t anyone else you want to assign for this, choose Skip group assignment for now. You can add other people later if you find you need help managing this.
  6. Save.
  7. Note the Client ID from the application's General tab - you'll need this later.
  8. Generate a Client Secret and save it securely - you'll need this later.

Configure the Access Policy for the OIDC application

  1. Go to Security > API > Authorization Servers.
  2. Select the default authorization server.
  3. Go to Access Policies and choose Add New Access Policy.
  4. Configure the policy:
    1. Name: "OIDC for Axon Integration"
    2. Description: "Policy for OIDC for Axon Integration"
    3. Assign to: select The following clients and choose the OIDC application you just created
  5. Create Policy.
  6. In the newly created policy, select Add Rule and configure:
    1. Rule name: "Authorization Code for Okta SAML Rule"
    2. Grant type is: Ensure Authorization Code is checked
    3. Refresh token lifetime is: Set to Unlimited
  7. Create Rule.

Create SAML Application with SCIM Provisioning

  1. Navigate to Applications > Applications and choose Create App Integration.
  2. Select SAML 2.0 and choose Next.
  3. In General settings, enter a descriptive name in App name, such as "SAML for Axon Integration", and choose Next.
  4. Configure SAML Settings for testing purposes - you will change these later:
    1. Single sign-on URL: http://localhost
    2. Audience URI (SP Entity ID): http://localhost
    3. Choose Next
  5. Select This is an internal app that we have created and then Finish.
  6. Update the OIDC Redirect URI:
    1. After creating the SAML application, note the application identifier from the URL. The format is: https://{org}-admin.okta.com/admin/app/{app_identifier}/instance/{instance_id}
    2. Use this to construct the redirect URI for the OIDC application, in the format: https://system-admin.okta.com/admin/app/cpc/{app_identifier}/oauth/callback
    3. Go back to your OIDC application, edit the Sign-in redirect URI, and add this redirect URL.
  7. Enable SCIM Provisioning:
    1. In the SAML application, go to the General tab
    2. In App Settings, select Edit
    3. Enable SCIM provisioning in the Provisioning section
    4. Save

Configure SCIM Connector Settings

  1. In your SAML application, go to the Provisioning tab.
  2. Under Integration, select Edit.
  3. Configure the SCIM connection:

 

Setting Value
SCIM connector base URL The SCIM Endpoint URL from In the Axon Admin Console, step 4 (in the format, https://yourorg.evidence.com/api/v2/agencies/{agency-id}/scim).
Unique identifier field for users We recommend Email, but you can choose userName if your organization doesn't want to use email.
Supported provisioning actions Select Push New Users, Push Profile Updates, and Push Groups.
Authentication Mode OAuth 2
  1. Configure OAuth 2 settings:
Setting Value
Access token endpoint URI https://{yourorg}.okta.com/oauth2/default/v1/token
Authorization endpoint URI https://{yourorg}.okta.com/oauth2/default/v1/authorize?scope=openid%20profile%20offline_access
Client ID From Create the OIDC Application step 7
Client Secret From Create the OIDC Applicationstep 8
  1. Save.
  2. Select Authenticate with OAuth to test the connection. In the popup that appears, sign in with your Okta credentials.
  3. After successful authentication, go To App settings and enable:
    1. Create Users
    2. Update User Attributes
    3. Deactivate Users

Configure Attribute Mappings

Navigate to Provisioning > To App > Attribute Mappings to configure how Okta attributes map to Axon.

Add custom Axon Extension Attributes

You must add the Badge ID attribute. If you also want to sync other Axon attributes, add them in this step.

  1. In Attribute Mappings, select Go to Profile Editor.
  2. Choose Add Attribute. You must add Badge ID. Add other attributes to meet your needs for user mapping:
Display name Variable Name and External Name External Namespace Data type Required? When to add
Badge ID badgeId urn:ietf:params:scim:schemas:extension:2.0:axon String Yes This attribute is required, so you must add it.
Rank Name rankName urn:ietf:params:scim:schemas:extension:2.0:axon String No When your organization has a ranking system (such as Lieutenant, Sergeant, etc.) and you want the rank mapped automatically.
Evidence Group Name evidenceGroupName urn:ietf:params:scim:schemas:extension:2.0:axon String No When you want to control access to Evidence using Axon's Evidence Group feature.
User Group Name userGroupName urn:ietf:params:scim:schemas:extension:2.0:axon String No When you want to add users to Axon's Groups, which can be used for many purposes such as access control or performance review.
Axon Role axonRole urn:ietf:params:scim:schemas:extension:2.0:axon String No When you want to control access to certain resource in Axon by role.

Add custom attributes to SCIM app

  1. Go to Profile Editor

  2. Select Users

  3. Choose Apps

  4. Select the application you created for Axon mapping

  5. Add Attribute

 

Required Attribute Mappings

SCIM Target Attribute Recommended Okta Source Notes
givenName user.firstName Set by default. Verify correct mapping.
familyName user.lastName Set by default. Verify correct mapping.
badgeId employeeNumber The badgeId attribute must be added, as described above in Add custom Axon Extension Attributes and Add custom attributes to SCIM app.

Below are images of the default mapping. You might need to change a few fields base on your needs, or just leave it as default. In the images below, the only custom attribute added is badgeId, which is required.

Sync users

  1. In your SAML application, go to the Assignments tab.
  2. Select Assign and choose either Assign to People or Assign to Groups.
  3. Select the users or groups you want to provision to Axon.
    1. If you Assign to Groups, all users in those groups will be synced with Axon.
  4. Configure any per-user or per-group attribute overrides if needed.
  5. Choose Save and Go Back for each assignment.

Enable Provisioning

  1. Go to the Provisioning tab.
  2. Under Settings > To App, ensure all desired provisioning actions are enabled.
  3. Okta will begin synchronizing users and groups according to your configuration.
  4. Monitor the Tasks and Logs tabs for provisioning status and any errors.

Troubleshooting

Common Issues

Issue or error Likely cause Solution
Cannot authenticate to generate a token Incorrect SCIM connector base URL Check your SCIM connector base URL. It should be in the format https://{your-axon-domain}/api/v2/agencies/{your-agency-id}/scim
The credentials used to connect to the API were invalid; please check your configuration
  1. Wrong Oauth Grant type
  2. Wrong client_id or client_secret
  1. Grant type should be "Authorization Code"
  2. Try copying and pasting your client_id and client_secret again

Verifying Configuration

  1. In Okta, use the Test Connection feature in provisioning settings to verify connectivity.
  2. Review Okta provisioning logs for detailed error messages:
    1. Navigate to Reports > System Log
    2. Filter for SCIM-related events
  3. The Okta org URL in Axon must match the issuer (iss) claim in the OAuth token. For example:
    1. Configured URL: https://{yourorg}.okta.com.
    2. Token issuer: https://{yourorg}.okta.com/oauth2/default
    3. The base domains must match for authentication to succeed

Provisioning Logs

Monitor provisioning activities in Okta:

  1. Go to Applications > your SAML app > Provisioning tab
  2. Check the Tasks section for:
    1. Pending provisioning operations
    2. Failed operations with error details
  3. Review System Log for detailed request/response information

Reference: Key Rules

  1. Organization URL Validation: The Okta org URL in the JWT token issuer must match the configured org URL in Axon.
  2. Role Handling:
    1. The role name "Blank" is filtered out (ignored)
    2. Default role is "User" if no other is specified
  3. Group Sync:
    1. Requires Sync Users and Groups configuration
    2. If you selected Sync Users Only but have configured groups, you will get a 403 Forbidden when trying to sync
    3. Groups cannot be deleted if they're in the Command Hierarchy
  4. User Deletion:
    1. SCIM DELETE operations set user status to Inactive
    2. Users are not permanently removed from the system
  5. External ID:
    1. Primary identifier for SCIM operations
    2. Must be unique across all users in the agency
    3. Used to link accounts for SSO
  6. Unique Fields:
    1. userName must be unique
    2. email must be unique
    3. externalId must be unique
  7. Default Language uses your organization's language setting in Axon, or defaults to EN_US.
  8. Rank and Role Lookup searches by name - they must exist in your Axon organization before provisioning users with those values.