Using REST Directory User Mapping for JIT provisioning

Overview

REST Directory User Mapping is an extension to the Directory User Mapping feature in Ubisecure SSO.

Where Directory User Mapping is implemented by LDAP URL patterns the REST Directory User Mapping calls a REST service that performs the actual mapping from one or more identity attributes to a directory user account.

REST service description

The request to the REST service is configured using a URL pattern with EL expression input parameters.

A successful response from the REST service uses HTTP status 200. Currently any other response status is considered invalid. No mapping is performed for an invalid response and usually this condition results in a Access Denied error.

The response from the REST service must be a well formed XML document. XPath expressions are used to fetch output parameter values from the XML document.

As of Ubisecure SSO version 6.6 it is only possible to describe a HTTP GET request.

URL pattern

Example URL pattern:

ubiloginServiceTemplate: http://services.example.com/mapping?from=$\{inparam1}

Input parameters

Example input parameter:

ubiloginServiceInputParameter: inparam1 ${method.aname}

This inparam1 input parameter description reads the value of the Method Attribute named aname.

Example: if the aname method attribute has the value extuser1234 then the REST HTTP request is:

GET http://services.example.com/mapping?from=extuser1234 HTTP/1.1

Output parameters

Example output parameter:

ubiloginServiceOutputParameter: directory.uniqueid /uniqueid/text()

This output parameter description sets the value of the directory.uniqueid output parameter to the text content value of the XML root element named uniqueid.

Example xml document:

<uniqueid>cn=mappeduser,ou=Users,cn=Ubilogin,dc=localhost</uniqueid>

The directory.uniqueid is a special well known output parameter name. The value of this parameter is used to look up a Directory account for mapping.

Just In Time provisioning – JIT

To implement JIT provisioning the REST service must provide a get-or-create model.

Get-or-create

The REST service first looks for an existing account. If a valid account is found then the service generates a success response with this account's uniqueid.

If no valid account is found then the REST service creates a new account and generates a success response with the new account's uniqueid.

User attributes

Any number of user attributes may be passed to the JIT service to allow provisioning of user profile details such as first name, last name, e-mail etc.

Example:

ubiloginServiceTemplate: http://services.example.com/jit
  ?uid=${uid}&mail=${mail}&givenName=${givenName}&sn=${sn} 
ubiloginServiceInputParameter: uid ${method.uid} 
ubiloginServiceInputParameter: mail ${method.mail } 
ubiloginServiceInputParameter: givenName ${method.givenName} 
ubiloginServiceInputParameter: sn ${method.sn}

It is up to the JIT service implementation to perform any validation and sanity checks of the user attributes.

JIT Updates

When mapping to an existing directory account the JIT REST service may also choose to check and update attributes of the existing account.

Configuration – example

At this time no Management User Interface exists for managing REST services. The configuration entries need to be created using LDIF scripts or using a LDAP editor.

Directory User Mapping object

Use Ubisecure SSO Management to create a Directory User Mapping object. This example uses name mapping. Bind this mapping object to your external authentication method. Also make sure a Directory is selected for the authentication method. In this example Ubilogin Directory is used.

Distinguished name of directory user mapping object

cn=mapping,cn=Server,ou=System,cn=Ubilogin,dc=localhost

Service object

The service object describes the REST URL pattern and output parameters

dn: cn=restservice,cn=Services,ou=System,cn=Ubilogin,dc=localhost  
changetype: add objectClass: top objectClass: ubiloginService cn: 
restclient ubiloginClassname:  
com.ubisecure.ubilogin.restclient.impl.UbiloginRestClientFactory 
ubiloginServiceOutputParameter: directory.uniqueid /uniqueid/text() 
ubiloginServiceTemplate: http://services.example.com/mapping?from=$\{inparam1}

This service expects a input parameter named inparam1. The service returns an output parameter directory.uniqueid with the text value of the XML root element named uniqueid.

Service User Mapping Entry object

Create a service user mapping entry object as a child of the mapping object that was created previously. The name of this object is not significant.

dn: cn=entry1,cn=mapping,cn=Server,ou=System,cn=Ubilogin,dc=localhost 
changetype: add objectClass: top objectClass: 
ubiloginServiceUserMappingEntry cn: entry1 ubiloginDirectoryServiceDN:  
 cn=Ubilogin Directory,cn=Services,ou=System,cn=Ubilogin,dc=localhost  
ubiloginServiceDN:   
cn=restservice,cn=Services,ou=System,cn=Ubilogin,dc=localhost 
ubiloginServiceInputParameter: inparam1 ${method.aname} 

This description calls the REST service named restservice passing a single parameter named inparam1. The value of inparam1 is fetched from a method attribute named aname.

If the output parameters of restservice contain a parameter named directory.uniqueid then directory user mapping to a Ubilogin Directory account is performed.