overview.md

description
User, Session, Client resources and mechanics explained

User, Session, Client resources

User

This table outlines the attributes of the User resource and their descriptions.

path	type	description
User.active	boolean	Ignored Attribute. Indicates the user's administrative status.
User.addresses	array of objects	A collection of physical mailing addresses for the user. Common types: 'work', 'home', 'other'. Each entry may include the fields below.
User.addresses.country	string	Country name component of the address.
User.addresses.formatted	string	The full mailing address formatted for display or label printing. May contain newlines.
User.addresses.locality	string	The city or locality component.
User.addresses.postalCode	string	The zip or postal code component.
User.addresses.region	string	The state or region component.
User.addresses.streetAddress	string	The full street address, possibly multiline (e.g., house number, street name, etc.). May contain newlines.
User.addresses.type	string	A label for the address function, e.g., 'work' or 'home'.
User.costCenter	string	The name of a cost center associated with the user.
User.data	any	Arbitrary user-related data.
User.department	string	The name of a department associated with the user.
User.displayName	string	The user's display name, ideally their full name.
User.division	string	The name of a division associated with the user.
User.email	email	The user's primary email address.
User.emails	array of objects	A collection of the user's email addresses. The service should provide canonical forms, e.g., lowercase. Common types: 'work', 'home', 'other'.
User.emails.display	string	A human-readable label for the email address (read-only).
User.emails.primary	boolean	Indicates if this is the primary/preferred email. Only one can be true.
User.emails.type	string	The function label for the email (e.g., 'work', 'home').
User.emails.value	string	The user's email address, canonicalized.
User.employeeNumber	string	A numeric or alphanumeric identifier assigned by the organization.
User.entitlements	array of objects	A list of entitlements the user has.
User.entitlements.display	string	A human-readable label for the entitlement (read-only).
User.entitlements.primary	boolean	Indicates if this entitlement is primary. Only one can be true.
User.entitlements.type	string	A label indicating the entitlement's function.
User.entitlements.value	string	The value of the entitlement.
User.fhirUser	Reference	A reference to a related FHIR resource (Patient, Practitioner, or Person).
User.gender	string	The user's gender.
User.identifier	array of Identifier	A list of identifiers for the user.
User.ims	array of objects	A collection of instant messaging addresses for the user.
User.ims.display	string	A human-readable label for the IM address (read-only).
User.ims.primary	boolean	Indicates if this IM address is primary. Only one can be true.
User.ims.type	string	The function label for the IM address (e.g., 'aim', 'gtalk').
User.ims.value	string	The user's instant messaging address.
User.inactive	boolean	Indicates the user's administrative status.
User.link	array of objects	A collection of references or links associated with the user.
User.link.link	Reference	A referenced resource link.
User.link.type	string	A label indicating the link's function.
User.locale	string	The user's default locale, used for localization (e.g., formatting dates, numbers).
User.manager	Reference	The user's manager, referencing another user by id.
User.name	object	The components of the user's real name.
User.name.familyName	string	The user's family (last) name.
User.name.formatted	string	The user's full name, formatted for display.
User.name.givenName	string	The user's given (first) name.
User.name.honorificPrefix	string	The user's honorific prefix(es), e.g., 'Ms.'.
User.name.honorificSuffix	string	The user's honorific suffix(es), e.g., 'III'.
User.name.middleName	string	The user's middle name(s).
User.organization	Reference	A reference to the user's associated organization.
User.password	password	The user's cleartext password, used for initial setup or resets.
User.phoneNumber	string	The user's primary phone number.
User.phoneNumbers	array of objects	A collection of phone numbers for the user. Common types: 'work', 'home', 'mobile', etc. Should follow RFC 3966.
User.phoneNumbers.display	string	A human-readable label for the phone number (read-only).
User.phoneNumbers.primary	boolean	Indicates if this phone number is primary. Only one can be true.
User.phoneNumbers.type	string	The function label for the phone number (e.g., 'work', 'home').
User.phoneNumbers.value	string	The user's phone number.
User.photo	uri	The user's primary photo.
User.photos	array of objects	A collection of photo URLs for the user.
User.photos.display	string	A human-readable label for the photo (read-only).
User.photos.primary	boolean	Indicates if this photo is primary. Only one can be true.
User.photos.type	string	The function label for the photo, e.g., 'photo' or 'thumbnail'.
User.photos.value	uri	The URL of a user photo.
User.preferredLanguage	string	The user's preferred language (e.g., 'en_US').
User.profileUrl	uri	A URL pointing to the user's online profile.
User.roles	array of objects	A collection of roles for the user, e.g., 'Student', 'Faculty'.
User.roles.display	string	A human-readable label for the role (read-only).
User.roles.primary	boolean	Indicates if this role is primary. Only one can be true.
User.roles.type	string	A label indicating the role's function.
User.roles.value	string	The value of the role.
User.securityLabel	array of objects	A list of security labels associated with the user.
User.securityLabel.code	string	The code value of the security label.
User.securityLabel.system	string	The code system of the security label.
User.timezone	string	The user's time zone, in Olson format (e.g., 'America/Los_Angeles').
User.title	string	The user's title, e.g., "Vice President."
User.twoFactor	object	Two-factor authentication (2FA) settings for the user.
User.twoFactor.enabled	boolean	Indicates if two-factor authentication is currently enabled.
User.twoFactor.secretKey	string	The TOTP secret key for 2FA.
User.twoFactor.transport	string	The method of delivering the 2FA code. If absent, no code is sent.
User.userName	string	A required unique identifier used by the user for authentication.
User.userType	string	Defines the relationship between the organization and the user (e.g., 'Employee', 'Contractor').
User.x509Certificates	array of objects	A collection of X.509 certificates issued to the user.
User.x509Certificates.display	string	A human-readable label for the certificate (read-only).
User.x509Certificates.primary	boolean	Indicates if this certificate is primary. Only one can be true.
User.x509Certificates.type	string	A label indicating the certificate's function.
User.x509Certificates.value	base64Binary	The value of the X.509 certificate.

Sessions

For each user login Aidbox creates Session resource

{% code title="Get last 10 sessions" %}

select cts, resource#>>'{user,id}'
from session
order by cts desc
limit 10

{% endcode %}

Session expiration

Basically, all sessions stored in Aidbox are infinite, and you have to manage session expiration by yourself manually.

However since Aidbox v:2205 Session.exp field was added. It represents NumericDate from RFC7519 and it identifies the expiration time after which the Session will not be accepted for processing.

You can specify auth.*.access_token_expiration (in seconds) on Client resource, so Session.exp field will be propagated once corresponding grant_type is used to launch a Session.

Session expiration for Aidbox UI

In Aidbox version v:2402 and later, sessions created through the Aidbox UI log-in are not infinite. The default session expiration time is set to 432000 seconds (5 days). To change the default time, create an AuthConfig resource and set the asidCookieMaxAge to the desired value:

PUT /AuthConfig/my-auth-config
content-type: text/yaml
accept: text/yaml

asidCookieMaxAge: 86400 # seconds

Client

To provide programmatic access to Aidbox you have to register a Client resource.

Client.audience

A Client can have the audience attribute. The audience shows what resource server access is intended for. Aidbox compares the audience of the Client to the audience it receives within aJWT and decides if the access should be granted.

The audience attribute can be defined in 2 ways:

• As a plain string. For example, https://cmpl.aidbox.app/smart
• As a Regex. In that case, the audience value should start with the # symbol. For example, #https://cmpl.aidbox.app/tenant/[^\]/smart

{% hint style="info" %} That validation of the audience happens when SMART on FHIR app launches {% endhint %}

Client.grant_types

Client resource must have grant_types attribute defining authentification scheme for this Client.

Application grant types (or flows) are methods through which applications can gain Access Tokens and by which you grant limited access to your resources to another entity without exposing credentials.

Grant types are choosed appropriately based on the grant_types property of your Auth0-registered Application. The OAuth 2.0 protocol supports several types of grants, which allow different types of access. To see available grant types and grant type mapping refer to the doc.

Other required attributes are determined based on the values of this attribute grant_types is an array of strings, possible values are:

• basic
• client_credentials
• password
• implicit
• authorization_code
• code

{% hint style="info" %} You can find different authorization flow examples in the Auth Sandbox in the Aidbox ui {% endhint %}