Authentication & Users
-
Authentication
Overview
This page outlines the various authentication mechanisms supported by Unimarket.
At a high level there are two broad categories of authentication:-
Username / Password Authentication
-
Standard Unimarket Authentication
-
Active Directory Authentication
-
Unimarket integrated username/password authentication
-
-
Single Sign On (SSO) Authentication
-
Unimarket integrated SSO authentication
-
CAS SSO
-
SAML SSO
-
1. Username / Password Authentication
Standard Unimarket Authentication
This is the standard/default Unimarket Authentication mechanism. Users will be directed to the Unimarket login screen to enter their user name and password. Users and passwords are managed and stored in Unimarket. Features of this approach:
-
No setup required.
-
All users are administered within Unimarket.
Active Directory / LDAP Authentication
This enables the authentication decision to be made by the customer's Active Directory system. The Unimarket login page will be used to capture the user name and password which will then be sent to Active Directory for authentication.Features of this approach:
- Allows centralized control of a customer's users (e.g. if a user leaves the customer organization and he/she is removed from Active Directory then that user will no longer be able to use Unimarket).
- Users do not need to be created in Unimarket. They will be auto-provisioned when they login for the first time with default role and group settings.
- Users will not have to remember a new set of user names and passwords for Unimarket.
- Customer will have to allow Unimarket to send requests to the Active Directory server. In most cases this simply means opening the standard ldap and ldaps ports in the customer firewall.
- A user with the administrator role in Unimarket will still have to manage the users in Unimarket to configure them with things like Unimarket roles or the customer can make use of the Unimarket user-detail integration to externally manage the users profile.
- The needed information for the Active Directory (LDAP) authentication are:
- Active Directory Domain (Example: college.edu or ad.college.edu)
- Active Directory URL (Example: ldaps://192.162.1.1:port or ldaps://college.edu:port)
Unimarket Integrated Username / Password Authentication
Users will be directed to the Unimarket login screen to enter their username and password. The entered credentials are then sent via a SOAP web service request to an endpoint in the customer environment, which then indicates in it's response message whether the credentials were valid or not.This approach is documented more fully here. Features of this approach:
- Gives the customer full control of user authentication and customer can integrate with any custom backend system they might have.
- A user with the administrator role in Unimarket will still have to manage the users in Unimarket to configure them with things like Unimarket roles or the customer can make use of the Unimarket user-detail integration.
2. Single Sign-On (SSO) Authentication
Single Sign-On is a process that allows network users to access authorized network resources (such as Unimarket) without having to separately log in to each resource. Single Sign-On also gives your organization the ability to integrate with an external identity management system (such as Active Directory) or perform web based single sign on to Unimarket.A typical example is an internal customer portal. Users have to enter their credentials once to get into the portal but are then able to access all the other systems in the organization without further authentication.
Unimarket Integrated SSO Authentication
This enables Single Sign On into Unimarket through web service integration. It is documented more fully here. Features of this approach:
-
Allows completely transparent user authentication.
-
A user with the administrator role in Unimarket will still have to manage the users in Unimarket to configure them with things like Unimarket roles or the customer can make use of the Unimarket user-detail integration.
CAS SSO
This enables Single Sign On into Unimarket through the CAS standard.
Please find more information on the CAS standard here. Features of this approach:- Allows completely transparent user authentication.
- A user with the administrator role in Unimarket will still have to manage the users in Unimarket to configure them with things like Unimarket roles or the customer can make use of the Unimarket user-detail integration.
SAML (Security Assertion Markup Language) SSO
This enables Single Sign-On into Unimarket through the SAML standard.
Please find more information on the SAML standard here. Features of this approach:- Allows completely transparent user authentication.
- Unimarket acts as a SAML Service Provider (SP) and integrates with the customer Identity Provider (IDP).
- A user with the administrator role in Unimarket will still have to manage the users in Unimarket to configure them with things like Unimarket roles or the customer can make use of the Unimarket user-detail integration.
- Alternatively the customer IDP is able to supply user roles, buyer group and organization units in the SAML response message.
Related Articles Authentication user name/password (authentication-request), Authentication token based (authentication-request)
-
-
Authentication token based (authentication-request)
SSO Process
- To authenticate a user with SSO, a request is made to
https://<unimarket tenant url>/sso
. - The following url parameters should be passed:
?unimarket_sso_token=<token>
- If the Tenant the user is attempting to login to has SSO enabled, Unimarket makes a Web Service call to the configured Delegated Authentication Authority, asking it to validate the token or username and password.
- The Web Services call (
authentication-request
) passes the token and requestIp to the Delegated Authentication Authority (requestIp is the IP address from where the login request originated). The Delegated Authentication Authority must implement this Web Service and be accessible by Unimarket servers. - The implementation of the Web Service validates the passed information and returns the appropriate response (
authentication-response
). - If the response indicates successful authentication then the login process continues, a new session is generated, and the user proceeds to the application.
Token Based
1/2. A User logs in to the customers intranet or internal portal. The user then requests the web page from where he will initiate the login to Unimarket. During the process in which this web page is sent to the users browser a request is made to the customers 'Token Generator' to generate a unique token which is associated with the logged in user. This token is then used to create a login link on the web page. The required parameters for this link are described above and the resulting url would look something like
http://<customer>.unimarket.com/sso?unimarket_sso_token=<generated token>
.3. The user clicks on the login link described above and sends the generated token to Unimarket.
4. Unimarkets 'Authentication Manager' receives the SSO request and determines whether the given customer is configured to use SSO. If the customer has been configured to use SSO then the 'Authentication Manager' sends an
authentication-request
Web Service message to the customers 'Delegated Authentication Authority' via configured integration url.5. The customers 'Delegated Authentication Authority' receives the token (generated in step 1) and verifies that it is valid and which user it is associated with. An
authentication-response
Web Service message is generated and returned to Unimarket. If the token was valid this response contains the username of the user to be granted access to Unimarket. If the token is not valid this response contains information about why it is not valid.6. Unimarket evaluates the
authentication-response
and determines if the user is granted access to Unimarket.Tip on token generation
To ensure greater security and reduce the risk of a token from being re-used customers typically choose to give the tokens a limited lifespan during which it is valid.
Technical Information
Technical documentation and examples relating to the full list of Unimarket webservice interfaces can be found below:
- To authenticate a user with SSO, a request is made to
-
Authentication user name/password (authentication-request)
SSO Process
- The user credentials can either:
- Be Passed in the request
https://<unimarket tenant url>/sso?unimarket_sso_username=<username>&unimarket_sso_password=<password>
. - Or collected using the Unimarket login screen
- Be Passed in the request
- If the Tenant the user is attempting to login to has SSO enabled, Unimarket makes a Web Service call to the configured Delegated Authentication Authority, asking it to validate the username and password.
- The Web Services call (
authentication-request
) passes the username/password and requestIp to the Delegated Authentication Authority (requestIp is the IP address from where the login request originated). The Delegated Authentication Authority must implement this Web Service and be accessible by Unimarket servers. - The implementation of the Web Service validates the passed information and returns the appropriate response (
authentication-response
). - If the response indicates successful authentication then the login process continues, a new session is generated, and the user proceeds to the application.
Notes for customers using the Unimarket Connector
A Unimarket customer (Tenant) can only be configured with one integration url. This means if a customer has chosen to use the Unimarket connector for integration (e.g. for order integration) and the customer also wishes to use SSO then the url for the Web Service described above must be the same as the connector url. This in turn means that SSO must be handled by the Unimarket connector (the Unimarket connector can then be configured to authenticate with an Active Directory server or to check credentials against a database).
Username / Password Based
Technical Information
For technical documentation and examples relating to the full list of Unimarket webservice interfaces see:
- The user credentials can either:
-
Setting up SAML SSO
Step 1
The first step to start the SAML SSO setup is for Unimarket to provide the credentials for the two environments to the technical team at the Customer end, please note they are slightly different.
We recommend that the SAML SSO gets configured and tested in Demo before continuing on to Production which is the live environment.Replace the 'customerdomain' section of the URL with the customer's domain name.
Credentials for Demo
Login URL : https:// customerdomain.unimarket-demo.com/saml/login
Entity ID : https:// customerdomain.unimarket-demo.com/saml/sp
Credentials for Production
US
Login URL : https:// customerdomain.unimarket.com/saml/login
Entity ID : https:// customerdomain.unimarket.com/saml/sp
AU
Login URL : https:// customerdomain.unimarket.com.au/saml/login
Entity ID : https:// customerdomain.unimarket.com.au/saml/sp
NZ
Login URL : https:// customerdomain.unimarket.co.nz/saml/login
Entity ID : https:// customerdomain.unimarket.co.nz/saml/sp
Step 2
The Customer needs to provide Unimarket with the SAML IDP Metadata, either by providing a URL or by providing the XML file. Once Unimarket has been provided with this it will be plugged into the authentication setup for the Customer community on the Unimarket platform. This will in turn generate the SP Metadata for Unimarket to share with the Customer to complete their setup.
This process will establish the ‘handshake’ and a test can be done to ensure the Single Sign On authentication works.Note: Unimarket requires the Metadata first. We cannot generate our metadata without first plugging in the customers'.
Step 3
If applicable - Ensure the correct attributes are set and mapped at both the Customer end and Unimarket.
Determine if Auto Provision should be on or off, Create Users on or off - depending on where the users are managed.
Note: The authentication age also needs to be confirmed and matched on both ends, please confirm what the Customer has it set to on their side.
-
User API (JSON)
Customers can send Unimarket new and updated users in real time via a JSON REST interface. It is also possible to submit an initial bulk load of users through the same interface (one user per request).
The JSON format is used by all the below operations. Get User responds with it; the other operations expect it as input.
Unimarket exposes three operations through this REST interface:
- Get User - Fetch an existing user by username. The Customer can use this for users for which it does not know the Unimarket User UUID to determine if it should send a create or update request
- Create User - Create a new user. The Customer can use this for new users after calling GET to confirm the user does not yet exist in Unimarket
- Update User - Update an existing user. The Customer can use this for users for which it already knows the Unimarket User UUID.
The URL for the API is: api.unimarket.com (or .co.nz, com.au)
Message Details
Name
Data Type
Description
id
string(255)
Unimarket unique ID for a user (stays the same even if the username changes). Unimarket will generate this ID if it is not provided for the create operation but the call needs to ensure it is unique and it cannot be changed.
username
string(255)
Username
externalId
string(255)
An alternative username. This will hold the user’s external ID.
firstName
string(255)
The user’s first name.
lastName
string(255)
The user’s last name.
displayName
string(255)
A display name to show when searching for buyers to reassign to. This could include the buyer’s name, email address and/or default location code
email
string(255)
The user’s email address.
phone
string(255)
The user’s phone number.
enabled
boolean
Users whose accounts are not enabled will be prevented from logging into Unimarket.
organisationsUnits
array of object
One per Organisation Unit. These must be unique.
organisationsUnits.code
string(255)
Organisation Unit codes, each of which is a string(255)
roles
array of object
One per role.
roles.code
string(255)
One of the role values defined in User Detail Request in Unimarket Helpdesk.
buyerGroups
array of object
One per buyer group that the user is a member of. These control a user’s access to suppliers and catalogues.
buyerGroups.code
string(255)
Buyer Groups
attributes
array of object
One per custom attribute
attributes.name
string(20)
Name of the attribute
attributes.value
string(20)
Value of the attribute
approverGroups
array of object
One per approver group that the user is a member of.
approverGroups.code
string(255)
Approver Groups
Example message
{
"id": "278d1da1-3ebd-11e8-9726-9cb6d0f65f6c",
"username": "jsmith001",
"externalId": "john-smith-123",
"firstName": "John",
"lastName": "Smith",
"displayName": "John Smith john.smith School Administrative Officer",
"email": "john.smith@community.com",
"phone": "(00) 1234-5678",
"enabled": true,
"organisationUnits": [
{
"code": "1010"
},
{
"code": "2256"
}
],
"roles": [
{
"code": "COMMUNITY_BUYER"
},
{
"code": "COMMUNITY_RFQ_CREATE"
}
],
"buyerGroups": [
{
"code": "GENERAL"
},
{
"code": "CORPORATE"
}
],
"attributes": [
{
"name": "Contractor",
"value": "true"
}
]
}Standard Headers
HTTP Headers will be required as part of the message to identify the source of message (Community). Two headers will be required. The user upload will only be processed if both these headers are correct.
- Unimarket-Account-ID, this value will be supplied by Unimarket and is used in all REST messages sent to Unimarket as a unique (but not secret) identifier for the Customer in Unimarket.
- Unimarket-API-Key, Similar to a password. The API Key will be generated inside Unimarket and linked to this customer. This can also be restricted to only work from specific IP addresses.
HTTP Status Codes
Unimarket will respond with an HTTP status code indicating success or failure of the operation.
- 200 for success
- 400 for a failure, along with a message describing the reason for failure.
- 401 for an authentication failure.
- 404 for a GET or PUT (update) request for a user that does not exist.
Get User Operation
The Get User operation will be a simple GET request with the requested username to which Unimarket will respond with either a JSON representation of the user or a 404 error code if the user does not exist.
A sample Get User JSON GET request will look similar to this:
GET /v1/users/username/jsmith001 HTTP/1.1
Host: api.unimarket.com
Unimarket-Account-ID: <account id>
Unimarket-API-Key: <api key>Create User Operation
The Create User operation will be a POST request with a JSON user in the body of the message. The id field is optional, if it is provided it must be unique, if it is not provided, Unimarket will generate a unique id. Unimarket will respond with the full JSON of the newly created user. Most of this will be the same data just uploaded but there may be additional fields and potentially some data may have been modified as result of constraints (e.g. non-critical fields could be trimmed rather than rejecting the request) or business rules (e.g. all users might automatically get a role added) Importantly, the JSON response will contain the id field that Customer can remember for future updates.
A sample Create User POST request will look similar to this:
POST /v1/users HTTP/1.1
Host: api.unimarket.com
Content-Type: application/json; charset=utf-8
Content-Length: <size of json file>
Unimarket-Account-ID: <account id>
Unimarket-API-Key: <api key>
<JSON DATA>Update User Information
The Update User operation will be a PUT request with a JSON user in the body of the message. The user to update will be identified by the id field in the JSON message.
A sample Update User PUT request will look similar to this:
PUT /v1/users HTTP/1.1
Host: api.unimarket.com
Content-Type: application/json; charset=utf-8
Content-Length: <size of json file>
Unimarket-Account-ID: <account id>
Unimarket-API-Key: <api key>API Key
Unimarket will generate a unique API key that is specific to the customer.
Unimarket needs to generate the key for you which will be done during integration setup.
This API Key can be linked to a specific IP address(es) and then only requests from those address(es) will be accepted for the API Key, others will be rejected. By configuring this with the IP address of the Customer, only requests coming from that server will be accepted.
-
User Detail Request (user-detail-request)
Overview
The user-detail-request and user-detail-response integration points are used when a buying organization wishes use an external system such as an Active Directory or their ERP system as the master source of user information. During the login process a user-detail-request is sent from Unimarket to the external system. This contains the details of the person attempting to login. The external system then responds with the user-detail-response which provides Unimarket with the valid user details. Access to Unimarket will then be granted/denied based on the details provided from the external system.
Note: If this integration is enabled the external system is the master for all user information. Each time the user-detail-response message provides Unimarket with user details these will replace anything previously held for that user inside Unimarket. This integration allows an organization to centrally manage their user information within an Active Directory (or similar) and have this information updated into Unimarket. It removes the need to manage users inside Unimarket.
Setting up User Details Integration
If you want to use a central repository to manage user details such as an Active Directory then you will need to store some specific information about the Unimarket user so it can be passed to Unimarket within the user-detail-response. Below is a list of the values that need to be stored.
Unimarket User Roles
Role Integration Syntax Definition Approval Administrator
COMMUNITY_APPROVALS
View and manage community approval information and configurations.
Bid Request
COMMUNITY_RFX_CREATE
Initiate bidding events (RFQ, RFP, RFI) through the sourcing module.
Bid Request Collaboration
COMMUNITY_RFX_COLLABORATION_CREATE
Gives users with the Bid Requests role the ability to select collaborators when creating a bid request.
Browser
COMMUNITY_BROWSER
Shop the marketplace and create incomplete requisitions to reassign to Buyers within their org unit. The Browser role can not be used with the Buyer Role.
Buyer
COMMUNITY_BUYER
Shop the marketplace, create requisitions and complete reassigned requisitions from users with the Browser role.
Community Administrator
COMMUNITY_ADMIN
Full community administration rights.
Community Features
COMMUNITY_FEATURES
Manage administrator functions that relate to the community features, such as general community preferences, ordering and checkout preferences and invoice matching preferences.
Community Management
COMMUNITY_MANAGEMENT
Manage administrator functions that relate to the community setup and master data.
Community Profile
COMMUNITY_PROFILE
Manage administrator functions that relate to the community profile, such as community name, branding, welcome text, links, community email addresses and more.
Community Supplier Administrator
COMMUNITY_SUPPLIER_ADMIN
Manage supplier information, categories, invitations and connections.
Contracts Administrator
CONTRACTS_ADMIN
Allows users to make changes and edit a contract as if they were the owner of the contract without being a member of the contract. Allows users to able to access the Documents and Transactions tabs without being a member.
Create Blanket Order
COMMUNITY_BLANKET_ORDER_CREATE
Create Blanket Orders for suppliers.
Create Contracts
COMMUNITY_CONTRACTS_CREATE
Ability to Create contracts and link or unlink transactions (reqs and orders) to a contract.
Create Buyer Invoices
COMMUNITY_INVOICE_BUYER_CREATE
If community PO Flip is enabled, a user with the Create Buyer Invoices role can use the 'Invoice Order' feature to create invoices for any of their own orders already in Unimarket. If Retrofit Invoices are enabled a user with this role will also be able to create invoices for orders that are not yet in Unimarket for buyer approval.
Create Invoices
COMMUNITY_INVOICE_CREATE
If community PO Flip is enabled, a user with the Create Invoices role can use the 'Invoice Order' feature to create invoices for orders already in Unimarket. If Retrofit Invoices are enabled a user with this role will also be able to create invoices for orders that are not yet in Unimarket for buyer approval. Users can also force match invoices.
Escalate Approval
COMMUNITY_APPROVAL_ESCALATE
Escalate approvals for viewable requisitions.(Community Administration role also gives this ability)
Expenses
COMMUNITY_EXPENSES
Create expense claims.
On Behalf Of
COMMUNITY_ON_BEHALF_OF_BUYER
Create requisitions on behalf of any other user in the community.
On Behalf Of Expenses
COMMUNITY_EXPENSES_OBO
Create expense claims on behalf of other users. On Behalf of Receiving
COMMUNITY_ON_BEHALF_OF_RECEIVING
Receive orders on behalf of other users. User will see full community open receiving. Ideal for Central Receiving staff.
Over Receiving
COMMUNITY_OVER_RECEIVING
Allows users to receive more than the ordered quantity. RFQ
COMMUNITY_RFQ_CREATE
Initiate simple RFQs with suppliers.
Supplier Request Admin
COMMUNITY_SUPPLIER_REQUEST_ADMIN
Manage new supplier requests from end users. The requests can be turned into invitations if the supplier is not currently in the marketplace.
User Administrator
COMMUNITY_USER_ADMIN
Manage community users including user details and roles. The User Administrator role cannot allocate a user the Community Administrator role.
User Support
COMMUNITY_USER_SUPPORT
Allows User to Switch into other users to assist with support. Not able to make changes while switched into other users.
View Contracts
COMMUNITY_CONTRACTS_VIEW
View any existing contract leadsheets entered for your community. User must be a member of a contract to view the contract documents.
View Tax Profiles
COMMUNITY_TAX_PROFILE_VIEW
View Tax Profiles (W9/W8BEN forms) submitted by suppliers.
View Transactions
COMMUNITY_TRANSACTION_VIEW
View all transactions for the entire community. Users with this role can view any purchase throughout the entire community. Without this role, users may only see transactions they are involved in. Technical Information
For technical documentation and examples relating to the full list of Unimarket webservice interfaces see: