Skip to main content

Import identities

Ory allows you to import identities from any other system. The endpoint used is the same as when creating identities with the subtle difference that you also provide the credentials field.

Importing verified addresses​

Use the verifiable_addresses field to import a verified address like an email address.

danger

You must ensure that address verification is enabled and that the verifiable_address is present in the identity's traits. If the identity traits do not have the address set as the "verified address" type, the imported values will be deleted on the next identity update.

An exemplary payload for importing an identity with a verified address:

{
  "schema_id": "preset://email",
  "traits": {
    "email": "docs-verify@example.org"
  },
  "verifiable_addresses": [
    {
      "value": "docs-verify@example.org",
      "verified": true,
      "via": "email",
      "status": "completed"
    }
  ]
}

Test the above example with a cURL command:

curl --request POST -sL \
  --header "Authorization: Bearer ory_pat_xRKLsFEOUFQFVBjd6o3FQDifaLYhabGd" \
  --header "Content-Type: application/json" \
  --data '{
  "schema_id": "preset://email",
  "traits": {
    "email": "docs-verify@example.org"
  },
  "verifiable_addresses": [
    {
      "value": "docs-verify@example.org",
      "verified": true,
      "via": "email",
      "status": "completed"
    }
  ]
}' https://playground.projects.oryapis.com/admin/identities

The API then responds with the created identity:

{
  "id": "880052ae-d32c-4b56-b82d-0dc711080910",
  "schema_id": "preset://email",
  "schema_url": "http://localhost:4455/schemas/cHJlc2V0Oi8vZW1haWw",
  "state": "active",
  "state_changed_at": "2022-02-24T15:33:17.845589803Z",
  "traits": {
    "email": "docs-verify@example.org"
  },
  "verifiable_addresses": [
    {
      "id": "c3f67b59-ab58-410b-971a-06b80f38468a",
      "value": "docs-verify@example.org",
      "verified": true,
      "via": "email",
      "status": "completed",
      "created_at": "2022-02-24T15:33:17.848941Z",
      "updated_at": "2022-02-24T15:33:17.848941Z"
    }
  ],
  "recovery_addresses": [
    {
      "id": "819b53bf-79e3-452e-8a9b-0323ec9d193c",
      "value": "docs-verify@example.org",
      "via": "email",
      "created_at": "2022-02-24T15:33:17.849758Z",
      "updated_at": "2022-02-24T15:33:17.849758Z"
    }
  ],
  "created_at": "2022-02-24T15:33:17.848475Z",
  "updated_at": "2022-02-24T15:33:17.848475Z"
}

Importing recovery addresses​

It is possible to import a list of recovery_addresses - similar to verifiable_addresses. It is better to let the identity schema handle setting the appropriate fields since there is no status to set for this address type.

We do not recommend setting these fields as they will be overwritten by other self-service flows! For more information on account recovery please head over to the account recovery documentation.

Importing credentials​

Ory supports importing credentials for identities including passwords and social sign in. You can use all of these payloads with the curl command from above!

Clear text password​

To import a clear text password, provide the password in the JSON payload.

danger

Password imports do not use any password validation. Users have to update their password according to the policy themselves using self-service flows.

{
  "schema_id": "preset://email",
  "traits": {
    "email": "docs-cleartext@example.org"
  },
  "credentials": {
    "password": {
      "config": {
        "password": "the-password"
      }
    }
  }
}

The password the-password will then be hashed according to the configured password hashing algorithm and stored in the database. The identity will be able to sign in using docs-cleartext@example.org and the-password as credentials.

Hashed passwords​

To import a hashed password, provide the hashed password in the JSON payload.

{
  "schema_id": "preset://email",
  "traits": {
    "email": "docs-hash@example.org"
  },
  "credentials": {
    "password": {
      "config": {
        "hashed_password": "$2a$10$ZsCsoVQ3xfBG/K2z2XpBf.tm90GZmtOqtqWcB5.pYd5Eq8y7RlDyq"
      }
    }
  }
}

BCrypt​

Ory Identities can hash passwords by BCrypt and can compare stored BCrypt hash and migrate if configured hasher (hashers.algorithm) isn't BCrypt.

Format​

BCrypt format is described here.

Argon2​

Ory Identities can hash passwords by Argon2 and can compare stored Argon2 hash and migrate if configured hasher (hashers.algorithm) isn't Argon2.

Format​

$argon2id$v=<version>$m=<memory>,t=<iterations>,p=<parallelism>$<hash>

Parameters​

  • version(number): The current version.
  • memory(number): Amount of memory to use.
  • iterations(number): Number of iterations to perform.
  • parallelism(number): Degree of parallelism.
  • hash(string): The computed derived key by the Argon2 algorithm encoded to Base64.

Example​

$argon2id$v=19$m=32,t=2,p=4$cm94YnRVOW5jZzFzcVE4bQ$MNzk5BtR2vUhrp6qQEjRNw

MD5​

Ory Identities doesn't hash password by MD5 but can compare stored MD5 hashes and migrate to configured hasher (hashers.algorithm). You can configure MD5 hashes to use a plain format (for hashes without salt) or a salted format (for hashes with salt).

Plain format (hashes without salt)​

$md5$<hash>

Parameters​

  • hash(string): The computed hash by the MD5 algorithm encoded to Base64.

Example​

$md5$CY9rzUYh03PK3k6DJie09g==

Salted format (hashes with salt)​

This format allows administrators to import passwords that use salting to calculate the MD5 hash. Ory doesn't prepend or append the salt to the user's password. To determine the way system performs salting, use the salting-format parameter.

$md5$pf=<salting-format>$<salt>$<hash>

Read this section to learn more about configuring the salting-format parameter.

