Single SignOn using User Authentication Service (UAS)

Introduction   #

This document is designed to give developers of third-party systems, instructions on how to manage eCert users through the User Authentication Service (UAS). The link to the UAS swagger page is as follows: 

• https://uas.ecert.co.za/swagger 

Please Note: This is the Live URL. There is no UAS on QA so any submission will be on the live database. 

How to Connect  #

Refer to UAS How to Connect document. 

Web API Endpoints   #

Supported Formats  #

Messages (data) are delivered via two response types namely XML and JSON. In order to receive data in a specific format, you need to specify the content type in the response header as such: 

Content-Type: ‘application/xml’ 

Or  

Content-Type: ‘application/json’ 

Available Methods  #

This section demonstrates some of the endpoints using a 3^rd party tool, Swagger. This tool will help the user to get a feel of what the endpoint parameters look like as well as view the responses in different formats. Below are screenshots and tables to show how the request and responses look like for the different endpoints. 

Register: POST #

Used to register new users using the User Authentication Service  

Endpoint: 

Request (xml, json): 

Parameter	Description	Datatype	Required?	Example/ Ref
Email	Unique email address	String	Yes	e.g. test@test.com
Password	Password used to login	String	Yes	Password Value
FirstName	First name as per ID document	String	Yes	Jess
LastName	Last name as per ID document	String	Yes	Jay
CellNo	User’s mobile number	String		0111233456
PhoneNo	User’s phone number	String		0111233456
Company	Company user belongs to	String	Yes	ABC Ltd
IDNum	Valid South African ID	String	Yes	202012345678
PassportNo	Passport Number for non-SA users	String	No	PN123
Gender	User’s gender	String		PN123
Title	User’s title	String		Mr
PassportDocument	Passport document attachment object:  ContentLength (int) ContentType (string) FileName (String) InputStream{ _identity:{ } }	Object

Response: 

Update User: POST #

Used to update existing user information using the User Authentication Service  

Endpoint: 

Request (xml, json): 

Parameter	Description	Datatype	Required?	Example/ Ref
UserId	Unique ID for user	String	Yes	12334567ed
Email	Unique email address	String	Yes	e.g. test@test.com
FirstName	First name as per SA ID document	String	Yes	Jess
LastName	Last name as per SA ID document	String	Yes	Jay
CellphoneNumber	User’s mobile number	String	No	0711234567
PhoneNumber	User’s phone number	String	No	0111233456
Company	Company user belongs to	String	Yes	ABC Ltd
IdNumber	Valid South African ID	String	Yes
PassportNumber	Passport Number for non-SA users	String	No	PN234
Gender	User’s gender	String	Yes	Male
Title	User’s title	String	No	Dr
CBRBusinessId	ID of business that the user belongs to	Integer	No	1

Response: 

Get User: GET #

Used to retrieve a registered user’s information from the User Authentication Service  

Endpoint: 

Request (xml, json): 

Parameter	Description	Datatype	Required?	Example/ Ref
Email	Email address for user	String	Yes	e.g.  test@test.com

Response: 

Code Snippets  #

Client-Side Examples with AJAX  #

Following are code snippet examples to illustrate how to call the UAS endpoints using AJAX on the Client side. The examples show how clients can specify which format they want to receive as a response between Json and XML. 

Json Format 

Server-Side Examples with C#  #

The examples below show C# code snippets of how to register a user on UAS, as well as how to get UAS user information. 

Get Access Token Method #

Register UAS User Endpoint Code #

The method below shows how to register a new user on UAS by posting the user model (see endpoints section for object structure). 

Get UAS User Endpoint Code #

The method below shows how to get user information from UAS using the email parameter. 

Code in Practice (Examples from PhytClean)  #

The following points explain, with code snippets and images, how to create a registration form in your own application and submit the user details to a central repository, the User Authentication Service User tables. In future we will refer to your application as MyApp. 

The user completes the registration form (with UAS fields and application specific fields) in MyApp. The UAS specific fields are submitted to the UAS and on successfully registration a unique UASUserID is returned. This can then be stored in the MyApp user table along with any additional fields that were requested during registration that are specific to MyApp. 

PhytClean User Table Structure   #

As shown in the picture below, the PhytClean user table only stores minimal user fields that are only relevant to PhytClean and the rest of the user information can be reference from UAS using the UASUserID. 

Registration Page  #

The picture below shows the PhytClean registration page. The fields that are ticked are the ones that are stored in the User table in the User Authentication Service database. The rest of the fields are stored in the PhytClean user table including the UASUserID. 

Code Samples from PhytClean   #

The UAS base URL is stored in config file – https://uas.ecert.co.za 

UAS User View Model #

The code snippet below shows the registration fields and validations.

Please note: For all code snippets below, the DTO objects store the responses returned from the relevant endpoints. For example: The RegisterDTO is an object that stores the response returned from the Register endpoint. 

UAS Registration Method #

The code snippet below demonstrates the process of registering a user through the UAS. Once a user is successfully registered a confirmation email is sent to the email account entered and a response is sent back to PhytClean with user data which includes the UASUserID. 

The user will have to click on the link provided in the confirmation email to verify that their email is valid. 

Login Method #

Once the user has been successfully registered and they have confirmed their email, they can log into PhytClean or any of the UAS authenticated systems. The code snippet below shows the PhytClean code for logging in. 

Logout Method #

The code below details how to log the user out of the application. 

Forgot Password Method #

If a user forgets their password, they can request for it to be reset. The code snippet below shows the PhytClean code that initiates the password reset on UAS. 

All methods available on the swagger page use the same principle. As long as the user has a valid token you can POST/GET data from the database using an endpoint and the response can then be consumed as needed.  

APPENDIX 1 

References 

• UAS Web API-How to Connect