Getting started with the Lithnet FIM Service REST API

Article
1/17/2024

Introduction

The Lithnet FIM Service REST API is a wrapper for the FIM Service's SOAP/WCF, exposing create, update, delete and search functionality via a series of standard HTTP calls. The API returns JSON-formatted data, making it compatible with a wide range of platforms and services. The Lithnet FIM Service REST API runs as an IIS application. The following guide will show you how to setup the REST API in the following configuration

A new IIS SSL-protected web site which exposes the API at https://<hostname>:<port>/v1/resources
The web service will be protected by SSL and use basic authentication
The web service will be configured to pass through authentication to the FIM service. Requests to the FIM service will be submitted with the user’s security context, and any MPRs governing permissions within the FIM service itself will apply to those requests
A security group will restrict access to the API to only authorized API users

As this is a WCF web service, alternate configurations are possible, but outside the scope of this guide.

Prerequisites

IIS 7.5 or higher with the following features installed
ASP.NET
.NET Extensibility
ISAPI Extensions
ISAPI Filters
Basic Authentication
.NET Framework 4.5
A valid SSL certificate for your API
If you are installing the module on a server other than a FIM Service server, then you will need to copy Microsoft.ResourceManagement.dll from the FIM Service server, and register it in the GAC. Further instructions can be found here https://msdn.microsoft.com/en-us/library/dkkx7f79(v=vs.110).aspx

Procedure

Obtain the current installation package from https://lithnetrmws.codeplex.com/releases
Unzip the package to C:\inetpub\rmws, or another directory where you want to host the web service
Create a new IIS web site pointing to the folder created in the step above. Configure the appropriate hostname, port, and certificate, and ensure the application pool account is set to ASP .NET v4.0 Classic

http://download-codeplex.sec.s-msft.com/Download?ProjectName=lithnetrmws&DownloadId=1480810
From the SSL settings option, configure the web site to require SSL

http://download-codeplex.sec.s-msft.com/Download?ProjectName=lithnetrmws&DownloadId=1480808
Using the authentication feature, enable basic authentication and ASP.NET impersonation, and disable other authentication types

http://download-codeplex.sec.s-msft.com/Download?ProjectName=lithnetrmws&DownloadId=1480806
Create a new security group in active directory. This group will be used to allow users to access the web service
Create a new Authorization Rule to allow only those users to access the API, and remove the default “All Users” rules

http://download-codeplex.sec.s-msft.com/Download?ProjectName=lithnetrmws&DownloadId=1480807
On the web server itself, configure the ISAPI and CGI Restrictions feature to allow ASP.NET v4.0

http://download-codeplex.sec.s-msft.com/Download?ProjectName=lithnetrmws&DownloadId=1480809

Update the assembly redirection information in the web.config file for the version of Microsoft.ResourceManagement dll you have installed on the server.

<runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="Microsoft.ResourceManagement" publicKeyToken="31bf3856ad364e35" culture="neutral" />
        <bindingRedirect oldVersion="0.0.0.0-4.1.3653.0" newVersion="4.1.3653.0" />
      </dependentAssembly>
    </assemblyBinding>
</runtime>

Update the lithnetResourceManagementClient section of the web.config file point to your FIM service endpoint
```
<lithnetResourceManagementClient resourceManagementServiceBaseAddress="http://localhost:5725"/>
```
Restart the web site

The web service is now configured and ready for use. You can go to https://<hostname>:<port>/v1/help to view a list of queries that you can use.

Calling the API

Get a resource

You can retrieve a resource by using either its ObjectID, or an anchor attribute and value pair

GET  /v1/resources/{id}  
GET  /v1/resources/{objectType}/{anchorAttributeName}/{anchorAttributeValue}

If the call was successful, you will recieve a HTTP 200 OK reponse, with a JSON-formatted resource object in the response

{
    "ObjectType": "Person",
    "ObjectID": "64f62191-b255-443b-bbe4-491a66300725",
    "ObjectSID": "AQUAAAAAAAUVAAAAFYLkaG78nJrWb05iFacCAA==",
    "CreatedTime": "2015-06-02T09:13:57.037",
    "Creator": "fb89aefa-5ea1-47f1-8890-abe7797d6497",
    "DomainConfiguration": "1aff46f4-5511-452d-bcbd-7f7b34b0fe14",
    "Manager": "64f62191-b255-443b-bbe4-491a66300725",
    "AccountName": "testuser",
    "DisplayName": "Test User",
    "Domain": "FIM-DEV1",
    "Email": "test.user@lithnet.local",
    "FirstName": "Test",
    "JobTitle": "Test User",
    "LastName": "User",
    "MVObjectID": "{7612EEDA-551E-E511-8CDB-005056B50BB9}",
    "jobTitles": [
        "Test1",
        "Test2"
    ],
}

Updating a resource

To update a resource, you need to use the HTTP PUT verb

PUT  /v1/resources/{id}

In the request body, specify the attributes and values to update

{
    "AccountName":"testuser9"
}

A HTTP 200 OK response will be returned if the object was updated successfully

Deleting a resource To delete a resource, you use the HTTP DELETE verb

DELETE  /v1/resources/{id}

A HTTP 200 OK response will be returned if the object was deleted successfully

Other opreations (Create, Search)

The API also supports create and search operations. For more details, please see the complete project API reference.

Share via