Authentication service

<< Click to Display Table of Contents >>

Navigation:  Signant web services >

Authentication service

The authentication service give access to the Signant ID portal for identification by means of the underlying trusted service providers supported by Signant. This API documentation describes the authentication web services functions in order to successfully create and validate authentication requests.

 

Web service endpoint

Web service description endpoint in the testing environment T3: https://test3.signant.no/Auth/AuthService.svc?wsdl

 

 

The service operates in two layers; the WS layer for initializing and validating the authentication requests, and a web layer where the user interacts with the service.

The integrator communicates with the “Signant authentication service” by a secure WS connection. The integrator must make sure the integrator credentials (DistributorID, AccessCode, TrackingID) are kept safe and measures should be made to avoid disclosing this data to any other parties.

 

 

The authentication sequence work flow

The following sequence diagram illustrates the work flow of an authentication request.

 

 

Auth_SequenceDiagram

 

Authentication steps

1)User initiates an authentication request.

2)Integrator initializes new Authentication.

3)URL to authentication is returned.

4)User is redirected to authentication page.

5)After successful authentication the user is redirected back to Integrator web.

6)The redirect back (step 5.) should trigger a call to the “authentication status check” function call from the Integrator system.

7)Signant WS returns authentication status.

8)If authentication was successful the user is logged in to the Integrator web.

 

 

Code sample for InitAuth

 

Web service functions

This web service exposes the following functions:

Name

Description

InitAuth

For creating a new authentication session.

GetAuthStatus

Returns the status for the authentication session.

 

InitAuth

Used to create a new authentication session. Sample request.

InitAuth parameters

Name

Type

Description

Required

DistributorID

String

For authentication (Provided by Signant)

Yes

AccessCode

String

For authentication (Provided by Signant)

Yes

AuthOptions

AuthOptions

Options for the Auth session

Yes

 

 

InitAuth AuthOptions

Name

Type

Description

Required

AuthTypes

AuthType[]

Array of authentication types to be made available to the user (1)

Yes

NextUrl

String

Redirect Url after successful authentication (2)

Yes

CancelUrl

String

Redirect Url after cancelled or failed authentication

Yes

ReturnSSN

Bool

Return SSN after authentication (3)

Yes

1)See AuthOptions-AuthTypes for a list of available authentication types.

2)RequestId will be added to the querystring before redirect: https://abc/auth will become https://abc/auth?requestid=xyz.

3)Access to norwegian ssn require legal basis.

 

 

InitAuth output: InitAuthResponse

Name

Type

Description

StatusID

Int

Status code of the authentication session (1)

StatusText

String

Status of the authentication session

AuthenticationUrl

String

Unique Url to the authentication

RequestID

String

Request Id for this authentication session

TrackingID

String

Tracking Id for this authentication session

1) See Authentication Status codes for a possible values.

 

GetAuthStatus

Call this function to receive authentication session status. See sample request.

GetAuthStatus parameters

Name

Type

Description

Required

DistributorID

String

Provided by Signant

Yes

AccessCode

String

Provided by Signant

Yes

RequestID

String

RequestID from InitAuth

Yes

TrackingID

String

TrackingID from InitAuth

Yes

 

GetAuthStatus output - GetAuthStatusResponse

Name

Type

Description

StatusID

Int

Status code of the authentication session (1)

StatusText

String

Status of the authentication session

State

String

State of the authentication session (2)

TrackingID

String

Echo of incoming parameter: TrackingID

UserUniqueID

String

Unique id for this person

UserFullName

String

Full name of authenticated person

UserFirstName

String

First name of authenticated person

UserLastName

String

Last name for authenticated person

UserDOB

String

Date of birth of authenticated person DD.MM.YYYY

UserSSN

String

Social security number of user (3)

1. See Authentication - Status codes values

2. See Authentication - Session states for values.

3. Account requires proof of permission from The Norwegian Data Protection Authority (Datatilsynet)

 

AuthOptions - AuthTypes

AuthTypes values:

AuthType

Description

NO_BankID

Norwegian BankID, read more at www.vipps.no

NO_BankID_Mobile

Norwegian BankID, read more at www.vipps.no

NO_BuyPass

Norwegian Buypass, read more at www.buypass.no

 

 

Authentication Status codes

Authentication status code can have the following values:

StatusID

Description

0

OK

2001

Wrong DistributorID and/or AccessCode

2002

Invalid value(s) in options object – see status StatusText for details

4000

General error – see StatusText for details

4001

Invalid or expired RequestID

4002

Wrong RequestID or TrackingID

4003

Session expired

 

 

Authentication Session state

Authentication session can have the following states

State

Description

N/A

Session does not exists

NOT_STARTED

Session create but not started

STARTED

Authentication prossess started

INITIALIZED

Authentication provider handshake initialized

PROCESSING

Authentication in process

CANCELED

Authentication canceled by user (1)

FAILED

Authentication failed, see StatusText value for more details

EXPIRED

Session expired

COMPLETED

Authentication completed successfully

1. Cancelled sessions cannot be reused, new session must be requested using InitAuth.

 

 

Sample requests

The sample requests and responses have been shortened down for readability and will therefore not work “as is“, you will have to replace all required fields with correct data before trying to send a request to the service.

InitAuth sample request

 

The request above will return the following result

 

GetAuthStatus sample request 

 

The request above will return the following result