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 3rd 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): 

ParameterDescriptionDatatypeRequired?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): 

ParameterDescriptionDatatypeRequired?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 

Response: 

Get User: GET #

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

Endpoint: 

Request (xml, json): 

ParameterDescriptionDatatypeRequired?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