Version: 8.2405.x.x RR

Developer Use Cases

This chapter describes specific use cases for nevisIDM, including their behavior and configuration.

The General Data Protection Regulation (GDPR) is a regulation issued by the European Union to strengthen and unify data protection. The REST API of nevisIDM allows marking user-related data to classify information, as is required in the GDPR business case.

Configuration

Marking user-related data is possible through client policy configuration. The following is a sample configuration of the client policy:

data.classifications=[gov, sensitive, personal]

data.classifications.personal.user=[name.firstName, name.familyName, contacts.mobile]
data.classifications.sensitive.user=[birthDate]
data.classifications.gov.user=[languageCode]

data.classifications.personal.user.properties=[propertyName1, propertyName2]

data.classifications.personal.profile=[remarks, modificationComment]
data.classifications.gov.profile=[profileState]

data.classifications.personal.profile.properties=[propertyName1, propertyName2]

The declaration of the customized classification levels occurs in the client policy configuration parameter _data.classifications{_}. The only limitation on the defined levels is that they have to match the following regular expression: [a-zA-Z0-9]+.

The declaration of fields occurs in line with the syntax data.classifications.<level>.<dto>.

Before you are going to use a classification (level), do not forget to declare it in the client policy configuration parameter data.classifications first. Otherwise a validation error will occur. For example, the following client policy configuration will not be accepted:

data.classifications=[gov, sensitive, personal]
data.classifications.undefined.user=[name.firstName,name.familyName, contacts.mobile]

The validation of fields enforces the rule set of the data transfer object (DTO). Therefore, the validation does not accept any item that is not part of the DTO returned by the corresponding REST service. The supported DTOs are those of the user and profile. Moreover, user properties and profile properties can be classified as well. The validation is case sensitive and the hierarchical relationships among fields are enforced, too. Hence, the following scenarios would be rejected:

data.classifications.personal.user=[firstName, contacts.MOBILE]
data.classifications.sensitive.user=[randomName]
data.classifications.gov.user=[mobile]

REST response format

The following responses are only returned in the format shown below if you have configured an applicable client policy.

When querying a single user:

// GET /users/12345
{
 "extId": "12345",
 "name": {
  "firstName": "Maria",
  "lastName": "Meier"
 },
 "_classifications": {
  "personal": name.firstName", "birthDate", "contacts.mobile,
  "sensitive": birthDate,
  "gov": language
 }
}

When querying a list of users:

// GET /clients/{extId}/users/
{
 "items": [
 {
  "extId": "12345",
  "name": {
  "firstName": "Maria",
  "lastName": "Meier"
 }
 }
],
"_classifications": {
  "personal": name.firstName", "name.familyName", "contacts.mobile,
  "sensitive": birthDate,
  "gov": languageCode
 }
}

When querying properties:

// GET /{clientExtId}/profiles/{extId}/properties/
{
 "propertyName1": "value1",
 "propertyName2": "value2",
 "propertyNameN": "valueN",
 "_classifications": {
  "personal": propertyName1", "propertyName2
 }
}

(Mobile) Authentication with FIDO UAF Authenticators

In the future, and in combination with nevisFIDO, it will be possible to store FIDO UAF authenticators in nevisIDM. The FIDO Alliance provides two different standards: UAF and U2F. The Nevis Security Suite only supports UAF. The UAF standard enables a passwordless login experience, which can also be used as a second factor or mobile authentication. It includes multiple flows and variants. For more details, we recommend reading the FIDO specification or the documentation from nevisFIDO.

FIDO is built on top of public key cryptography. In nevisIDM, only the public key of an authenticator is stored. Usually an authenticator is a branded mobile app.

The FIDO standard also allows generic FIDO apps or authenticators. However, with these generic apps and authenticators, the UX and security is no longer under complete control.

An online service challenges the user to log in with a previously registered device that matches the service’s acceptance policy.
The user unlocks the FIDO authenticator with the same method he used at registration time.
The client device uses the user’s account identifier provided by the service to select the correct key and to sign the service’s challenge.
The device returns the signed challenge to the service, which verifies it with the stored public key. If everything is fine, the service logs in the user.

Information stored in nevisIDM

Attribute	Type	Validation	Description	Remarks
aaid	String(9)	`/^[0-9a-f]{4}#[0-9a-f]{4}$/i` E.g., 46AB#DE12	The authenticator attestation identifier: This is a unique identifier assigned to a model, class or batch of FIDO authenticators that all share the same characteristics. Format: HHHH#HHHH, whereby H is a hexadecimal char.	Mandatory. Read-only once set.
publicKey	String	No validation	The user authentication public key generated by the FIDO authenticator during the registration process.	Mandatory. Read-only once set.
keyId	String	`/^[a-z0-9_-]*$/i` (base64url encoding)	The key identifier of the authenticator registered key, as `base64url(byte[32...2048]).`	Mandatory. Read-only once set.
deviceId	String	No validation	The device identifier obtained from a push service, which sends push messages to this specific device.	Read-only once set.
signCounter	Integer	Must be greater than the current value.	Indicates how many times this authenticator has performed signatures in the past.	Default: 0
authenticatorVersion	Integer	Must be a non-negative number.	The version of the authenticator.	Mandatory. Read-only once set.
appId	String	No validation	OS-specific ID of the application that uses the FIDO credential.	Mandatory. Read-only once set.
publicKeyAlgorithm	String	No validation	Public key algorithm used for the public key in the authenticator record, to know how to decode the key later on.	Mandatory. Read-only once set.

Operations supported via SOAP

