Skip to main content

Managing Identities

At the core of Hanko Identity are - as the name suggests - identities. An identity is the "who" of a software system. It can be a for example a customer, employee, user, or even an application. In Hanko Identity, the concept of an identity and a user are not considered distinct, so we use these terms interchangeably.

Identity schemas & Identity traits

Identities have a schema and each identity, theoretically, can have a different schema. The schema is used to validate any changes to existing identities. Identity characteristics are represented by traits that to allow for establishing different identity types. Traits are supposed to be modified by the identity itself e.g. as part of identity self-service management or by administrative entities through the Admin API.

Hanko Identity currently provides a single default schema with a small, fixed set of traits for all identities. Following is a representation of the most common properties of the default schema:

Hanko Identity default identity schema
# Every identity has a state. Inactive identities will not be able to log into the system.
state: active

# An identifier for the schema. Primarily of concern when using identity CRUD operations
# via the Admin API (see below for details).
schema_id: default

# Traits represent information about the identity, such as the first or last name.
# The traits content is currently fixed but customization is planned for a future
# release.
traits:
email: john.doe@example.com
name:
first: John
last: Doe
academic-degree: Dr.

Identities can be created, updated and deleted. The exact modalities of the operations depend on the manner in which you interact with Hanko Identity. Basically, there are three ways to manage identities:

Identity management via self-service

Users can manage their identity information in a self-service manner through their Hanko Identity profile page.

Users can access their profile page by accessing https://{HANKO_IDENTITY_TENANT_DOMAIN}/profile after having authenticated to Hanko Identity.

The profile page allows users to edit their basic identity traits (a.k.a. account settings) and manage their WebAuthn credentials for authenticating with Hanko Identity.

Manage identity properties through account settings

In their profile, users can currently change their first name, last name, and add an academic degree in their account settings (these are the properties that correspond with the traits defined in the current default Identity schema described above).

Hanko Identity main 'Account & Security' profile page
Figure 1: Hanko Identity main "Account & Security" profile page
Hanko Identity 'Account settings' page
Figure 2: Hanko Identity "Account settings" page

Manage WebAuthn credentials

In the profile users can also use their device to register, edit and delete WebAuthn credentials by making use of their device's built-in biometric capabilities. Head over to the Authentication Methods section to learn how Hanko Identity uses WebAuthn for authentication.

Hanko Identity WebAuthn credentials section in the profile
Figure 3: Hanko Identity WebAuthn credentials section in the profile

Identity management via management UI

COMING SOON

Identity management through the management UI is planned for a future release.

Identity management via admin API

Users can also be managed through a RESTful admin API. View the OpenAPI based specification for this API here.

Get an access token

To access the admin API you need to create API credentials, use these credentials to get an access token, and then use this access token to perform operations with the API.

Create API credentials

To create API credentials:

  1. Sign in to the Hanko Console.
  2. Select your organization.
  3. Select your Hanko Identity project.
  4. Select the "Users" section in the side menu.
  5. In the "API credentials" panel, click the "Add new" button.
  6. In the shown modal, give your credential a name (can be changed later) and click the "Create" button.
  7. A modal shows your client credentials - the shown client secret is confidential information and should be stored securely, it will only be shown this once. Click "Ok" to finish credential creation.
  8. Select the authentication method you want to use for requesting access tokens from the token endpoint:
    • client_secret_basic: You must send credentials using HTTP Basic Authorization.
    • client_secret_post: You must send credentials in the body of an HTTP POST request as application/x-www-form-urlencoded parameters.

When creating credentials the following additional information is shown in the credential detail view:

  • Token endpoint: This is the endpoint to use for retrieving an access token (see next section). Its value will be set automatically.
  • Audience: The audience identifies the intended recipient for the token. Its value will be set automatically.

Retrieve access token

To retrieve an access token you need:

  • Your Hanko Identity tenant domain - you can find it on the dashboard of your Identity project in the Hanko Console
  • Your Client ID and Client Secret - these are the credentials you created in the previous section
  • The Audience information for your credentials - you can find it in the credential details for the credentials you created in the previous section
Using basic client secret method

If your credentials are configured for use with the client_secret_basic authentication method, you can request an access token by making a request to the /oauth2/token endpoint using HTTP Basic Authorization. To do so, concatenate your credentials with a colon and base64 encode the resulting string ({CLIENT_ID}:{CLIENT_SECRET}). Then use this value in the Authorization header.

curl -X POST 'https://{HANKO_IDENTITY_TENANT_DOMAIN}/oauth2/token' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic ZDRiZjI5MzEtY2RkNS00ZWU1LThiNzctYmJlMTNhZDU5N2YyOm9pZGNDbGllbnRTZWNyZXQ=' \
-d 'grant_type=client_credentials' \
-d 'scope=openid' \
-d 'audience={AUDIENCE}'
Using post client secret method

If your credentials are configured for use with the client_secret_post authentication method, you can request an access token by making a request to the /oauth2/token endpoint using your API credentials in the POST body:

curl -X POST https://{HANKO_IDENTITY_TENANT_DOMAIN}/oauth2/token \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d client_id={CLIENT_ID} \
-d client_secret={CLIENT_SECRET} \
-d grant_type=client_credentials \
-d scope=openid \
-d audience={AUDIENCE}
Access token response

Hanko Identity responds with the following data:

{
"access_token": "rxH7Bdxw488bRf8Z1XksDqPRquH4UM0LW796J-mKB3Y.GRzv0vLrNQ...",
"expires_in": 3599,
"scope": "openid",
"token_type": "bearer"
}

You can now use the access_token value to perform operations with the Identity Admin API using the Bearer Token authorization scheme:

Authorization: Bearer {ACCESS_TOKEN}

Common admin API operations

Below you will find some short examples for common user management operations. For detailed operation descriptions consult the API reference.

Get single identity

You can retrieve info about a single identity (API reference):

curl -X GET 'https://{HANKO_IDENTITY_TENANT_DOMAIN}/admin/identities/{IDENTITY_ID}' \
-H 'Accept: application/json'
-H 'Authorization: Bearer {ACCESS_TOKEN}'

List identities

You can list all identities for this tenant (API reference):

curl -X GET 'https://{HANKO_IDENTITY_TENANT_DOMAIN}/admin/identities?per_page=100&page=0' \
-H 'Accept: application/json'
-H 'Authorization: Bearer {ACCESS_TOKEN}'

Create an identity

You can create an identity (API reference):

curl -X POST 'https://{HANKO_IDENTITY_TENANT_DOMAIN}/admin/identities' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-d '{
"schema_id": "default",
"traits": {
"email": "john.doe@example.com",
"name": {
"first": "John",
"last": "Doe"
}
}
}'

Update an identity

You can update an identity (API reference):

curl -X PUT 'https://{HANKO_IDENTITY_TENANT_DOMAIN}/admin/identities/{IDENTITY_ID}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-d '{
"schema_id": "default",
"state": "inactive",
"traits": {
"email": "john.doe@example.com",
"name": {
"first": "John",
"last": "Doe",
"academic-degree": "Dr."
}
}
}'