Skip to main content
Version: 8.2405.x.x RR

Administrative operations

The following general administrative operations are offered for the management of entities in nevisIDM.

If not mentioned otherwise, an administrative operation honors all provided fields in the operation request and maps them to corresponding fields in nevisIDM. For example, if createUser is called with a user parameter that has name set to Smith, a nevisIDM user is created with the name set to Smith.

User​

User createUser(User user)​

Creates a new user. Uses only the attributes of the user object and property values. Does not create credentials or profiles for the user.

Returns:

  • the user‘s extId
  • the user’s loginId

User createUserWithCredentials(User user)​

Creates a new user. Same as createUser, but additionally allows supplying credentials with the user object.

Notes and requirements:

  • the credentials‘ types are mandatory

Returns:

  • the user‘s extId
  • the user’s loginId
  • the credentials‘ extIds
  • the credentials‘ generated plain values (only displayed for passwords, tickets and temporary strong passwords if the policy is defined that a part has to be returned to the caller/admin, see the chapter "Facing of web GUI design").

User createUserWithProfile(User user)​

Creates a new user. Same as createUser, but additionally allows supplying profiles for the user object.

Notes and requirements:

  • the units are mandatory
  • any referenced role or unit must already exist
  • the profiles' names are optional. If they are not set, the profiles will get generated names: Profile-<userLoginId>, Profile-<userLoginId>-2, ...

Returns:

  • the user‘s extId
  • the user’s loginId
  • the profiles’ extIds

User createUserWithProfileAndCredentials(User user)​

Creates a new user. Same as createUser, but additionally allows supplying credentials and profiles for the user object.

Notes and requirements:

  • the credentials‘ types are mandatory
  • the units are mandatory
  • any referenced role or unit must already exist
  • the profiles' names are optional. If they are not set, the profiles will get generated names: Profile-<userLoginId>, Profile-<userLoginId>-2, ...

Returns:

  • the user‘s extId
  • the user’s loginId
  • the profiles’ extIds
  • the credentials‘ extIds
  • the credentials‘ generated plain values (only for passwords, tickets and temporally strong passwords if the policy is defined that a part has to be returned to the caller/admin, see the chapter "Facing of web GUI design").

void updateUser(User user)​

Updates the attributes and property values of the specified user (identified by extId).

The operation has the following side effects on version 43 and lower:

An update of a user's state will result in the following updates of the user's profile states:

  • If the user's new state is "ARCHIVED" and the profile state is not "ARCHIVED", the profile will be archived. In case of a deputed profile, the profile will be deleted.
  • If both the user's new state and the profile state are not "ARCHIVED", and the profile state does not match the user's new state, then the profile state will be updated to the user's new state. For example, if you activate a disabled user with two disabled profiles, the result will be an active user with two activated profiles.

void deleteUser(User user)​

Deletes the specified user (identified by extId).

void sendUserNotification(User user, SendingMethod sendingMethod, CommEventType commEventType, boolean synchronous)​

Sends notifications about the user attributes to the user by triggering the event identified by parameter "commEventType". Supported values for "commEventType" are:

  • USER_NOTIFICATION_1
  • USER_NOTIFICATION_2
  • .......
  • USER_NOTIFICATION_20
  • NEVISADAPT_NOTIFICATION

If synchronous is set to "true", the notification will be sent directly. The response will contain errors that occurred during sending of the notification. If it is set to false, an asynchronous event will be triggered, which notifies the user.

Profile​

Profile createProfile(Profile profile)​

Creates a new profile.

Notes and requirements:

  • The user to which the profile belongs must exist
  • The unit to which the profile belongs must exist
  • The roles attached to a profile must exist

Returns:

  • If the operation succeeds, it will return a profile object containing the extId of the newly created profile.

void updateProfile(Profile profile)​

Updates the specified profile (identified by extId).

