Gå til innhold

Webservice - Security Maintainance

  • Created by Unknown User (alexanderlk), last modified by Olti Naska on Jun 09, 2016

Technical Documentation - Security maintenance

Version 1.0.5

This service consists of two parts.

First user maintenance. In short it exposes information about users, as well as allowing creation of new users, and maintenance of data like e-mail, workPhone and login alias. 

Second part is group maintenance. It exposes group information like groupId and groupName as well as containing the userId's of all members.

Document Version Webservice Version

  • 1.0.0 Enterprise-ws 2011.1-RC1
  • 1.0.1 Enterprise-ws 2011.1.00
  • 1.0.2 Enterprise-ws 2011.1.01
  • 1.0.3 Enterprise-ws 2011.1.02
  • 1.0.4 Enterprise-ws 2015.1.00
  • 1.0.5 Enterprise-ws 2016.2.00

Root URI:

http://<host>:<port>/<context>/secure

For example\ http://visma-webservice:8090/enterprise_ws/secure

The following overview only refers to the relative URI's and should always be prefixed by the root uri.

If the credentials are not correct, a HTTP 403 FORBIDDEN response error is returned.

The input data should use charset: UTF-8.

User maintenance

Resources

GET - /user\ Returns Users element containing the User of all registered and non-deleted users.

HTTP 200 OK is returned if the request successfully succeeds.

GET - /user/<userId>\ Returns a User XML described in more details.

HTTP 200 OK is returned if the request successfully succeeds

HTTP Error codes:

404 NOT_FOUND if userId does not represent any user in the system

PUT - /user/<userId>/email/WORK/<email>

Updates the system/work-email of the user, no validation is performed with the exception of ensuring that the email address is valid and that it is not already in use.

* *  HTTP 200 OK is returned if the email has been updated

HTTP Error codes:

404 NOT_FOUND if userId does not represent any user in the system

400 BAD_REQUEST If usage is not given. (In this case it is mentioned as WORK) In general, usage may have values like WORK, PRIVATE...

400 BAD_REQUEST If email is not valid

400 BAD_REQUEST If email already exists in the system with WORK usage

PUT - /user/<userId>/email/<type>/<email>

Updates an e-mail address for a given user. Any value may be used for type. Enterprise currently utilizes WORK and PRIVATE e-mails, but others may be introduced without warning. Using custom types is possible, but not supported.

* *  HTTP 200 OK is returned if the email has been updated. Sending WORK as the type is identical to the previously mentioned PUT, including the otherwise excluded unique constraint.

HTTP Error codes:

404 NOT_FOUND if userId does not represent any user in the system

400 BAD_REQUEST If usage is not given. In general, usage may have values like WORK, PRIVATE...

400 BAD_REQUEST If email is not valid

400 BAD_REQUEST If email already exists in the system with WORK usage

DELETE - /user/<userId>/WORK/email

Removes the mail registered on the user. Care should be taken while doing this as some functionality is dependent on the e-mail being present. For example recovering username/password will be unavailable.

*   *HTTP 200 OK is returned if email is successfully removed.

HTTP Error codes:

404 NOT_FOUND if userId does not represent any user in the system

400 BAD_REQUEST If usage is not given. (In this case it is mentioned as WORK) In general, usage may have values like WORK, PRIVATE...

DELETE - /user/<userId>/<type>/email\ Removes the mail registered on the user.

*   *HTTP 200 OK is returned if email is successfully removed.

HTTP Error codes:

404 NOT_FOUND if userId does not represent any user in the system

400 BAD_REQUEST If usage is not given. In general, usage may have values like WORK, PRIVATE...

PUT - /user/<userId>/phone/<type>/<phone>\ Updated the given phone number for the user. No validation is performed here. Currently known values for type are WORK, PRIVATE and MOBILE. Other types may be stored, but as for e-mail this is not supported.

*   *HTTP 200 OK is returned if phone is successfully added.

HTTP Error codes:

404 NOT_FOUND if userId does not represent any user in the system

400 BAD_REQUEST If type is not given

PUT - /user/<userId>/password/<password>\ Sets the password for the given user. No check is made on the password other than it not being blank, the password being blank results in an HTTP 400. For purposes of password expiry it's treated as if it were changed the same day. This function must be invoked with a plain text password

*   *HTTP 200 OK is returned if password is successfully added.

HTTP Error codes:

404 NOT_FOUND if userId does not represent any user in the system

400 BAD_REQUEST If no password is provided

PUT - /user/<userId>/initials/<initials>\ Updates the initials of the user. There are strict checks on this action. The provided initials must neither be used on any other user, nor used as a username/alias/domainUser. In addition the user must not already have initials. Should one of those checks fail an HTTP 400 will be returned

*   *HTTP 200 OK is returned if initials are successfully added.

HTTP Error codes:

404 NOT_FOUND if userId does not represent any user in the system

400 BAD_REQUEST If given initials are already in use, or illegal. (F.ex.: reasonably too long such as exceeding 8 chars)

GET - /user/<userId>/username/

Returns an XML representing the domain users registered for this person.

*   *HTTP 200 OK is returned if the request successfully succeeds

HTTP Error codes:

404 NOT_FOUND if userId does not represent any user in the system

POST - /user/<userId>/username/

