• Authentication

    Overview

    This page outlines the various authentication mechanisms supported by Unimarket.
    At a high level there are two broad categories of authentication:

    1. Username / Password Authentication

      • Standard Unimarket Authentication

      • Active Directory Authentication

      • Unimarket integrated username/password authentication

    2. 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

    1. To authenticate a user with SSO, a request is made to https://<unimarket tenant url>/sso.
    2. The following url parameters should be passed: ?unimarket_sso_token=<token>
    3. 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.
    4. 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.
    5. The implementation of the Web Service validates the passed information and returns the appropriate response (authentication-response).
    6. 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:

    Integration > General

  • Authentication user name/password (authentication-request)

    SSO Process

    1. The user credentials can either:
      1. Be Passed in the request https://<unimarket tenant url>/sso?unimarket_sso_username=<username>&unimarket_sso_password=<password>.
      2. Or collected using the Unimarket login screen
    2. 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.
    3. 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.
    4. The implementation of the Web Service validates the passed information and returns the appropriate response (authentication-response).
    5. 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:

    Integration > General

  • 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:

    Integration > General