Notes and requirements:

  • The profile‘s external ID, the profile user‘s external ID and the assigned authorizations/roles cannot be modified.
  • To change the profile‘s authorizations, use addAuthorizationToProfile and removeAuthorizationFromProfile.
  • The method supports the modification of properties of the scopes onProfileGlobal, onProfileForApp, and onProfileForAppGlobal.
  • Omit the "defaultProfile" attribute if you do not want to change the default flag of the profile. Any value other than "true" will be interpreted as "false" by the web service stack.
  • It is not allowed to change "defaultProfile" from true to false, since exactly 1 profile of every user must be marked as default at any point in time.

void deleteProfile(Profile profile)​

Deletes the specified profile (identified by ExtId).

void addAuthorizationToProfile(Profile profile, Authorization authorization)​

Adds a specific authorization to a profile. In case of nevisIDM roles, one may specify the authorized applications, clients and units, or set the global flags for these.

void removeAuthorizationFromProfile(Profile profile, Authorization authorization)​

Removes the authorization for a specific role from a profile.

Credential​

Credential createCredential(Credential cred, MobileSignature mobileSignature, SamlFederation samlFederation, SecurityQuestions securityQuestions)​

Creates a new credential.

Notes and requirements:

  • The type is mandatory.
  • For Context password credentials, the context is mandatory.
  • For certificates (property scope on_credential_certificate_global) and for generic credentials (property scope on_credential_generic_global), property values can be specified.
info

It is possible to override the default values of a credential’s validFrom and validTo fields. However, if a user changes his password through the self administration UI, the system resets the credential's validity period according to the credential policies.

Creating mobile signature credentials is supported as well.

Notes and requirements regarding mobile signature credentials:

  • The identifier, msspIdentifier and msisdn are mandatory attributes.
  • property scope ON_CREDENTIAL_MOBILESIGNATURE_GLOBAL property values can be specified.

Creating SAML federation credentials is supported as well.

Notes and requirements regarding SAML federation credentials:

  • The issuerNameId and subjectNameId attributes are mandatory.
  • The issuerNameIdFormat and subjectNameIdFormat attributes are not mandatory. If they are not set, the default value set in the SAML federation policy will be used.
  • property scope ON_CREDENTIAL_SAMLFEDERATION_GLOBAL property can be specified.
  • The property values have to be set in the SamlFederation object.

Creating security question credentials is supported as well.

Notes and requirements regarding security question credentials:

  • The personal answer and personal question attributes are mandatory.
  • The personal question can be specified by its extId.
  • property scope ON_CREDENTIAL_SECURITYQUESTIONS_GLOBAL property can be specified. The property values have to be set in the SecurityQuestions object.

Returns:

  • If the operation succeeds, it will return a Credential object containing the extId of the newly created credential.

List<Credential> createPUKCredential(Credential pukCred, Boolean createPasswordFlag, String passwordPolicyName)​

Creates a new credential of type PUK (personal unblocking key). If the "createPasswordFlag" is set to "true", a password credential will be created automatically too, according to the policy identified by "passwordPolicyName". The created credentials (PUK and optional password) will be returned to the caller. Note: Both creden-tials are generated in the same transaction and trigger one single event holding the full PUK and password.

Notes and requirements:

  • The type is mandatory and must be "PUK".
  • The basic behavior is the same as that of createCredential.
  • If the request contains createPasswordFlag=true, but the user already owns a password credential, the existing password will be reset automatically.

Returns:

  • If the operation succeeds, it will return a list of credential objects containing the extIds of the newly created credentials.

Credential resetCredential(Credential cred)​

Resets an existing credential.

Notes and requirements:

  • only supported for credential types that are resettable, e.g., passwords, PUKs, etc.
  • The previous reset approach (call updateCredential with stateChangeReasonCode "reset") remains supported but becomes deprecated.
  • modificationComment of input credential is always adopted.
  • The state of input credential is adopted, if provided. Else, the previous state of the credential is kept.
  • The new value of the credential will be set if provided. Else, the new value will be generated.

Returns:

  • If the operation succeeds, it will return the reset credential object.

void updateCredential(Credential cred)​

Updates the specified credential (identified by extId).

Updating of the credential’s property values is not supported yet.

info

It is possible to override the default values of a credential’s validFrom and validTo fields. However, if a user changes his password through the self administration UI, the system resets the credential's validity period according to the credential policies.