Request POST body form parameter Value Required

user username on domain Yes domain login domain No

Domain is an optional parameter, if omitted this will only be added as an alias which is used for manual login or login if domain name is stripped.

HTTP 200 OK is returned if the domain user is successfully added.

HTTP Error codes:

400 BAD REQUEST if the username is already in use as an alias of if the domain user is already registered.

404 NOT_FOUND if userId does not represent any user in the system

DELETE - /user/<userId>/username/<domain>/<user>

*   *HTTP 201 CREATED is returned if password is successfully added.

HTTP Error codes:

404 NOT_FOUND if userId does not represent any user in the system

DELETE - /user/<userId>/username/<user>\ Both return a HTTP 200 is the user is successfully deleted, otherwise an HTTP 500 is returned with more details.

*   *HTTP 201 CREATED is returned if password is successfully added.

HTTP Error codes:

404 NOT_FOUND if userId does not represent any user in the system

POST - /user/new/firstname/<newUserFirstname>/lastname/<newUserLastname>/initials/<newInit>/workemail/<WorkEmail>

Headers: Content-Type application/x-www-form-urlencoded;charset=UTF-8

This method creates a new internal user based on the specified inputs.

Firstname, lastname, initials, workemail are required, whereas privatemobile and alias are optional. It is possible to give several aliases at once in the form of a semicolon separated list.

It returns the userId of the newly created internal user as a text/plain;charset=utf-8.

Optional parameters may be passed in the POST request body as form data:

Request POST body form parameter Value Example

privatemobile private mobile number +47468889 alias ; separated list of aliases ALIAS1;ALIAS2

Example of calls:

http://<host>:<port>/<context>/secure/user/new/firstname/Ola/lastname/Normann/initials/OLN/workemail/Ola.Normann@web.no

*   *HTTP 201 CREATED is returned if new internal user gets successfully created

HTTP Error codes:

400 BAD_REQUEST if names are not given or reasonably too long (should not exceed 250 characters)

400 BAD_REQUEST if email is invalid or already in use with WORK usage

400 BAD_REQUEST if initials are already in use or illegal (reasonably too long such as greater than 8 characters)

400 BAD_REQUEST if too many aliases are given, or if any of the given aliased is reasonably too long (such as greater than 250 characters) 

500 INTERNAL_SERVER_ERROR with corresponding error message if something else goes not as expected 

XML samples

Users

?

<users>

<user/>

...

</users>

User

?

<user userId="..." email="..." workPhone="..." mobilePhone="..." initials="..." usertype="...">

<groupMembership />

<name displayName="..."/>

<usernames username="...">

<domainUser username="..."/>

<domainUser username="..."/>

<alias username="..."/>

</usernames>

</user>

Name

userId

email

workPhone

mobilePhone

initials

usertype

groupMembership

name

usernames

GroupMembership

?

<groupMembership>

<group id="..."/>

</groupMembership>

Name

group

id

Name

?

<name displayName="..."/>

Name displayName

Usernames

?

<usernames username="...">

<domainUser username="..."/>

<alias username="..."/>

</usernames>

Name

username

alias

domainUser

Group maintainance

Resources

GET - /group\ Returns all groups containing information about members.

GET - /group/<groupid>\ Returns a specific group containing information about members.

POST - /group/<groupId>/

Request POST body form parameter Value Example

userid userId for the new group member +47468889

Adds a user to the specified group. Group must already exist

DELETE - /group/<groupId>/user/<userId>\ Removes the specified user from the given group. The group must exist, but no exception is given if the user wasn't a group member.

XML samples

Groups

?

<groups>

<group id="..." name="...">

...

</group> 

...

</groups>    

Group

?

<group id="..." name="...">

<members>

...  

</members> 

</group>

Name

id

name

members

Members

?

<members>

<user id="..."/>

...

</members>

Name

user

id

Authorization

For all the services an HTTP Basic authentication has to be included. The username/password is looked up in Security, and has to belong to a user registered as a Security Administrator.

If no HTTP basic auth is found in the request an HTTP 401 is returned, along with a request for authentication ( The header is "WWW-Authentication" – "Basic realm=realm")

If the authenticated user is not authorized to perform any updates (is not a security administrator) an HTTP 403 is returned.

Since the authorization is performed with HTTP Basic the username and password are sent as plain text with a Base64 encoding. We strongly encourage the use of SSL (HTTPS) for the transfer to reduce the likelihood of the request being sniffed on unsecured networks.

Return codes

HTTP Status Meaning

  • 200 OK, response body contains requested information or the request was processed correctly
  • 201 Created, for exampl the username was added
  • 202 Accepted, e-mail, phone or password was updated
  • 400 Bad request, given when the username is missing from a POST or when the password change function is invoked with blank password
  • 401 No credentials passed or credentials are incorrect
  • 403 Provided credentials do not have sufficient permissions to use this service
  • 404 If userId does not represent any user in the system
  • 405 Method not allowed, could be a GET on a resource only permitting PUT or similar
  • 409 Conflict, given in cases where a requested e-mail is already in use. In the future conflicting usernames will also give this error code
  • 500 Internal Server Error, this code should be checked or logged as the system occasionally uses it to signify bad data. In a future version this will be handled properly