You can perform each of the following operations via SOAP.

Querying FIDO UAF credentials

You can access FIDO UAF credentials via SOAP in two possible ways:

Querying by type

<v1:queryCredentials>
<query>
 <clientName>Default</clientName>
 <detail>2</detail>
 <credential>
 <type>FIDO_UAF</type>
 </credential>
</query>
</v1:queryCredentials>

Querying by aaid/keyId/appId

<v1:queryCredentials>
<query>
 <clientName>Default</clientName>
 <detail>2</detail>
 <credential>
 <fidoUaf>
 <keyId>someId</keyId>
 </fidoUaf>
 </credential>
</query>
</v1:queryCredentials>

Creating FIDO UAF credentials

<v1:createCredentials>
<request>
 <clientExtId>100</clientExtId>
 <credential>
 <userExtId>someUser</userExtId>
 <state>ACTIVE</state>
 <type>FIDO_UAF</type>
 <extId>FIDO001</extId>
 <value>12346789</value>
 <fidoUaf>
 <aaid>12aF#3cdF</aaid>
 <keyId>someId</keyId>
 <appId>https://www.example.com</appId>
 <authenticatorVersion>3</authenticatorVersion>
 <signCounter>22</signCounter>
 <publicKeyAlgorithm>RSA</publicKeyAlgorithm>
  </fidoUaf>
 </credential>
</request>
</v1:createCredentials>

Updating FIDO UAF credentials

You can update FIDO UAF credentials by updating the related credential object:

<v1:updateCredential>
<request>
 <clientExtId>100</clientExtId>
 <credential>
 <extId>FIDO999</extId>
 <fidoUaf>
 <deviceId>44667987</deviceId>
 <signCounter>202</signCounter>
 </fidoUaf>
 </credential>
</request>
</v1:updateCredential>

Deleting FIDO UAF credentials

You can delete FIDO UAF credentials by deleting the related credential object:

<v1:deleteCredential>
<request>
 <clientExtId>100</clientExtId>
 <credential>
 <extId>FIDO999</extId>
 </credential>
</request>
</v1:deleteCredential>

FIDO UAF admin screen

Just as many other credential types, FIDO UAF credentials can be created, modified and deleted via the nevisIDM admin GUI. The "search by credential" type is also a supported functionality.

Terms and conditions use cases

It is possible to integrate the terms and conditions concept in a login flow of nevisAuth AuthStates. The goal is to ensure that users give consent to all required terms and conditions before they access an application service.

The terms and conditions REST API can be accessed from the nevisAuth ScriptState using the IdmRestClient as described in the chapter: Accessing nevisIDM over REST from nevisAuth ScriptState.

A login flow with an integrated terms and conditions concept includes the following steps:

User login
Getting pending terms
Creating consents

After a user login, a transition to an instance of the nevisAuth ScripState can be added.

Getting pending terms

Pending terms of a user are all the terms

that are assigned to an application for which the user profile has an assigned role, and
to which the user has not given consent yet, or not to the current version of the terms, in case silent acceptance is not enabled.

For example, if the application "Wiki" has terms assigned and the user profile includes the "Editor" role for this "Wiki" application, then the user needs to give their consent to these terms to be able to log in.

All pending terms of the user can be retrieved via the IdmRestClient using a script created with the ScriptState (such as the sample script below).

If no terms are returned, the login flow can be continued.
In case of pending terms, the list of terms and conditions URLs in the corresponding user language can be displayed on the GUI, to be read and accepted by the user.

// GET /{clientExtId}/users/{userExtId}/pending-terms/
{
 "items": [
 {
 "extId": "8865",
 "name": "Terms and conditions",
 "active": true,
 "silentAcceptance": false,
 "termsVersion": "1.0",
 "created": "2019-11-20T14:22:20Z",
 "lastModified": "2019-11-20T14:22:20Z",
 "urls": {
 "en" : "http://test-server.ch/terms_en.html",
 "de" : "http://test-server.ch/terms_de.html"
 }
  "applicationExtIds" : [1000]
 },
 {
 "extId": "8866",
 "name": "Privacy Policy",
 "active": true,
 "silentAcceptance": true,
 "termsVersion": "1.1",
 "created": "2019-11-20T14:22:20Z",
 "lastModified": "2019-11-20T14:22:20Z",
 "urls": [
 "en" : "http://test-server.ch/privacy_policy_en.html",
 "de" : "http://test-server.ch/privacy_policy_de.html"
 ]
  "applicationExtIds" : [1000]
 }
 ]
}

Creating consents

If the user does not agree to all terms and conditions, access is denied and a logout is performed.
Otherwise, a consent is created using the IdmRestClient for each accepted term and condition.

Note that giving consent is not limited to pending terms. A user can also give consent to terms that have no application assigned for which the user holds a role.

// POST /{clientExtId}/users/{userExtId}/consents/
{
 "termsExtId": "8865"
}
// POST /{clientExtId}/users/{userExtId}/consents/
{
 "termsExtId": "8866"
}

Developer Use Cases

Information classification with the REST API – GDPR business case​

Configuration​

REST response format​

(Mobile) Authentication with FIDO UAF Authenticators​

A simple login flow​

Information stored in nevisIDM​

Operations supported via SOAP​

Querying FIDO UAF credentials​

Creating FIDO UAF credentials​

Updating FIDO UAF credentials​

Deleting FIDO UAF credentials​

FIDO UAF admin screen​

Terms and conditions use cases​

Login with continuous terms and conditions acceptance​

User login​

Getting pending terms​

Creating consents​

Information classification with the REST API – GDPR business case