Updating SAML federation, mobile signature and security question credentials is supported.

Notes and requirements regarding SAML federation credentials:

  • The issuerNameId and subjectNameId are mandatory attributes, so they cannot be deleted.
  • Property scope: ON_CREDENTIAL_SAMLFEDERATION_GLOBAL property values can be updated.
  • The property values have to be set in the SamlFederation object.

Notes and requirements regarding mobile signature credentials:

  • The identifier and msisdn are mandatory attributes, so they cannot be deleted.
  • The msspIdentifier attribute is mandatory if no default value is set in the mobile signature policy.
  • Property scope: ON_CREDENTIAL_MOBILESIGNATURE_GLOBAL property values can be updated. The property values have to be set in the MobileSignature object.

Notes and requirements regarding security question credentials:

  • The question is mandatory.
  • The personal question can be specified by its extId.
  • If the answer is empty, the PersonalAnswer object will be deleted.
  • Property scope: ON_CREDENTIAL_SECURITYQUESTIONS_GLOBAL property values can be updated. The property values have to be set in the SecurityQuestions object.

Notes and requirements regarding Context password credentials:

  • For Context password credentials, the context attribute cannot be changed or deleted.

void deleteCredential(Credential cred)​

Deletes the specified credential (identified by extId) and its property values.

void deleteCredentials(List<Credential> creds)​

This is a batch operation that deletes a list of credentials according to their extId in one single transaction (all or nothing). In case of an error the whole transaction will be rolled back, and a BusinessException will be thrown. BusinessException’s element "elementIndex" will hold the index of the erroneous entry (starting with index 0).

Credential unlockCredential(Credential cred)​

Unlock credential operations (identified by extId). Possible unlock codes via values.

void assignCredential(Credential cred, User user) - Supported only for credentials of type "VASCO"​

Assigns the specified credential to the specified user, both identified by their extid. Supported only for spare (i.e., not assigned) credentials of type "VASCO". All other credential types must be assigned to a user at creation time and will stay assigned to the same user during their complete lifetime. After assigning a Vasco Digipass token credential to a user, its state will be ACTIVE.

void unassignCredential(Credential cred) - Supported only for credentials of type "VASCO"​

Unassigns the specified credential identified by its extid from the currently assigned user. Supported only for credentials of type "VASCO". Therefore, there is a virtual pool of spare Vasco Digipass token credentials to which the unassigned credential is added. Afterwards, it can be re-assigned to another user with a call to "assignCredential" (see above). After unassinging the Vasco Digipass token credential from a user, its state will be INITIAL.

MobileSignature createMobileSignature(MobileSignature mobileSignature)​

This operation is deprecated. Use the createCredential operation instead.

void updateMobileSignature(MobileSignature mobileSignature)​

This operation is deprecated. Use the updateCredential operation instead.

SecurityQuestions revealSecurityQuestions(SecurityQuestions securityQuestions)​

Reveals the plain content of the selected PersonalAnswer entities to the caller. This is analogous to when you reveal the plain content of an answer on the nevisIDM admin GUI.

Notes and requirements:

  • It is possible to reveal one or more PersonalAnswer entities in one request.
  • The credentialExtId, clientExtId and the question extId attributes are mandatory.

ShareOATHResult shareOATH(String credentialExtId)​

Shares the OATH credential identified by the credentialExtId.

The operation returns the OATH attributes, like authentication type, algorithm, digits, counter, period, issuer, account and the secret. It also returns a base64 encoded QR code image which can be used to share the secret with a mobile device and the content of the QR code in plain string.

Unit​

Unit createUnit(Unit unit)​

Creates a new unit.

Notes and requirements:

  • Name must be specified.
  • Name must be unique within the set of subunits of the parent unit.
  • If the parent unit is not set, the unit will be created as a main unit of the given client.
  • The unit’s extId can be specified (optional). If it is specified, the value must be unique within the provided client. If it is omitted, nevisIDM will generate an extId automatically.

Returns:

  • If the operation succeeds, it will return a unit object containing the extId of the newly created unit.

