Web server interface

Use SOAP messages to interact with the Net iD Access Server server. The methods register, authenticate, sign, and collect are described below.

If a server calls any of the authenticate-, sign-, or collect-methods, and have not been registered on the Net iD Access Server server prior to the calls, the server will default to a dummy server named "Company ANY", and use the file image "any.png" as its logo. This feature is for testing purposes only and should not be used in a live environment.

For Information about example requests and responses using SOAP and HTTP POST, see WSDL.

Register

The register call is used for registering a service on the Net iD Access Server server.

Register – Request elements

Element	Description
<serverId>	Needed as placeholder. Leave element empty.
<name>	The desired service name that will be displayed in connecting clients.
<image>	A binary base64 encoded PNG image, no larger than 16 kB.
<format>	No value or pkcs7 = PKCS #7, raw = raw-256, raw-512

Element

Description

Needed as placeholder. Leave element empty.

<name>

The desired service name that will be displayed in connecting clients.

<image>

A binary base64 encoded PNG image, no larger than 16 kB.

No value or pkcs7 = PKCS #7, raw = raw-256, raw-512

Register – Response elements

Element	Description
<scheme>	Not used.
<provider>	NiAS server where the calling server was registered at.
	<name>	Name of the NiAS server.
	<version>	Version number of Net iD Access Server.
<caller>	The server making the register call.
	<name>	Name of the server.
	<image>	Same as the image provided in the argument.
	<id>	Server ID.

Element

Description

Not used.

NiAS server where the calling server was registered at.

<name>

Name of the NiAS server.

Version number of Net iD Access Server.

The server making the register call.

<name>

Name of the server.

<image>

Same as the image provided in the argument.

<id>

Server ID.

Authenticate

The authentication call is used to authenticate a user.

Authenticate – Request elements

Element	Description
<personalNumber>	Personal number of the user being authenticated.
<userNonVisibleData>	If null, user nonvisible data will be generated.
<endUserInfo>	Information about the end user. Not currently used.

Element

Description

Personal number of the user being authenticated.

If null, user nonvisible data will be generated.

Information about the end user. Not currently used.

Authenticate – Response elements

Element	Description
<AuthenticateResult>	String referencing the authentication order. Used as argument in Collect calls to query the order status.

Element

Description

String referencing the authentication order. Used as argument in Collect calls to query the order status.

Sign

The sign call is used for user signing.

Sign – Request elements

Element

Description

Personal number of the user signing.

Visible data to be signed.

Nonvisible data to be signed.

If using PKCS #7-signatures, <userVisibleData> and <userNonVisibleData> can be combined. When using raw-signatures only use <userNonVisibleData>.

Not currently in use.

Sign – Response elements

Element	Description
<SignResult>	String referencing the sign order. Used in Collect to query the order status.

Element

Description

String referencing the sign order. Used in Collect to query the order status.

Collect

The collect call is used for querying the status of an outstanding order, and to collect return data once the order has been completed.

Collect – Request elements

Element	Description
<orderRef>	The <AuthenticateResult> or <SignResult> strings returned by the sign and authenticate methods.

Element

Description

The <AuthenticateResult> or <SignResult> strings returned by the sign and authenticate methods.

Collect – Response elements

Element	Description
<progressStatus>	String indicating the status of the request. If COMPLETE the other fields of the response will be filled out, otherwise left empty. For a description of the status codes, see Collect – Status codes.
<signature>	Signature for content to ensure the sender is the one expected.
<userInfo>	Information about the end user.
	<name>	User name.
	<personalNumber>	User personal number.
	<notBefore>	Validity time for id.
	<notAfter>	Validity time for id.
	<givenName>	Given name of the end user.
	<surname>	Surname of the end user.
<ocspRespone>	OCSP response for the request. Only available if the authority is set to include a copy of the OCSP response in the SOAP response.
<deviceInfo>	Information about the device used to create the request.
	<name>	Platform name. May contain white space.
	<version>	Platform version.
	<address>	IP address.

Element

Description

String indicating the status of the request. If COMPLETE the other fields of the response will be filled out, otherwise left empty. For a description of the status codes, see Collect – Status codes.

Signature for content to ensure the sender is the one expected.

Information about the end user.

<name>

User name.

User personal number.

Validity time for id.

Validity time for id.

Given name of the end user.

Surname of the end user.

OCSP response for the request. Only available if the authority is set to include a copy of the OCSP response in the SOAP response.

Information about the device used to create the request.

<name>

Platform name. May contain white space.

Platform version.

IP address.

Collect – Status codes

Table 1. Collect status codes
Status code	Description
COMPLETE	The request has been completed.
OUTSTANDING_TRANSACTION	The request has been created, but not yet received by the client.
USER_SIGN	The request has been received by the client, and signing/authentication is pending.

Error codes

Table 2. Error codes
Error code	Description
INVALID_PARAMETERS	Input parameters are missing or invalid.
ACCESS_DENIED_RP	The security configuration of the RP does not allow the requested operation.
SIGN_VALIDATION_FAILED	The PKI validation of the signature for Authentication or Sign failed.
RETRY	Some kind of temporary problem.
INTERNAL_ERROR	Internal error in the service.
UNKNOWN_USER	The end user is unknown or not valid.
ALREADY_COLLECTED	The signature has already been collected; it can only be collected once.
EXPIRED_TRANSACTION	The queried transaction has expired.
TIMEOUT	Not used.
INVALID_DEVICESW	The mobile client is invalid.
ALREADY_IN_PROGRESS	The end user already has a request to process.
USER_CANCEL	The mobile client reported that the end user cancelled the Authenticate or Sign request.
CANCELLED	The order has been cancelled.

WSDL

Reference WSDL code is available at https://showroom.lab.secmaker.com/nias/.