Parameters​

  • salting-format(string): Format string specifies how salting should be done. Must be encoded to Base64.
  • salt(string): A sequence of bits, known as a cryptographic salt encoded to Base64.
  • hash(string): The computed hash by the MD5 algorithm encoded to Base64.

Example​

$md5$pf=e1NBTFR9e1BBU1NXT1JEfQ==$MTIz$q+RdKCgc+ipCAcm5ChQwlQ==
Salting format parameter​

Below are formatting specifiers that can be used in the salting-format.

  • {SALT}: Salt value from the previous section.
  • {PASSWORD}: User's password in clear text.
Example​

Assuming that User's password is ory123 and salt is c2FsdDEyMw==(in clear text: salt123) and the clear text form of salting-format parameter as follows:

{SALT}--{PASSWORD}

In that case result of the salting process would be:

salt123--ory123

SSHA, SSHA256, and SSHA512​

Ory Identities doesn't hash passwords by salted SHA but can compare stored salted SHA hashes and migrate to configured hasher (hashers.algorithm). SSHA does not take in any parameters for verification.

Examples​

{SSHA}JFZFs0oHzxbMwkSJmYVeI8MnTDy/276a
{SSHA256}czO44OTV17PcF1cRxWrLZLy9xHd7CWyVYplr1rOhuMlx/7IK
{SSHA512}xPUl/px+1cG55rUH4rzcwxdOIPSB2TingLpiJJumN2xyDWN4Ix1WQG3ihnvHaWUE8MYNkvMi5rf0C9NYixHsE6Yh59M=

PBKDF2​

Ory Identities doesn't hash passwords by PBKDF2 but can compare stored PBKDF2 hash and migrate to configured hasher (hashers.algorithm).

Format​

$pbkdf2-<algorithm>$i=<iteration>,l=<length>$<salt>$<hash>

Parameters​

  • digest(string): The HMAC digest algorithm applied to derive a key of the input password.
  • iterations(number): The number of iterations desired. The higher the number of iterations, the more secure the derived key will be, but will take a longer amount of time to complete.
  • length(number): Length in octets of derived key.
  • salt(string): A sequence of bits, known as a cryptographic salt encoded to Base64.
  • hash(string): The computed derived key by the PBKDF2 algorithm encoded to Base64.

Example​

$pbkdf2-sha256$i=100000,l=32$1jP+5Zxpxgtee/iPxGgOz0RfE9/KJuDElP1ley4VxXc$QJxzfvdbHYBpydCbHoFg3GJEqMFULwskiuqiJctoYpI

SCrypt​

Ory Identities doesn't hash passwords by SCrypt but can compare stored SCrypt hashes and migrate to configured hasher (hashers.algorithm).

Format​

$scrypt$ln=<cost>,r=<block>,p=<parrelization>$<salt>$<hash>

Parameters​

  • cost(number): CPU/memory cost (has to be power of 2 and >1)
  • block(number): block size parameter (must satisfy r * p < 2³⁰)
  • parallelization(number): parallelization parameter (must satisfy r * p < 2³⁰)
  • salt(string): A sequence of bits, known as a cryptographic salt encoded to Base64.
  • hash(string): The computed derived key by the SCrypt algorithm encoded to Base64.

Example​

$scrypt$ln=16384,r=8,p=1$ZtQva9xCHzlSELH/mA7Kj5KjH2tCrkbwYzdxknkL0QQ=$pnTcXKaWVT+FwFDdk3vO1K0J7ZgOxdSU1tCJNYmn8zI=

Firebase SCrypt​

Ory Identities doesn't hash passwords by Firebase SCrypt but can compare stored Firebase SCrypt hashes and migrate to configured hasher (hashers.algorithm).

Format​

$firescrypt$ln=<mem_cost>,r=<rounds>,p=<parallelization>$<salt>$<hash>$<salt_separator>$<signer_key>

Parameters​

  • mem_cost(number): CPU/memory cost as given by
  • rounds(number): rounds firebase hash config parameter (must satisfy r * p < 2³⁰)
  • parallelization(number): parallelization parameter (must satisfy r * p < 2³⁰)
  • salt(string): A sequence of bits, known as a cryptographic salt encoded to Base64.
  • hash(string): The computed derived key by the SCrypt algorithm encoded to Base64.
  • salt_separator(string): Firebase hash config parameter encoded to Base64.
  • signer_key(string): Firebase hash config parameter encoded to Base64.

Example​

$firescrypt$ln=14,r=8,p=1$sPtDhWcd1MfdAw==$xbSou7FOl6mChCyzpCPIQ7tku7nsQMTFtyOZSXXd7tjBa4NtimOx7v42Gv2SfzPQu1oxM2/k4SsbOu73wlKe1A==$Bw==$YE0dO4bwD4JnJafh6lZZfkp1MtKzuKAXQcDCJNJNyeCHairWHKENOkbh3dzwaCdizzOspwr/FITUVlnOAwPKyw==

Social sign-in connections​

Similar to importing passwords it is possible to import social sign-in connections as well. If you do not have Social Sign In set up yet please head over to the social sign in documentation.

When importing social sign in connections, the provider refers to the provider ID you set in your Social Sign In configuration. The subject ID must be the ID of the user on the given platform. Usually, this is the sub claim of the OpenID Connect ID Token provider such as Google.

{
  "schema_id": "preset://email",
  "traits": {
    "email": "docs-oidc@example.org"
  },
  "credentials": {
    "oidc": {
      "config": {
        "providers": [
          {
            "provider": "github",
            "subject": "12345"
          },
          {
            "provider": "google",
            "subject": "12345"
          }
        ]
      }
    }
  }
}