void updateUnit(Unit unit)​

Updates the specified unit (identified by extId).

Notes and requirements:

  • The unit’s client cannot be changed.
  • The request must contain a non-empty extId that exists.

void deleteUnit(Unit unit)​

Deletes the specified unit (identified by extId).

Application​

Application createApplication(Application a, List<Client> assignedClients)​

Creates a new application and its roles.

If the operation succeeds, it will return the newly created Application object.

If nevisIDM runs with multiple clients, the clients the application has to be assigned to need to be defined. Otherwise, the application is not assigned to any client, and only users with client-global authorization will be able to manage the applications.

void updateApplication(Application a)​

Updates the specified application (identified by extId). In case the application roles are provided too, updateApplication() will automatically create or modify these roles:

  • If the role extId is not set, the role will be created.
  • If the role extId is set and the role does not exist, it will be created.
  • If the role extId is set and the role already exists, it will be updated.

void deleteApplication(Application a)​

Deletes the specified application (identified by name).

void addRoleToApplication(Application a, Role r)​

Adds a role to the specified application.

void removeRoleFromApplication(Application a, Role r)​

Removes a role from the specified application.

Policy​

void assignPolicies(List<Policy> pList, Unit u)​

Assign policies in pList to Unit u. The method is also used to switch the default flag. To do so, just call assignPolicies and pass the new default policy with the default flag set to "true".

Notes and requirements:

  • unit.extId must be defined, unit must exist
  • policy.name must be defined, policy must exist

void revokePolicies(List<Policy> pList, Unit u)​

Revoke assignments of the policies in pList from Unit u.

Notes and requirements:

  • unit.extId must be defined, unit must exist
  • policy.name must be defined, policy must exist

Policy createPolicy(Policy p)​

Creates a new policy configuration.

Notes and requirements:

  • Name must be specified.
  • The name and policy type combination must be unique within the client.
  • The extId is optional. It must be unique within the client.
  • The client the policy belongs to must be specified.

Returns:

  • If the operation succeeds, it will return the newly created policy object.

void updatePolicy(Policy p)​

Updates the specified policy configuration. The policy is identified by its extId.

void deletePolicy(Policy p)​

Deletes the specified policy configuration. The policy is identified by its extId.

Client​

Client createClient(Client c)​

Creates a new client.

Notes and requirements:

  • The name must be specified.
  • The external ID extId is optional. It must be unique.

Returns:

  • If the operation succeeds, it will return the newly created client object.

void updateClient(Client c)​

Updates the specified client. The client is identified by its extId.

Template​

Template createTemplate(Template t)​

Creates a new template and its template contents. The template collection is not supported in the web service tier, so it always uses the default template collection of the selected client.

Notes and requirements:

  • documentType is mandatory
  • commEventType is mandatory
  • The extId is optional. It must be unique within the client.
  • precedence is optional. If it is not set, the template will be created with precedence 0.
  • The combination of documentType, commEventType and precedence has to be unique within the template collection.
  • The language-dependent content can be set as a list of TemplateContents.
  • The binary content of the TemplateContent has to be Base64-encoded.

Currently, multipart messages are not supported by the web service stack of nevisIDM, so be sure to inline the binary data to your SOAP request instead of creating an attachment with the binary data.

Returns:

  • If the operation succeeds, it will return the newly created template object and its contents.

void updateTemplate(Template t)​

Updates the specified template and creates or modifies its template contents. The template is identified by its extId.

void deleteTemplate(Template t)​

Deletes the specified template (identified by extId).

EnterpriseRole​

EnterpriseRole createEnterpriseRole (EnterpriseRole er)​

Creates a new enterprise role.

Notes and requirements:

  • name must be specified. It must be unique within a client.
  • The extId is optional. It must be unique within a client.

Returns:

  • If the operation succeeds, it will return the newly created enterprise role object.

void updateEnterpriseRole (EnterpriseRole er)​

Updates the specified enterprise role (identified by extId).

Notes and requirements:

  • The client of the enterprise role cannot be changed.
  • The request must contain a non-empty extId that exists.

