Identity schema best practices

Follow this guide to learn about best practices when creating custom identity schemas.

Sensitive data

The identity schema isn't the right place to store data that should be obfuscated from the user. Users can see traits and other data - except credentials - using the /sessions/whoami endpoint. Users are also able to edit identity traits.

info

Don't store sensitive internal data in the identity's traits. Use the metadata_admin field for this purpose.

Read this document for information how to use metadata that can't be viewed or changed by the end user.

Keep your data lean

• Do not add too many fields to your identities. Keep the number of fields well below 15.
• Do not store business logic in your identities. Store this information in other systems. This includes credit card information, shipping addresses, shopping cart items, or user preferences.
• Do store profile data that is used across your system. This includes the usernames, email addresses, phone numbers, first names, and last names.

Updating identity schemas

When using the Ory CLI and Ory configuration files, use versioning to keep track of changes to your identity schema. This allows you to gradually update your identity schema without affecting existing identities.

Let's say that you just defined your first identity schema:

identity:
  default_schema_id: user_v0
  schemas:
    - id: user_v0
      url: file://path/to/user_v0.json

After a few weeks, you decide that you want to add additional fields or that you need to break compatibility with your current schema. To do that, add another version of the schema to the configuration and change the default_schema_id to use the new schema:

identity:
  default_schema_id: user_v1
  schemas:
    - id: user_v0
      url: base64://{b46-encoded-user_v0}
    - id: user_v1
      url: base64://{b46-encoded-user_v1}

With this configuration in place, existing identities work as expected and continue to use the user_v0 identity schema. All newly created identities will use user_v1 schema.

When you're ready to migrate all identities that use the user_v0 to the user_v1 schema, use the REST API to list all identities using the old version and perform the required data transformations.

Sanitize usernames/traits

To make sure usernames or traits satisfy a specific regex (for example only alphanumeric characters), they can be sanitized. To sanitize usernames add regular expressions to the identity Schema. To sanitize usernames coming from third-party OIDC providers like Google or GitHub write JSonnet.