void deleteEnterpriseRole (EnterpriseRole er)​

Deletes the specified enterprise role (identified by extId).

void assignRolesToEnterpriseRole (EnterpriseRole er, List<Role> roles, Boolean failIfAssigned)​

Adds application roles identified by extId to EnterpriseRole identified by extId.

Note that the application of each role has to be visible within the client of the enterprise role.

  • failIfAssigned (default:true): If true, the operation will fail in case one of the roles is already assigned to the enterprise role.

void unassignRolesFromEnterpriseRole (EnterpriseRole er, List<Role> roles, Boolean failIfNotAssigned)​

Removes application roles identified by extId from EnterpriseRole identified by extId.

  • failIfNotAssigned (default:true): If true, we throw a business exception in case one of the roles is not assigned to the enterprise role.

void addEnterpriseRoleToProfile (Profile profile, EnterpriseRole er)​

Adds the enterprise role identified by extId to the profile identified by extId.

void removeEnterpriseRoleFromProfile (Profile profile, EnterpriseRole er)​

Removes the enterprise role identified by extId from the profile identified by extId.

PersonalQuestion​

PersonalQuestion createPersonalQuestion (PersonalQuestion personalQuestion)​

Creates a new personal question.

Notes and requirements:

  • The extId is optional, but it must be unique within a client.

Returns:

  • If the operation succeeds, it will return the newly created personal question object.

void updatePersonalQuestion(PersonalQuestion personalQuestion)​

Updates the specified personal question (identified by extId).

Notes and requirements:

  • The client of the personal question cannot be changed.
  • The request must contain a non-empty extId that exists.

void deletePersonalQuestion(PersonalQuestion personalQuestion)​

Deletes the specified personal question (identified by extId).

PasswordPolicyCheckResult checkPasswordPolicy(String password, String policyExtId, String unitExtId)​

Check password value against policy without creating a real password credential.

Notes and requirements:

  • password is mandatory
  • One of the parameters policyExtId and unitExtId must be provided.

If policyExtId is set, check the password against the policy identified by the policyExtId. Otherwise, use the default password policy of the unit identified by the unitExtId.

Returns:

  • If the password violates the policy, the operation will return a PasswordPolicyCheckResult object that contains all information about the policy and about the violated parts of the policy.

Bulk Authorizations​

void addAuthorizationsToProfiles(List<Profile> profiles, List<Authorization> authorizations, Boolean failIfExists)​

Deprecated

This call is deprecated because it does not respect the data room restrictions, but only checks functional authorization.

Instead, use addAuthorizationToProfile.

Adds all authorizations to all profiles.

If failIfExists is true, an already existing authorization will cause the operation to fail; otherwise, it just continues.

FailIfExists defaults to true.

void removeAuthorizationsFromProfiles(List<Profile> profiles, List<Authorization> authorizations, Boolean failIfNotExists)​

Deprecated

This call is deprecated because it does not respect the data room restrictions, but only checks functional authorization.

Instead, use removeAuthorizationFromProfile.

Removes all authorizations from all profiles.

If failIfNotExist is true, an inexisting authorization will cause the operation to fail; otherwise, it just continues.

FailIfNotExists defaults to true.

void updateDataroomOfAuthorization(List<Profile> profiles, Authorization authorization, Mode mode, Boolean failIfNotExists)​

Deprecated

This call is deprecated because it does not respect the data room restrictions, but only checks functional authorization.

Updates the data room of authorization for all profiles.

Mode describes how the data room should be updated:

  • If mode is "add", all data room permissions of authorization are added to the respective authorizations in each profile, updating the global flags.
  • If mode is "remove", all the data room permissions of authorization are removed from the respective authorizations in each profile, updating the global flags.
  • If mode is "recreate", the data room permissions are completely rebuilt from the provided data room permissions, i.e., the old data room permissions are discarded and replaced with the provided ones.
  • If failIfNotExist is "true", the operation will fail if the referred authorization does not exist in one of the profiles or the authorization data room element has already been added/removed.

failIfNotExists defaults to true.